`nupp.profile`

Two profiling channels: one for where the time went, one for whether it went there compiled.

local profile = nupp.profile

with session = profile.sample({intervalMs = 5}) do
    render()
    local report = session:stop("profile.out")
    print(report.samples, report.stacks)
end

profile.sample is the statistical sampler. A timer interrupts the program and writes down where it was; what comes back is collapsed-stack text, the format speedscope.app, FlameGraph.pl and inferno all read.

profile.trace watches the JIT give up. It aggregates trace aborts, so blacklisted hot code, a bytecode the compiler will not record, and traces that grew past a limit all become rows rather than silence. That is the question a sampler cannot answer and the one that usually matters here: code the JIT refused is an order of magnitude slower than code it took, and nothing says so out loud.

Both channels attribute work through nupp.profile.zone, so a sample or an abort carries the zone path that was open when it happened. Both are process-wide rather than per-coroutine, and at most one session of each kind runs at a time.

Neither is free. A sample session pays a timer interrupt, a stack walk and a table write at every interval; a trace session pays a callback at every abort, inside the compiler. A session is a nupp.Closeable, so a with ends it where its block does: stop returns the report, and a session nothing stopped is closed without one.

See Profiling for reading a report, and LuaJIT trace checking for finding the same aborts without running the program.

Submodules

Module	Description
`nupp.profile.trace`	Stable identities shared by static trace checking and the opt-in runtime collector.
`nupp.profile.zone`	Gated LuaJIT profiler zones: the stack work is skipped until a profiler asks for it.

Module contents

Types

Type	Kind	Description
`AbortSite`	record	A place the JIT gave up, and how often it did.
`Sample`	record	A distinct stack, and what landed on it.
`SampleOptions`	type	What profile.sample collects, and how much of it.
`SampleReport`	record	What a sample session saw, as SampleSession:stop returns it.
`SampleSession`	record	A running sampler, as profile.sample returns it.
`Session`	interface	A running profiling session whose declaration chooses the report stop returns.
`Severity`	type	How much an abort is worth reading.
`SourceSample`	type	Lua leaf samples attributed to a source line.
`TraceOptions`	type	What profile.trace counts.
`TraceProfile`	record	The exact recorder configuration used to normalize a trace report.
`TraceReport`	record	What a trace session saw, as TraceSession:stop returns it.
`TraceSession`	record	A running trace-abort collector, as profile.trace returns it.

Functions

Function	Kind	Description
`sample`	function	Starts sampling.
`trace`	function	Starts collecting trace aborts.

Types#

`AbortSite`record#

record profile.AbortSite ...

A place the JIT gave up, and how often it did.

A row of a TraceReport, built at stop.

Members

Name	Kind	Description
`severity`	field	How much it is worth reading.
`count`	field	Times this exact severity, reason, location and zone fired.
`reason`	field	The reason, from jit.vmdef.traceerr.
`reasonId`	field	Stable compiler identity and classification for the raw VM reason above.
`reasonClass`	field	What the identity is worth acting on: a blocker cannot record at all, a risk may or may not sit on a hot path, and a...
`rawReason`	field	The VM's own text, before the registry mapped it.
`location`	field	":" of the function being recorded when it aborted.
`rootLocation`	field	Where the root trace began, including when recording entered a library.
`zonePath`	field	The zone path that was open, "" when none was.

`severity`field#

severity: profile.Severity

How much it is worth reading.

`count`field#

count: integer

Times this exact severity, reason, location and zone fired.

`reason`field#

reason: string

The reason, from jit.vmdef.traceerr. An unrecordable bytecode is rendered with the opcode's name.

`reasonId`field#

reasonId: string

Stable compiler identity and classification for the raw VM reason above.

`reasonClass`field#

reasonClass: 'blocker' | 'risk' | 'stop'

What the identity is worth acting on: a blocker cannot record at all, a risk may or may not sit on a hot path, and a stop is trace formation working as designed.

`rawReason`field#

rawReason: string

The VM's own text, before the registry mapped it.

`location`field#

location: string

":" of the function being recorded when it aborted.

`rootLocation`field#

rootLocation: string?

Where the root trace began, including when recording entered a library.

`zonePath`field#

zonePath: string

The zone path that was open, "" when none was.

`Sample`record#

record profile.Sample ...

A distinct stack, and what landed on it.

A row of a SampleReport, built at stop. The five state counts sum to count.

Members

Name	Kind	Description
`zonePath`	field	The zone path the samples were taken under, "" when none was open.
`stack`	field	The stack as dumpstack rendered it, ";" between frames, outermost first.
`count`	field	Samples on this stack, in every VM state.
`compiled`	field	Samples running compiled machine code.
`interpreted`	field	Samples in the interpreter.
`cCode`	field	Samples inside a C function.
`collecting`	field	Samples in the garbage collector.
`compiling`	field	Samples inside the JIT compiler itself.

`zonePath`field#

zonePath: string

The zone path the samples were taken under, "" when none was open.

`stack`field#

stack: string

The stack as dumpstack rendered it, ";" between frames, outermost first.

`count`field#

count: integer

Samples on this stack, in every VM state.

`compiled`field#

compiled: integer

Samples running compiled machine code.

`interpreted`field#

interpreted: integer

Samples in the interpreter.

`cCode`field#

cCode: integer

Samples inside a C function.

`collecting`field#

collecting: integer

Samples in the garbage collector.

`compiling`field#

compiling: integer

Samples inside the JIT compiler itself.

`SampleOptions`type#

type profile.SampleOptions = {
    --- Milliseconds between samples; 10 by default, which is 100 a second. Must be
    --- between 1 and 2147483647, the range LuaJIT's profiler accepts. Below about 10
    --- the timer starts taking real time away from the thread it is measuring, so
    --- lower it for a short window and read the result knowing that it was paid for.
    intervalMs: integer?,

    --- How many frames to walk per sample; 16 by default. Must be between 1 and
    --- 2147483647, the range LuaJIT's stack dumper accepts. The walk is linear in
    --- this and it happens on the interrupted thread, so raise it only when a
    --- specific question needs the depth.
    stackDepth: integer?,

    --- Keep only the samples taken under a zone path starting with this, so
    --- "frame/render" reads as that subtree alone.
    ---
    --- Applied at `stop` rather than while sampling: narrowing it costs nothing at
    --- runtime, and widening it afterwards is not possible, because the prefix is fixed
    --- when the session starts.
    zone: string?,

    --- The module the program starts at, as a stack frame names it. Everything below
    --- the outermost frame from it is dropped.
    ---
    --- A profiler samples the whole stack it is embedded in, and what is under the
    --- program, the loader that read it and the pcall that guards it, is not the
    --- program. Naming its module cuts the report back to it.
    ---
    --- Frames read "<module>:<name>", so the module is the part to give. A stack with
    --- no frame from it is kept whole rather than emptied, and two stacks that differ
    --- only below the root become one, their counts summed.
    root: string?
}

What profile.sample collects, and how much of it. Every field is optional.

`SampleReport`record#

record profile.SampleReport ...

What a sample session saw, as SampleSession:stop returns it.

tostring on it is the collapsed-stack text, so it prints and pipes directly.

Members

Name	Kind	Description
`intervalMs`	field	The interval the session ran at, so the sample counts can be read as time.
`samples`	field	Samples recorded, after the zone filter.
`sourceSamples`	field	Lua leaf locations, ordered by file and line.
`stacks`	field	Distinct stacks they fell on.
`text`	field	One line per stack: semicolon-separated frames, a space, then the sample count.
`__tostring`	metamethod

`intervalMs`field#

intervalMs: integer

The interval the session ran at, so the sample counts can be read as time.

`samples`field#

samples: integer

Samples recorded, after the zone filter.

`sourceSamples`field#

sourceSamples: {profile.SourceSample}

Lua leaf locations, ordered by file and line. Their sum can be less than samples because native VM states have no reliable Lua source location.

`stacks`field#

stacks: integer

Distinct stacks they fell on.

`text`field#

text: string

One line per stack: semicolon-separated frames, a space, then the sample count. Ordered by count descending. Empty when nothing was sampled, which a short session and a zone prefix that matched nothing both produce.

`__tostring`metamethod#

__tostring: function(self): string

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`string`

`SampleSession`record#

record profile.SampleSession is profile.Session, nupp.Closeable ...

A running sampler, as profile.sample returns it.

Live until stop or close, and there is at most one at a time. Held by a with, it is closed where the block ends, so the timer never outlives the question.

Members

Name	Kind	Description
`Report`	field
`intervalMs`	field	The interval it was started at.
`zoneFilter`	field	The zone prefix stop will filter by, or nil for all of them.
`root`	field	The module stop will cut the stacks back to, or nil to keep them whole.
`paused`	field	Whether recording is suspended.
`stopped`	field	Whether stop has run.
`aggregate`	field	Samples so far, by zone path and then by stack.
`sourceSamples`	field	Lua leaf locations counted separately in each zone, before filtering.
`pause`	method	Stops recording without ending the session.
`resume`	method	Resumes recording.
`stop`	method	Ends the session and reports what it saw.
`close`	method	Ends the session without a report, which is what leaving its with does.

`Report`field#

Report: associatedDecl

`intervalMs`field#

intervalMs: integer

The interval it was started at.

`zoneFilter`field#

zoneFilter: string?

The zone prefix stop will filter by, or nil for all of them.

`root`field#

root: string?

The module stop will cut the stacks back to, or nil to keep them whole.

`paused`field#

paused: boolean

Whether recording is suspended. The timer keeps firing.

`stopped`field#

stopped: boolean

Whether stop has run.

`aggregate`field#

aggregate: {[string]: {[string]: profile.Sample}}

Samples so far, by zone path and then by stack. Two levels rather than one joined key, so a sample taken in a zone that has not changed since the last one costs a single table lookup.

`sourceSamples`field#

sourceSamples: {[string]: {[string]: integer}}

Lua leaf locations counted separately in each zone, before filtering.

`pause`method#

pause: function(self)

Stops recording without ending the session. The timer keeps firing, at the cost of one test per sample, and what was recorded on either side of the pause is kept, which is how a benchmark leaves its setup out.

Idempotent.

Arguments

Name	Type	Description
`?`	`self`

Raises

Type	Condition
`string`	once the session has stopped

`resume`method#

resume: function(self)

Resumes recording. Idempotent.

Arguments

Name	Type	Description
`?`	`self`

Raises

Type	Condition
`string`	once the session has stopped

`stop`method#

stop: function(self, filename: string?): self.Report

Ends the session and reports what it saw.

Arguments

Name	Type	Description
`?`	`self`
`filename`	`string?`

Returns

Type	Description
`self.Report`

Raises

Type	Condition
`string`	once the session has stopped, so it cannot be called twice

`close`method#

close: function(takes self: profile.SampleSession): nil

Ends the session without a report, which is what leaving its with does.

Does nothing once stop has run, so a block that stopped its session to read the report closes it for free.

Arguments

Name	Type	Description
`takes self`	`profile.SampleSession`

Returns

Type	Description
`nil`

`Session`interface#

interface profile.Session ...

A running profiling session whose declaration chooses the report stop returns.

Sampling and trace-abort sessions share this lifecycle. Generic helpers can use S.Report to preserve the concrete report chosen by a session declaration, and take the session borrows. Each session is also a nupp.Closeable: close, which leaving a with calls, ends one that nothing stopped without building a report, and does nothing after stop. The two are separate so a helper bounded by this one can still name S.Report.

Members

Name	Kind	Description
`Report`	field	What stop returns, chosen by the session declaration rather than here.
`pause`	method	Stops recording without ending the session.
`resume`	method	Resumes recording.
`stop`	method	Ends the session and returns what it saw, optionally writing it to a file.

`Report`field#

Report: associatedDecl

What stop returns, chosen by the session declaration rather than here.

`pause`method#

pause: function(self)

Stops recording without ending the session. Idempotent.

Arguments

Name	Type	Description
`?`	`self`

`resume`method#

resume: function(self)

Resumes recording. Idempotent.

Arguments

Name	Type	Description
`?`	`self`

`stop`method#

stop: function(self, filename: string?): self.Report

Ends the session and returns what it saw, optionally writing it to a file.

Arguments

Name	Type	Description
`?`	`self`
`filename`	`string?`

Returns

Type	Description
`self.Report`

`Severity`type#

type profile.Severity = "blacklist" | "warn" | "info"

How much an abort is worth reading.

blacklist is always actionable: the code is demoted to the interpreter for the rest of the process. warn is a refusal that may or may not sit on a hot path. info is trace formation working as designed.

`SourceSample`type#

type profile.SourceSample = {
    file: string,
    line: integer,
    samples: integer
}

Lua leaf samples attributed to a source line. Native VM states have no reliable Lua location and are excluded.

`TraceOptions`type#

type profile.TraceOptions = {
    --- Include the aborts that are ordinary trace formation rather than a refusal:
    --- leaving a loop, recursion, an inner loop. False by default; turn it on when the
    --- question is why a particular trace never formed.
    includeBenign: boolean?
}

What profile.trace counts. Every field is optional.

`TraceProfile`record#

record profile.TraceProfile ...

The exact recorder configuration used to normalize a trace report.

Two reports are comparable when their id matches. A report taken under an unsupported recorder still reads, but its reasons were mapped from a VM the registry was not written against.

Members

Name	Kind	Description
`id`	field	Every field below joined, which is what two reports are compared on.
`luajitRevision`	field	The pinned LuaJIT commit, or "external:" for any other build.
`luajitVersion`	field	The snapshot timestamp from the full version string.
`architecture`	field	jit.arch.
`operatingSystem`	field	jit.os.
`enabledRecorderFeatures`	field	The recorder flags jit.status reported, sorted.
`bytecodeSchema`	field	A digest of the VM's bytecode name table, so a renumbered opcode set is visible rather than silently remapped.
`supported`	field	Whether this is the recorder the reason registry was written against.

`id`field#

id: string

Every field below joined, which is what two reports are compared on.

`luajitRevision`field#

luajitRevision: string

The pinned LuaJIT commit, or "external:" for any other build.

`luajitVersion`field#

luajitVersion: integer

The snapshot timestamp from the full version string.

`architecture`field#

architecture: string

jit.arch.

`operatingSystem`field#

operatingSystem: string

jit.os.

`enabledRecorderFeatures`field#

enabledRecorderFeatures: {string}

The recorder flags jit.status reported, sorted.

`bytecodeSchema`field#

bytecodeSchema: string

A digest of the VM's bytecode name table, so a renumbered opcode set is visible rather than silently remapped.

`supported`field#

supported: boolean

Whether this is the recorder the reason registry was written against.

`TraceReport`record#

record profile.TraceReport ...

What a trace session saw, as TraceSession:stop returns it.

tostring on it renders sites as RFC 4180 CSV, so it prints, sorts and diffs directly.

Members

Name	Kind	Description
`durationSec`	field	Wallclock seconds the session was active, in whole seconds: it comes from os.time, so a session shorter than one...
`totalAborts`	field	Abort events recorded.
`blacklisted`	field	Blacklist events among them.
`sites`	field	One row per distinct severity, reason, location and zone.
`traceProfile`	field	The recorder and registry identities under which the events were interpreted.
`reasonCatalogId`	field	The reason registry the identities came from.
`reasonCatalogVersion`	field	Its version, so a stored report can be reread under a later one.
`__tostring`	metamethod

`durationSec`field#

durationSec: integer

Wallclock seconds the session was active, in whole seconds: it comes from os.time, so a session shorter than one reads as zero and dividing by it is the caller's problem.

`totalAborts`field#

totalAborts: integer

Abort events recorded. Excludes the benign ones unless includeBenign was set.

`blacklisted`field#

blacklisted: integer

Blacklist events among them. Always actionable.

`sites`field#

sites: {profile.AbortSite}

One row per distinct severity, reason, location and zone. Ordered by severity, then by count descending.

`traceProfile`field#

traceProfile: profile.TraceProfile

The recorder and registry identities under which the events were interpreted.

`reasonCatalogId`field#

reasonCatalogId: string

The reason registry the identities came from.

`reasonCatalogVersion`field#

reasonCatalogVersion: integer

Its version, so a stored report can be reread under a later one.

`__tostring`metamethod#

__tostring: function(self): string

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`string`

`TraceSession`record#

record profile.TraceSession is profile.Session, nupp.Closeable ...

A running trace-abort collector, as profile.trace returns it.

Live until stop or close, and there is at most one at a time. Held by a with, it is closed where the block ends, so the event hook never outlives the question.

Members

Name	Kind	Description
`Report`	field
`includeBenign`	field	Whether the benign trace-formation events are being counted.
`startedAt`	field	os.time when the session started.
`paused`	field	Whether aggregation is suspended.
`stopped`	field	Whether stop has run.
`sites`	field	Aborts so far, by severity, reason, location and zone joined.
`totalAborts`	field	Aborts counted so far.
`blacklisted`	field	Blacklist events among them.
`traceProfile`	field
`callback`	method	The handler to hand back to jit.attach to detach it.
`pause`	method	Stops counting without ending the session.
`resume`	method	Resumes counting.
`stop`	method	Ends the session and reports what it saw.
`close`	method	Ends the session without a report, which is what leaving its with does.

`Report`field#

Report: associatedDecl

`includeBenign`field#

includeBenign: boolean

Whether the benign trace-formation events are being counted.

`startedAt`field#

startedAt: integer

os.time when the session started.

`paused`field#

paused: boolean

Whether aggregation is suspended. The hook stays attached.

`stopped`field#

stopped: boolean

Whether stop has run.

`sites`field#

sites: {[string]: profile.AbortSite}

Aborts so far, by severity, reason, location and zone joined.

`totalAborts`field#

totalAborts: integer

Aborts counted so far.

`blacklisted`field#

blacklisted: integer

Blacklist events among them.

`traceProfile`field#

traceProfile: profile.TraceProfile

`callback`method#

callback: function(...: any)

The handler to hand back to jit.attach to detach it. Dropping the last reference to a handler does not remove it.

Arguments

Name	Type	Description
`...`	`any`

`pause`method#

pause: function(self)

Stops counting without ending the session. The hook stays attached, at the cost of one test per abort, and what was counted on either side of the pause is kept.

Idempotent.

Arguments

Name	Type	Description
`?`	`self`

Raises

Type	Condition
`string`	once the session has stopped

`resume`method#

resume: function(self)

Resumes counting. Idempotent.

Arguments

Name	Type	Description
`?`	`self`

Raises

Type	Condition
`string`	once the session has stopped

`stop`method#

stop: function(self, filename: string?): self.Report

Ends the session and reports what it saw.

Arguments

Name	Type	Description
`?`	`self`
`filename`	`string?`

Returns

Type	Description
`self.Report`

Raises

Type	Condition
`string`	once the session has stopped, so it cannot be called twice

`close`method#

close: function(takes self: profile.TraceSession): nil

Ends the session without a report, which is what leaving its with does.

Does nothing once stop has run, so a block that stopped its session to read the report closes it for free.

Arguments

Name	Type	Description
`takes self`	`profile.TraceSession`

Returns

Type	Description
`nil`

Functions#

`profile.sample`function#

function profile.sample(options: profile.SampleOptions?): profile.SampleSession

Starts sampling.

with session = profile.sample({intervalMs = 5, zone = "frame/render"}) do
    render()
    local report = session:stop("render.collapsed")
    print(report.samples, report.stacks)
end

Arguments

Name	Type	Description
`options`	`profile.SampleOptions?`	omitted samples every zone at 10 ms to a depth of 16

Returns

Type	Description
`profile.SampleSession`	the handle whose `stop` produces the report

Raises

Type	Condition
`string`	when a sample session is already running or an option is out of range

`profile.trace`function#

function profile.trace(options: profile.TraceOptions?): profile.TraceSession

Starts collecting trace aborts.

with session = profile.trace() do
    render()
    local report = session:stop("aborts.csv")
    print(report.blacklisted, report.totalAborts)
end

Arguments

Name	Type	Description
`options`	`profile.TraceOptions?`	omitted leaves the benign trace-formation events out

Returns

Type	Description
`profile.TraceSession`	the handle whose `stop` produces the report

Raises

Type	Condition
`string`	when a trace session is already running

nupp.profile

Submodules

Module contents

Types

Functions

Types#

AbortSiterecord#

Members

severityfield#

countfield#

reasonfield#

reasonIdfield#

reasonClassfield#

rawReasonfield#

locationfield#

rootLocationfield#

zonePathfield#

Samplerecord#

Members

zonePathfield#

stackfield#

countfield#

compiledfield#

interpretedfield#

cCodefield#

collectingfield#

compilingfield#

SampleOptionstype#

SampleReportrecord#

Members

intervalMsfield#

samplesfield#

sourceSamplesfield#

stacksfield#

textfield#

__tostringmetamethod#

Arguments

Returns

SampleSessionrecord#

Members

Reportfield#

intervalMsfield#

zoneFilterfield#

rootfield#

pausedfield#

stoppedfield#

aggregatefield#

sourceSamplesfield#

pausemethod#

Arguments

Raises

resumemethod#

Arguments

Raises

stopmethod#

Arguments

Returns

Raises

closemethod#

Arguments

Returns

Sessioninterface#

Members

Reportfield#

pausemethod#

Arguments

resumemethod#

Arguments

stopmethod#

Arguments

Returns

Severitytype#

SourceSampletype#

TraceOptionstype#

TraceProfilerecord#

Members

idfield#

luajitRevisionfield#

luajitVersionfield#

architecturefield#

`nupp.profile`

`AbortSite`record#

`severity`field#

`count`field#

`reason`field#

`reasonId`field#

`reasonClass`field#

`rawReason`field#

`location`field#

`rootLocation`field#

`zonePath`field#

`Sample`record#

`zonePath`field#

`stack`field#

`count`field#

`compiled`field#

`interpreted`field#

`cCode`field#

`collecting`field#

`compiling`field#

`SampleOptions`type#

`SampleReport`record#

`intervalMs`field#

`samples`field#

`sourceSamples`field#

`stacks`field#

`text`field#

`__tostring`metamethod#

`SampleSession`record#

`Report`field#

`intervalMs`field#

`zoneFilter`field#

`root`field#

`paused`field#

`stopped`field#

`aggregate`field#

`sourceSamples`field#

`pause`method#

`resume`method#

`stop`method#

`close`method#

`Session`interface#

`Report`field#

`pause`method#

`resume`method#

`stop`method#

`Severity`type#

`SourceSample`type#

`TraceOptions`type#

`TraceProfile`record#

`id`field#

`luajitRevision`field#

`luajitVersion`field#

`architecture`field#

`operatingSystem`field#

`enabledRecorderFeatures`field#

`bytecodeSchema`field#

`supported`field#

`TraceReport`record#

`durationSec`field#

`totalAborts`field#

`blacklisted`field#

`sites`field#

`traceProfile`field#

`reasonCatalogId`field#

`reasonCatalogVersion`field#

`__tostring`metamethod#

`TraceSession`record#

`Report`field#

`includeBenign`field#

`startedAt`field#

`paused`field#

`stopped`field#

`sites`field#

`totalAborts`field#

`blacklisted`field#

`traceProfile`field#

`callback`method#

`pause`method#

`resume`method#