@ogygia/devtools/profiler

This page is generated from the package’s own .d.ts files on every build, so the signatures, descriptions and examples below always match the source.

import { … } from '@ogygia/devtools/profiler';

Exports instrument · set_span_recorder · span · span_recording · tag · SpanHandle · SpanRecord · SpanRecorder · InstrumentAttrs · SpanAttrs

instrument

function

function instrument<A extends unknown[], R>(fn: (...args: A) => R, name: string, attrs?: InstrumentAttrs<A, R>): (...args: A) => R;
function instrument<T extends object, K extends keyof T>(target: T, method: K, name: string, attrs?: T[K] extends ((...args: infer A) => infer R) ? InstrumentAttrs<A, R> : never): () => void;

set_span_recorder

function

The profiler host installs a recorder for a recording; null uninstalls.

function set_span_recorder(r: SpanRecorder | null): void;

span

function

Run fn as a named span. Sync in, sync out; a promise in, a promise out — the wrapper never changes the shape of what it wraps. A throw (or rejection) is recorded on the span and rethrown. attrs is a plain record, or a function of the result for what is only known afterwards ((r) => ({ cache: r.fromCache ? 'hit' : 'miss', rows: r.length })). Reserved keys the report reads: cache ('hit' | 'miss'), rows, bytes, key; anything else is carried and shown.

function span<T>(name: string, fn: () => T, attrs?: SpanAttrs | ((result: Awaited<T>) => SpanAttrs | undefined)): T;

span_recording

function

Whether a recorder is installed (tests / the host).

function span_recording(): boolean;

tag

function

Stamp the current request with key = value (string, number or boolean; kept to 64 chars, at most 16 keys). Shown on the request's log row and in the report; the dashboard splits the slowest routes by any tag. A no-op outside a recording, and always on the client.

function tag(key: string, value: string | number | boolean): void;

SpanHandle

interface

A span opened by hand (span.start) for what a callback cannot wrap: a stream, an event.

interface SpanHandle {/*…*/}

SpanHandle.set

add or change an attribute while the span runs

set(key: string, value: string | number | boolean): void;

SpanHandle.end

close it; ending twice is a no-op

end(attrs?: SpanAttrs): void;

SpanHandle.fail

close it as failed

fail(error: unknown): void;

SpanRecord

interface

interface SpanRecord {/*…*/}

SpanRecord.id

id: number;

SpanRecord.name

name: string;

SpanRecord.start

performance.now() at start

start: number;

SpanRecord.ms

duration; -1 while running (an open span at the end of a recording keeps -1)

ms: number;

SpanRecord.attrs

attrs?: SpanAttrs;

SpanRecord.error

the thrown error's message, when fn threw / the handle was failed

error?: string;

SpanRecord.open

never ended before the recording stopped

open?: boolean;

SpanRecord.parent

the enclosing span's id, when nested

parent?: number;

SpanRecord.caller

resolved at report time from caller_site (same as an outbound call's)

caller?: string;

SpanRecord.caller_site

caller_site?: CallerSite;

SpanRecord.route

the page render that ran it, when known

route: string | null;

SpanRecord.path

path: string | null;

SpanRecorder

interface

What the profiler host installs while a recording runs.

interface SpanRecorder {/*…*/}

SpanRecorder.begin

begin(name: string, attrs?: SpanAttrs): SpanRecord;

SpanRecorder.within

run fn with s as the current span (nesting); the host binds it to its async context

within<T>(s: SpanRecord, fn: () => T): T;

SpanRecorder.end

end(s: SpanRecord, attrs?: SpanAttrs, error?: unknown): void;

SpanRecorder.tag

tag(key: string, value: string): void;

InstrumentAttrs

type

The attrs callback of instrument: the result, then the call's arguments. Declared method-style so a callback naming fewer arguments than the function takes ((r, tag) => … for a two-argument renderer) is accepted, and so it never narrows the wrapped signature. NoInfer wraps the whole callback, not its rest argument: on the rest tuple alone it made a shorter callback a tuple-length mismatch, so the (r, tag) => … form above did not type-check.

type InstrumentAttrs<A extends unknown[], R> = NoInfer<{
  bivariant(result: Awaited<R>, ...args: A): SpanAttrs | undefined;
}["bivariant"]>;

SpanAttrs

type

type SpanAttrs = Record<string, string | number | boolean>;