trace
Classes
Tracer
Defined in: trace.ts:79
A low overhead tracer for the install pipeline.
It is off unless VLT_TRACE=<file> or VLT_PHASES=1 is set, and when
off every method returns after one boolean check, so call sites can
stay in the hot path.
With VLT_TRACE every event is appended to the file as one JSON line.
Lines are buffered and flushed every flushLines lines or flushMs
ms, and at exit. Worker threads
get their own instance from the same env and append to the same file,
so the file interleaves threads; sort by t to read it.
With VLT_PHASES the main thread prints one line at exit: the ms
between consecutive Tracer.mark calls, the event loop delay
percentiles (the direct measure of how long the main thread was busy
with synchronous work while IO completions waited), and peak memory.
Constructors
new Tracer()
new Tracer(options): TracerDefined in: trace.ts:97
Parameters
| Parameter | Type |
|---|---|
options | TracerOptions |
Returns
Properties
| Property | Type |
|---|---|
enabled | boolean |
file? | string |
phases | boolean |
Methods
close()
close(): voidDefined in: trace.ts:256
Stop sampling, flush, and print the summary. Runs at process exit on the main thread; safe to call more than once.
Returns
void
flush()
flush(): voidDefined in: trace.ts:209
Write buffered lines to the file.
Returns
void
lane()
lane(
name,
busy,
queued): voidDefined in: trace.ts:191
Record how busy a resource lane is: how many jobs it is running and how many are waiting for a slot. The report derives idle time per lane from these.
Parameters
| Parameter | Type |
|---|---|
name | string |
busy | number |
queued | number |
Returns
void
mark()
mark(name, fields?): voidDefined in: trace.ts:180
Mark the start of a phase. The summary reports the ms between each
mark and the next one, and the trace records a phase event.
Parameters
| Parameter | Type |
|---|---|
name | string |
fields? | TraceFields |
Returns
void
sample()
sample(): voidDefined in: trace.ts:197
Record a memory sample.
Returns
void
span()
span(ev, fields?): (end?) => voidDefined in: trace.ts:161
Record a <ev>:start event now and return a function that records
<ev>:end with the elapsed ms (plus any fields it is given). The
same fields are stamped on both ends so the two can be paired.
Parameters
| Parameter | Type |
|---|---|
ev | string |
fields? | TraceFields |
Returns
Function
Parameters
| Parameter | Type |
|---|---|
end? | TraceFields |
Returns
void
summary()
summary(): undefined | stringDefined in: trace.ts:229
The one-line phase summary, or undefined when phases are off. Each phase is reported as the ms from its mark to the next mark (or to now, for the last one).
Returns
undefined | string
trace()
trace(ev, fields?): voidDefined in: trace.ts:140
Record one event.
Parameters
| Parameter | Type |
|---|---|
ev | string |
fields? | TraceFields |
Returns
void
fromEnv()
static fromEnv(env, options): TracerDefined in: trace.ts:127
Build a tracer from the environment: VLT_TRACE names the file,
VLT_PHASES (any value but 0 or empty) asks for the summary.
Parameters
| Parameter | Type | Default value |
|---|---|---|
env | Record<string, undefined | string> | process.env |
options | Omit<TracerOptions, "file" | "phases"> | {} |
Returns
Type Aliases
TraceEvent
type TraceEvent = object & TraceFields;Defined in: trace.ts:21
One trace event. t is an absolute wall clock in milliseconds
(performance.timeOrigin + performance.now()), the same clock on every
thread, so events from workers and the main thread can be laid on one
timeline. tid is the worker thread id, 0 for the main thread.
Type declaration
| Name | Type |
|---|---|
ev | string |
t | number |
tid | number |
TraceFields
type TraceFields = Record<string, string | number | boolean | undefined>;Defined in: trace.ts:10
Extra fields recorded with a trace event. Keep them flat and small: every event is one JSON line.
TracerOptions
type TracerOptions = object;Defined in: trace.ts:27
Type declaration
| Name | Type | Description |
|---|---|---|
append? | (file, data) => void | Appends a chunk of lines to the trace file. |
file? | string | Path of the JSON-lines file to append events to (VLT_TRACE). |
flushLines? | number | Flush after this many buffered lines. |
flushMs? | number | Flush this many ms after the first buffered line. |
main? | boolean | Whether this is the main thread, which owns the event loop monitor. |
now? | () => number | Absolute clock in ms. Defaults to the shared performance clock. |
phases? | boolean | Print a one-line phase summary to stderr at exit (VLT_PHASES). |
sampleMs? | number | Sample rss this often, in ms. 0 disables sampling. |
threadId? | number | The thread id to stamp events with. Defaults to the real one. |
write? | (line) => void | Writes the phase summary line. Defaults to stderr. |
Variables
tracer
const tracer: Tracer;Defined in: trace.ts:283
The process-wide tracer, built from the environment. Worker threads inherit the environment, so they trace to the same file.
Functions
lane()
function lane(
name,
busy,
queued): voidDefined in: trace.ts:300
Record lane occupancy on the process-wide tracer.
Parameters
| Parameter | Type |
|---|---|
name | string |
busy | number |
queued | number |
Returns
void
mark()
function mark(name, fields?): voidDefined in: trace.ts:296
Mark a phase on the process-wide tracer. See Tracer.mark.
Parameters
| Parameter | Type |
|---|---|
name | string |
fields? | TraceFields |
Returns
void
span()
function span(ev, fields?): (end?) => voidDefined in: trace.ts:290
Open a span on the process-wide tracer. See Tracer.span.
Parameters
| Parameter | Type |
|---|---|
ev | string |
fields? | TraceFields |
Returns
Function
Parameters
| Parameter | Type |
|---|---|
end? | TraceFields |
Returns
void
trace()
function trace(ev, fields?): voidDefined in: trace.ts:286
Record one event on the process-wide tracer.
Parameters
| Parameter | Type |
|---|---|
ev | string |
fields? | TraceFields |
Returns
void