@rootcat/node 0.0.0-stage → 0.1.0

package/dist/processor.d.ts

@@ -0,0 +1,94 @@
+import { type Context } from '@opentelemetry/api';
+import type { ReadableSpan, Span, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { type CallSiteLocation } from './callsite.js';
+import { type StatementMode } from './privacy.js';
+export { callSiteContextKey } from './keys.js';
+/**
+ * CallSiteSampling is the gate every capture goes through: the
+ * processor's own and the entry wrappers' (pg, pg pool, Drizzle,
+ * postgres.js), so a capture is never paid for a span that will not be
+ * exported or that the one-in-N setting skips.
+ */
+export declare class CallSiteSampling {
+    /** sample is the one-in-N setting; the benchmark changes it between blocks. */
+    sample: number;
+    /** ratio is the trace sampling share; the benchmark changes it between blocks. */
+    ratio: number;
+    private counter;
+    /** sample is ROOTCAT_CALLSITE_SAMPLE; ratio is ROOTCAT_SAMPLE. */
+    constructor(sample: number, ratio?: number);
+    /** take counts one occasion and reports whether it captures. */
+    take(): boolean;
+    /** on reports whether any capture happens at all. */
+    get on(): boolean;
+    /**
+     * carry is what an entry wrapper calls before the operation it wraps:
+     * it returns the context to run the operation in, or undefined to run
+     * it as it is. Under an unsampled span nothing happens. Outside any
+     * span with a ratio below 1, the trace decision is made here (the
+     * sampler follows it), and an unsampled operation captures nothing. A
+     * site already carried by an outer layer of the same operation stands,
+     * unless override (a capture that costs nothing, such as postgres.js's
+     * own origin, and names the operation more exactly). Otherwise, one
+     * occasion in N, capture() runs and its site is carried.
+     */
+    carry(capture: () => CallSiteLocation | undefined, override?: boolean): Context | undefined;
+}
+/**
+ * unsampled reports whether a span started under ctx would not be
+ * recorded (an unsampled parent, or a root an entry wrapper decided
+ * against): the drivers then run untouched, without even a
+ * non-recording span or a context of their own.
+ */
+export declare function unsampled(ctx: Context): boolean;
+/** runCarried runs fn under the context carry returned, if any. */
+export declare function runCarried<T>(ctx: Context | undefined, fn: () => T): T;
+/** CallSiteProcessorOptions configures the processor. */
+export interface CallSiteProcessorOptions {
+    /** sampling gates the captures; a number is the one-in-N setting. */
+    sampling: CallSiteSampling | number;
+    /** depth bounds the frames walked. */
+    depth: number;
+    /** statement is passed to the privacy rules. */
+    statement: StatementMode;
+    /** isApp decides which files are application code (tests override). */
+    isApp?: (file: string) => boolean;
+    /**
+     * above is the function a capture from the processor starts below (the
+     * SDK tracer's startSpan), so the walk skips the SDK's own frames.
+     */
+    above?: Function;
+}
+/** Attribute keys written. */
+export declare const codeFilepath = "code.filepath";
+export declare const codeLineno = "code.lineno";
+export declare const codeFunction = "code.function";
+/**
+ * eligible reports whether a span is a client operation worth a call
+ * site: client and producer spans, anything carrying db.system, and the
+ * operation spans of the ORMs that start their work in application code.
+ */
+export declare function eligible(span: ReadableSpan): boolean;
+/** CallSiteProcessor implements SpanProcessor. */
+export declare class CallSiteProcessor implements SpanProcessor {
+    readonly sampling: CallSiteSampling;
+    private readonly depth;
+    private readonly statement;
+    private readonly isApp;
+    /** above is where a processor capture starts (the SDK tracer startSpan); set once the provider exists. */
+    above: Function | undefined;
+    private readonly sites;
+    /** captured counts spans given a call site (tests and the benchmark). */
+    captured: number;
+    constructor(options: CallSiteProcessorOptions);
+    onStart(span: Span, parentContext: Context): void;
+    /**
+     * locate takes a site already carried in the context or by the parent
+     * span (an entry wrapper paid for it, under the same gate), else, one
+     * occasion in N, captures the synchronous stack.
+     */
+    private locate;
+    onEnd(span: ReadableSpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}

package/dist/processor.js

@@ -0,0 +1,252 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallSiteProcessor = exports.codeFunction = exports.codeLineno = exports.codeFilepath = exports.CallSiteSampling = exports.callSiteContextKey = void 0;
+exports.unsampled = unsampled;
+exports.runCarried = runCarried;
+exports.eligible = eligible;
+// CallSiteProcessor: a span processor that, when a client span starts,
+// records the application frame that caused it as code.filepath,
+// code.lineno and code.function, and applies the privacy rules to the
+// span's attributes at start and at end.
+//
+// Where the frame comes from, in order: the synchronous stack at span
+// start (the usual case: the driver was called from application code);
+// else a call site an entry wrapper stored in the active context (a pg
+// pool hands queries to a client on nextTick, where the stack is the
+// pool's); else the parent span's call site (an ORM's operation span
+// started in application code, its driver span on a later tick).
+const api_1 = require("@opentelemetry/api");
+const callsite_js_1 = require("./callsite.js");
+const keys_js_1 = require("./keys.js");
+const privacy_js_1 = require("./privacy.js");
+var keys_js_2 = require("./keys.js");
+Object.defineProperty(exports, "callSiteContextKey", { enumerable: true, get: function () { return keys_js_2.callSiteContextKey; } });
+/**
+ * CallSiteSampling is the gate every capture goes through: the
+ * processor's own and the entry wrappers' (pg, pg pool, Drizzle,
+ * postgres.js), so a capture is never paid for a span that will not be
+ * exported or that the one-in-N setting skips.
+ */
+class CallSiteSampling {
+    /** sample is the one-in-N setting; the benchmark changes it between blocks. */
+    sample;
+    /** ratio is the trace sampling share; the benchmark changes it between blocks. */
+    ratio;
+    counter = 0;
+    /** sample is ROOTCAT_CALLSITE_SAMPLE; ratio is ROOTCAT_SAMPLE. */
+    constructor(sample, ratio = 1) {
+        this.sample = Math.max(0, Math.floor(sample));
+        this.ratio = Math.min(1, Math.max(0, ratio));
+    }
+    /** take counts one occasion and reports whether it captures. */
+    take() {
+        if (this.sample === 0) {
+            return false;
+        }
+        this.counter++;
+        return this.counter % this.sample === 0;
+    }
+    /** on reports whether any capture happens at all. */
+    get on() {
+        return this.sample > 0;
+    }
+    /**
+     * carry is what an entry wrapper calls before the operation it wraps:
+     * it returns the context to run the operation in, or undefined to run
+     * it as it is. Under an unsampled span nothing happens. Outside any
+     * span with a ratio below 1, the trace decision is made here (the
+     * sampler follows it), and an unsampled operation captures nothing. A
+     * site already carried by an outer layer of the same operation stands,
+     * unless override (a capture that costs nothing, such as postgres.js's
+     * own origin, and names the operation more exactly). Otherwise, one
+     * occasion in N, capture() runs and its site is carried.
+     */
+    carry(capture, override = false) {
+        const active = api_1.context.active();
+        const span = api_1.trace.getSpanContext(active);
+        let ctx = active;
+        // A remote parent (an incoming traceparent) decides nothing: see the sampler.
+        if (span && api_1.trace.isSpanContextValid(span) && !span.isRemote) {
+            if ((span.traceFlags & api_1.TraceFlags.SAMPLED) === 0) {
+                return undefined;
+            }
+        }
+        else if (this.ratio < 1 && active.getValue(keys_js_1.rootDecisionKey) === undefined) {
+            const decided = Math.random() < this.ratio;
+            ctx = ctx.setValue(keys_js_1.rootDecisionKey, decided);
+            if (!decided) {
+                return ctx;
+            }
+        }
+        else if (active.getValue(keys_js_1.rootDecisionKey) === false) {
+            return undefined;
+        }
+        const existing = active.getValue(keys_js_1.callSiteContextKey) !== undefined;
+        if ((existing && !override) || (!existing && !this.take())) {
+            return ctx === active ? undefined : ctx;
+        }
+        const site = capture();
+        if (site) {
+            ctx = ctx.setValue(keys_js_1.callSiteContextKey, site);
+        }
+        return ctx === active ? undefined : ctx;
+    }
+}
+exports.CallSiteSampling = CallSiteSampling;
+/**
+ * unsampled reports whether a span started under ctx would not be
+ * recorded (an unsampled parent, or a root an entry wrapper decided
+ * against): the drivers then run untouched, without even a
+ * non-recording span or a context of their own.
+ */
+function unsampled(ctx) {
+    const parent = api_1.trace.getSpanContext(ctx);
+    if (parent && api_1.trace.isSpanContextValid(parent) && !parent.isRemote) {
+        return (parent.traceFlags & api_1.TraceFlags.SAMPLED) === 0;
+    }
+    return ctx.getValue(keys_js_1.rootDecisionKey) === false;
+}
+/** runCarried runs fn under the context carry returned, if any. */
+function runCarried(ctx, fn) {
+    return ctx ? api_1.context.with(ctx, fn) : fn();
+}
+/** Attribute keys written. */
+exports.codeFilepath = 'code.filepath';
+exports.codeLineno = 'code.lineno';
+exports.codeFunction = 'code.function';
+/**
+ * eligible reports whether a span is a client operation worth a call
+ * site: client and producer spans, anything carrying db.system, and the
+ * operation spans of the ORMs that start their work in application code.
+ */
+function eligible(span) {
+    if (!span.spanContext().traceFlags) {
+        return false; // not sampled: nothing will export it
+    }
+    if (span.kind === api_1.SpanKind.CLIENT || span.kind === api_1.SpanKind.PRODUCER) {
+        return true;
+    }
+    const attributes = span.attributes;
+    if (attributes['db.system'] !== undefined || attributes['db.system.name'] !== undefined) {
+        return true;
+    }
+    return span.name.startsWith('drizzle.') || span.name.startsWith('prisma:client:');
+}
+/** CallSiteProcessor implements SpanProcessor. */
+class CallSiteProcessor {
+    sampling;
+    depth;
+    statement;
+    isApp;
+    /** above is where a processor capture starts (the SDK tracer startSpan); set once the provider exists. */
+    above;
+    sites = new WeakMap();
+    /** captured counts spans given a call site (tests and the benchmark). */
+    captured = 0;
+    constructor(options) {
+        this.sampling = typeof options.sampling === 'number' ? new CallSiteSampling(options.sampling) : options.sampling;
+        this.depth = Math.max(1, Math.floor(options.depth));
+        this.statement = options.statement;
+        this.isApp = options.isApp ?? callsite_js_1.isAppFile;
+        this.above = options.above;
+    }
+    onStart(span, parentContext) {
+        try {
+            const changes = (0, privacy_js_1.scrubbed)(span.attributes, this.statement);
+            if (changes) {
+                span.setAttributes(changes);
+            }
+            if (!this.sampling.on || !eligible(span)) {
+                return;
+            }
+            const site = this.locate(parentContext);
+            if (!site) {
+                return;
+            }
+            this.sites.set(span, site);
+            this.captured++;
+            span.setAttribute(exports.codeFilepath, (0, callsite_js_1.displayPath)(site.file));
+            span.setAttribute(exports.codeLineno, site.line);
+            if (site.function !== '') {
+                span.setAttribute(exports.codeFunction, site.function);
+            }
+        }
+        catch {
+            // A call site is an extra; a failure to find one never reaches the app.
+        }
+    }
+    /**
+     * locate takes a site already carried in the context or by the parent
+     * span (an entry wrapper paid for it, under the same gate), else, one
+     * occasion in N, captures the synchronous stack.
+     */
+    locate(parentContext) {
+        const carried = parentContext.getValue(keys_js_1.callSiteContextKey);
+        if (isLocation(carried)) {
+            return carried;
+        }
+        const parent = api_1.trace.getSpan(parentContext);
+        const inherited = parent ? this.sites.get(parent) : undefined;
+        if (inherited) {
+            return inherited;
+        }
+        if (!this.sampling.take()) {
+            return undefined;
+        }
+        return (0, callsite_js_1.captureCallSite)(this.depth, this.isApp, this.above);
+    }
+    onEnd(span) {
+        try {
+            // The span is ended; the exporter reads these same objects, so the
+            // rules hold for attributes and events set after the start as well.
+            const changes = (0, privacy_js_1.scrubbed)(span.attributes, this.statement);
+            if (changes) {
+                const attributes = span.attributes;
+                for (const [key, value] of Object.entries(changes)) {
+                    attributes[key] = value;
+                }
+            }
+            let exceptionMessage;
+            for (const event of span.events) {
+                const attributes = event.attributes;
+                const stack = attributes?.['exception.stacktrace'];
+                if (typeof stack === 'string') {
+                    // A recorded exception's stack opens with its message line, which
+                    // a database server may fill with the input that failed; the
+                    // frames alone say where it happened.
+                    attributes['exception.stacktrace'] = (0, privacy_js_1.framesOnly)(stack);
+                }
+                if (event.name === 'exception' && typeof attributes?.['exception.message'] === 'string') {
+                    exceptionMessage = attributes['exception.message'];
+                }
+            }
+            // A database span's status message is the server's text, which can
+            // quote the input that failed; the instrumentation's own exception
+            // message (the pg one says only the class and SQLSTATE) stands in.
+            if (span.status.code === api_1.SpanStatusCode.ERROR && isDatabase(span.attributes) && span.status.message) {
+                span.status.message = exceptionMessage ?? 'database error';
+            }
+        }
+        catch {
+            // never reaches the app
+        }
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+}
+exports.CallSiteProcessor = CallSiteProcessor;
+function isDatabase(attributes) {
+    return attributes['db.system'] !== undefined || attributes['db.system.name'] !== undefined;
+}
+function isLocation(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return typeof record.file === 'string' && typeof record.line === 'number';
+}
+//# sourceMappingURL=processor.js.map

package/dist/processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.js","sourceRoot":"","sources":["../src/processor.ts"],"names":[],"mappings":"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"}

package/dist/register.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/register.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// The --require entry: starts tracing as a side effect of being loaded.
+//   NODE_OPTIONS="--require @rootcat/node"
+// The module loader hooks thread runs the same preloads as the main
+// thread; tracing belongs to the main thread only.
+const node_worker_threads_1 = require("node:worker_threads");
+const sdk_js_1 = require("./sdk.js");
+if (node_worker_threads_1.isMainThread) {
+    (0, sdk_js_1.start)();
+}
+//# sourceMappingURL=register.js.map

package/dist/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":";;AAAA,wEAAwE;AACxE,2CAA2C;AAC3C,oEAAoE;AACpE,mDAAmD;AACnD,6DAAmD;AACnD,qCAAiC;AAEjC,IAAI,kCAAY,EAAE,CAAC;IACjB,IAAA,cAAK,GAAE,CAAC;AACV,CAAC"}

package/dist/sampler.d.ts

@@ -0,0 +1,12 @@
+import { type Attributes, type Context, type Link, type SpanKind } from '@opentelemetry/api';
+import { type Sampler, type SamplingResult } from '@opentelemetry/sdk-trace-base';
+/** RootcatSampler is the ratio sampler that honours a wrapper's root decision. */
+export declare class RootcatSampler implements Sampler {
+    readonly ratio: number;
+    private readonly inner;
+    constructor(ratio: number);
+    shouldSample(context: Context, traceId: string, spanName: string, spanKind: SpanKind, attributes: Attributes, links: Link[]): SamplingResult;
+    toString(): string;
+}
+/** rootcatSampler builds the sampler for a ratio between 0 and 1. */
+export declare function rootcatSampler(ratio: number): Sampler;

package/dist/sampler.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RootcatSampler = void 0;
+exports.rootcatSampler = rootcatSampler;
+// The sampler: parent-based, with a trace-id ratio at the root
+// (ROOTCAT_SAMPLE, 1 by default) and for a parent from outside the
+// process, whose sampled flag is not trusted. A root span whose context carries a
+// decision an entry wrapper already made (see CallSiteSampling.carry)
+// follows it, so the wrapper's capture and the span's fate agree. A span
+// the sampler refuses is never recording: no processor runs for it.
+const api_1 = require("@opentelemetry/api");
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const keys_js_1 = require("./keys.js");
+const sampled = { decision: sdk_trace_base_1.SamplingDecision.RECORD_AND_SAMPLED };
+const dropped = { decision: sdk_trace_base_1.SamplingDecision.NOT_RECORD };
+/** RootcatSampler is the ratio sampler that honours a wrapper's root decision. */
+class RootcatSampler {
+    ratio;
+    inner;
+    constructor(ratio) {
+        this.ratio = ratio;
+        // A parent from outside the process (an incoming traceparent) does not
+        // decide: anyone on the internet could otherwise force full tracing of
+        // their requests with the sampled flag, or hide them with 00. The
+        // ratio decides on the trace id, which the request keeps, so the trace
+        // still joins its caller's.
+        const root = ratio >= 1 ? new sdk_trace_base_1.AlwaysOnSampler() : new sdk_trace_base_1.TraceIdRatioBasedSampler(ratio);
+        this.inner = new sdk_trace_base_1.ParentBasedSampler({ root, remoteParentSampled: root, remoteParentNotSampled: root });
+    }
+    shouldSample(context, traceId, spanName, spanKind, attributes, links) {
+        const parent = api_1.trace.getSpanContext(context);
+        if (!parent || !api_1.trace.isSpanContextValid(parent) || parent.isRemote) {
+            const decided = context.getValue(keys_js_1.rootDecisionKey);
+            if (decided === true) {
+                return sampled;
+            }
+            if (decided === false) {
+                return dropped;
+            }
+        }
+        return this.inner.shouldSample(context, traceId, spanName, spanKind, attributes, links);
+    }
+    toString() {
+        return `RootcatSampler(${this.ratio})`;
+    }
+}
+exports.RootcatSampler = RootcatSampler;
+/** rootcatSampler builds the sampler for a ratio between 0 and 1. */
+function rootcatSampler(ratio) {
+    return new RootcatSampler(ratio);
+}
+//# sourceMappingURL=sampler.js.map

package/dist/sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.js","sourceRoot":"","sources":["../src/sampler.ts"],"names":[],"mappings":";;;AA+CA,wCAEC;AAjDD,+DAA+D;AAC/D,mEAAmE;AACnE,kFAAkF;AAClF,sEAAsE;AACtE,yEAAyE;AACzE,oEAAoE;AACpE,4CAAoG;AACpG,kEAAmK;AACnK,uCAA4C;AAE5C,MAAM,OAAO,GAAmB,EAAE,QAAQ,EAAE,iCAAgB,CAAC,kBAAkB,EAAE,CAAC;AAClF,MAAM,OAAO,GAAmB,EAAE,QAAQ,EAAE,iCAAgB,CAAC,UAAU,EAAE,CAAC;AAE1E,kFAAkF;AAClF,MAAa,cAAc;IAGJ;IAFJ,KAAK,CAAU;IAEhC,YAAqB,KAAa;QAAb,UAAK,GAAL,KAAK,CAAQ;QAChC,uEAAuE;QACvE,uEAAuE;QACvE,kEAAkE;QAClE,uEAAuE;QACvE,4BAA4B;QAC5B,MAAM,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,gCAAe,EAAE,CAAC,CAAC,CAAC,IAAI,yCAAwB,CAAC,KAAK,CAAC,CAAC;QACtF,IAAI,CAAC,KAAK,GAAG,IAAI,mCAAkB,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,sBAAsB,EAAE,IAAI,EAAE,CAAC,CAAC;IACzG,CAAC;IAED,YAAY,CAAC,OAAgB,EAAE,OAAe,EAAE,QAAgB,EAAE,QAAkB,EAAE,UAAsB,EAAE,KAAa;QACzH,MAAM,MAAM,GAAG,WAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,MAAM,IAAI,CAAC,WAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpE,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,yBAAe,CAAC,CAAC;YAClD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,OAAO,OAAO,CAAC;YACjB,CAAC;YACD,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;gBACtB,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC1F,CAAC;IAED,QAAQ;QACN,OAAO,kBAAkB,IAAI,CAAC,KAAK,GAAG,CAAC;IACzC,CAAC;CACF;AA9BD,wCA8BC;AAED,qEAAqE;AACrE,SAAgB,cAAc,CAAC,KAAa;IAC1C,OAAO,IAAI,cAAc,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC"}

package/dist/sdk.d.ts

@@ -0,0 +1,88 @@
+import { type Instrumentation } from '@opentelemetry/instrumentation';
+import { type Sampler, type SpanExporter, type SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { type Config } from './config.js';
+import { type ESMHook } from './esmhook.js';
+import { CallSiteProcessor, CallSiteSampling } from './processor.js';
+/**
+ * Exporter bounds, fixed: sized for a loopback intake that takes 1 MiB
+ * per request (512 protobuf spans are a few hundred KiB) and four
+ * uploads per sender. The queue holds 4096 ended spans; past that the
+ * newest are dropped, and the drop is reported once on stderr.
+ */
+export declare const exporterTimeoutMillis = 2000;
+export declare const exporterConcurrency = 2;
+export declare const batchMaxQueueSize = 4096;
+export declare const batchMaxExportSize = 512;
+export declare const batchDelayMillis = 10000;
+/**
+ * spanLimits bound every span, so a batch of them can be split into
+ * requests the agent accepts and nothing the application records (a
+ * statement from any driver, an exception stack) grows without bound:
+ * each attribute value at most 4 KiB, 64 attributes, 8 events of 8
+ * attributes. The largest possible span then encodes to about half a MiB.
+ */
+export declare const spanLimits: {
+    attributeValueLengthLimit: number;
+    attributeCountLimit: number;
+    eventCountLimit: number;
+    attributePerEventCountLimit: number;
+    linkCountLimit: number;
+    attributePerLinkCountLimit: number;
+};
+/** signalFlushMillis bounds the flush attempted on SIGTERM and SIGINT. */
+export declare const signalFlushMillis = 2000;
+/** Started is a running SDK. */
+export interface Started {
+    config: Config;
+    provider: NodeTracerProvider;
+    callSites: CallSiteProcessor;
+    /** esmHook says whether the module loader hook is registered. */
+    esmHook: ESMHook;
+    /** instrumentations are the ones registered (the benchmark disables and enables them). */
+    instrumentations: Instrumentation[];
+    /** shutdown flushes and stops; it resolves within the exporter timeout. */
+    shutdown(): Promise<void>;
+}
+/** StartOptions override the environment (tests). */
+export interface StartOptions {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    /** spanProcessors replace the exporting processor (tests pass an in-memory one). */
+    spanProcessors?: SpanProcessor[];
+    /** exporter replaces the OTLP exporter behind the batching processor. */
+    exporter?: SpanExporter;
+    /** sampler replaces the default sampler. */
+    sampler?: Sampler;
+    /** esmHook false skips the module loader hook (the benchmark measures its cost). */
+    esmHook?: boolean;
+    /** instrumentations replace the curated set (tests). */
+    instrumentations?: Instrumentation[];
+    /** hooks installs the exit and signal handlers; default true. */
+    hooks?: boolean;
+}
+/** instrumentationNames are the names ROOTCAT_DISABLE accepts. */
+export declare const instrumentationNames: readonly ["http", "undici", "pg", "postgres", "drizzle", "mysql2", "mongodb", "ioredis", "redis", "prisma"];
+/** redisStatement records the command name and the argument count only. */
+export declare function redisStatement(command: string, args: unknown[]): string;
+/**
+ * curatedInstrumentations builds the instrumentation set the config
+ * allows; sampling is the call-site gate they share with the processor.
+ */
+export declare function curatedInstrumentations(config: Config, sampling?: CallSiteSampling): Instrumentation[];
+/**
+ * prismaInstrumentation loads @prisma/instrumentation from the application
+ * when the application has it (Prisma ships it beside its client, and its
+ * version must match the client's), and nothing otherwise.
+ */
+export declare function prismaInstrumentation(cwd: string): Instrumentation | undefined;
+/** current returns the running SDK, if any. */
+export declare function current(): Started | undefined;
+/**
+ * start reads the configuration and starts the SDK once per process. A
+ * later call (the import line and NODE_OPTIONS both, or a second copy of
+ * the package) returns the first result. It never throws.
+ */
+export declare function start(options?: StartOptions): Started | undefined;
+/** otlpExporter builds the package's OTLP/HTTP protobuf exporter (see otlp.ts). */
+export declare function otlpExporter(url: string): SpanExporter;