autotel 6.5.0 → 7.0.1

package/dist/exception-fingerprint.d.cts

@@ -0,0 +1,51 @@
+import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+//#region src/exception-fingerprint.d.ts
+/** Attribute the fingerprint is written to. */
+declare const EXCEPTION_FINGERPRINT_ATTRIBUTE = "exception.fingerprint";
+interface ExceptionInput {
+  /** Error class name, e.g. `TypeError`. Defaults to `Error`. */
+  type?: string;
+  /** Error message. Only used for grouping when there is no usable stack. */
+  message?: string;
+  /** Raw stack string, as `Error.stack` produces it. */
+  stack?: string;
+}
+/**
+ * Collapse a path to the part that identifies the code rather than the machine
+ * it ran on: a dependency becomes its package name, and an absolute path
+ * becomes the project-relative one. Without this, the same error fingerprints
+ * differently in CI, in Docker, and on a laptop.
+ */
+declare function normalizeFilePath(filePath: string): string;
+/**
+ * Strip the parts of a message that change on every occurrence, so
+ * `timeout after 341ms` and `timeout after 78ms` are one issue rather than two.
+ */
+declare function normalizeMessage(message: string): string;
+/**
+ * `function@normalized-path` for the top N frames. Line and column are
+ * deliberately dropped: an edit one line above the throw is the same bug.
+ */
+declare function normalizeStackFrames(stack: string, count: number): string[];
+/** 32-bit djb2-style hash, rendered as 8 hex characters. */
+declare function hashFingerprintParts(parts: string[]): string;
+/**
+ * Group key for an exception. Returns `undefined` when there is nothing to
+ * group on, so callers never write an attribute that means "no information".
+ */
+declare function fingerprintException(input: ExceptionInput, frames?: number): string | undefined;
+interface ExceptionFingerprintOptions {
+  /** Stack frames to fingerprint on. @default 5 */
+  frames?: number;
+}
+/**
+ * Span enricher that stamps {@link EXCEPTION_FINGERPRINT_ATTRIBUTE} on every
+ * span that recorded an exception.
+ *
+ * Pass it to `init({ spanEnrichers: [...] })` rather than `spanProcessors`:
+ * enrichers add to the pipeline instead of replacing it, and sit outside the
+ * redaction wrapper so the attribute reaches every exporter.
+ */
+declare function exceptionFingerprint(options?: ExceptionFingerprintOptions): SpanProcessor;
+//#endregion
+export { EXCEPTION_FINGERPRINT_ATTRIBUTE, ExceptionFingerprintOptions, ExceptionInput, exceptionFingerprint, fingerprintException, hashFingerprintParts, normalizeFilePath, normalizeMessage, normalizeStackFrames };

package/dist/exception-fingerprint.d.ts

@@ -0,0 +1,51 @@
+import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+//#region src/exception-fingerprint.d.ts
+/** Attribute the fingerprint is written to. */
+declare const EXCEPTION_FINGERPRINT_ATTRIBUTE = "exception.fingerprint";
+interface ExceptionInput {
+  /** Error class name, e.g. `TypeError`. Defaults to `Error`. */
+  type?: string;
+  /** Error message. Only used for grouping when there is no usable stack. */
+  message?: string;
+  /** Raw stack string, as `Error.stack` produces it. */
+  stack?: string;
+}
+/**
+ * Collapse a path to the part that identifies the code rather than the machine
+ * it ran on: a dependency becomes its package name, and an absolute path
+ * becomes the project-relative one. Without this, the same error fingerprints
+ * differently in CI, in Docker, and on a laptop.
+ */
+declare function normalizeFilePath(filePath: string): string;
+/**
+ * Strip the parts of a message that change on every occurrence, so
+ * `timeout after 341ms` and `timeout after 78ms` are one issue rather than two.
+ */
+declare function normalizeMessage(message: string): string;
+/**
+ * `function@normalized-path` for the top N frames. Line and column are
+ * deliberately dropped: an edit one line above the throw is the same bug.
+ */
+declare function normalizeStackFrames(stack: string, count: number): string[];
+/** 32-bit djb2-style hash, rendered as 8 hex characters. */
+declare function hashFingerprintParts(parts: string[]): string;
+/**
+ * Group key for an exception. Returns `undefined` when there is nothing to
+ * group on, so callers never write an attribute that means "no information".
+ */
+declare function fingerprintException(input: ExceptionInput, frames?: number): string | undefined;
+interface ExceptionFingerprintOptions {
+  /** Stack frames to fingerprint on. @default 5 */
+  frames?: number;
+}
+/**
+ * Span enricher that stamps {@link EXCEPTION_FINGERPRINT_ATTRIBUTE} on every
+ * span that recorded an exception.
+ *
+ * Pass it to `init({ spanEnrichers: [...] })` rather than `spanProcessors`:
+ * enrichers add to the pipeline instead of replacing it, and sit outside the
+ * redaction wrapper so the attribute reaches every exporter.
+ */
+declare function exceptionFingerprint(options?: ExceptionFingerprintOptions): SpanProcessor;
+//#endregion
+export { EXCEPTION_FINGERPRINT_ATTRIBUTE, ExceptionFingerprintOptions, ExceptionInput, exceptionFingerprint, fingerprintException, hashFingerprintParts, normalizeFilePath, normalizeMessage, normalizeStackFrames };

package/dist/exception-fingerprint.js

@@ -0,0 +1,126 @@
+import { g as nonEmptyString } from "./values-BenyvWKz.js";
+
+//#region src/exception-fingerprint.ts
+/** Attribute the fingerprint is written to. */
+const EXCEPTION_FINGERPRINT_ATTRIBUTE = "exception.fingerprint";
+/**
+* Frames deep enough to separate two different bugs, shallow enough that the
+* same bug reached through different callers still groups.
+*/
+const DEFAULT_FRAMES = 5;
+const NODE_FRAME = /^at\s+(.+?)\s+\((.+?):(\d+):\d+\)$/;
+const ANON_FRAME = /^at\s+(.+?):(\d+):\d+$/;
+const BROWSER_FRAME = /^(.+?)@(.+?):(\d+):\d+$/;
+/**
+* Collapse a path to the part that identifies the code rather than the machine
+* it ran on: a dependency becomes its package name, and an absolute path
+* becomes the project-relative one. Without this, the same error fingerprints
+* differently in CI, in Docker, and on a laptop.
+*/
+function normalizeFilePath(filePath) {
+	const nodeModulesMatch = filePath.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/);
+	if (nodeModulesMatch) return `[npm]/${nodeModulesMatch[1]}`;
+	return filePath.replace(/^.*?\/src\//, "src/").replace(/^.*?\/dist\//, "dist/").replace(/^.*?\/lib\//, "lib/").replace(/^file:\/\//, "");
+}
+/**
+* Strip the parts of a message that change on every occurrence, so
+* `timeout after 341ms` and `timeout after 78ms` are one issue rather than two.
+*/
+function normalizeMessage(message) {
+	return message.replaceAll(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "[UUID]").replaceAll(/\b[0-9a-f]{16,}\b/gi, "[ID]").replaceAll(/\d+/g, "[N]").replaceAll(/"[^"]*"/g, "\"[STR]\"").replaceAll(/'[^']*'/g, "'[STR]'").slice(0, 200);
+}
+/**
+* `function@normalized-path` for the top N frames. Line and column are
+* deliberately dropped: an edit one line above the throw is the same bug.
+*/
+function normalizeStackFrames(stack, count) {
+	const frames = [];
+	for (const line of stack.split("\n")) {
+		if (frames.length >= count) break;
+		const trimmed = line.trim();
+		const node = NODE_FRAME.exec(trimmed);
+		if (node) {
+			frames.push(`${node[1] ?? "anonymous"}@${normalizeFilePath(node[2] ?? "")}`);
+			continue;
+		}
+		const anon = ANON_FRAME.exec(trimmed);
+		if (anon) {
+			frames.push(`anonymous@${normalizeFilePath(anon[1] ?? "")}`);
+			continue;
+		}
+		const browser = BROWSER_FRAME.exec(trimmed);
+		if (browser) frames.push(`${browser[1] ?? "anonymous"}@${normalizeFilePath(browser[2] ?? "")}`);
+	}
+	return frames;
+}
+/** 32-bit djb2-style hash, rendered as 8 hex characters. */
+function hashFingerprintParts(parts) {
+	const value = parts.join("|");
+	let hash = 0;
+	for (let index = 0; index < value.length; index++) {
+		hash = (hash << 5) - hash + value.charCodeAt(index);
+		hash = hash & hash;
+	}
+	return Math.abs(hash).toString(16).padStart(8, "0");
+}
+/**
+* Group key for an exception. Returns `undefined` when there is nothing to
+* group on, so callers never write an attribute that means "no information".
+*/
+function fingerprintException(input, frames = DEFAULT_FRAMES) {
+	const stackFrames = input.stack ? normalizeStackFrames(input.stack, frames) : [];
+	if (stackFrames.length === 0 && !input.message && !input.type) return;
+	const parts = [input.type || "Error"];
+	if (stackFrames.length > 0) parts.push(...stackFrames);
+	else if (input.message) parts.push(normalizeMessage(input.message));
+	return hashFingerprintParts(parts);
+}
+/**
+* Read the error off a finished span, wherever it was recorded: the OTel
+* `exception` event, the `exception.*` attributes autotel-web sets, or the
+* `error.*` attributes structured errors write instead of an event.
+*/
+function readException(span) {
+	const { attributes } = span;
+	const event = span.events?.find((e) => e.name === "exception");
+	const eventAttributes = event?.attributes ?? {};
+	const type = nonEmptyString(attributes["exception.type"]) ?? nonEmptyString(attributes["error.type"]) ?? nonEmptyString(eventAttributes["exception.type"]);
+	const stack = nonEmptyString(attributes["exception.stacktrace"]) ?? nonEmptyString(attributes["exception.stack"]) ?? nonEmptyString(attributes["error.stack"]) ?? nonEmptyString(eventAttributes["exception.stacktrace"]) ?? nonEmptyString(eventAttributes["exception.stack"]);
+	if (!type && !stack && !event) return void 0;
+	return {
+		type,
+		message: nonEmptyString(attributes["exception.message"]) ?? nonEmptyString(attributes["error.message"]) ?? nonEmptyString(eventAttributes["exception.message"]) ?? nonEmptyString(span.status.message),
+		stack
+	};
+}
+/**
+* Span enricher that stamps {@link EXCEPTION_FINGERPRINT_ATTRIBUTE} on every
+* span that recorded an exception.
+*
+* Pass it to `init({ spanEnrichers: [...] })` rather than `spanProcessors`:
+* enrichers add to the pipeline instead of replacing it, and sit outside the
+* redaction wrapper so the attribute reaches every exporter.
+*/
+function exceptionFingerprint(options = {}) {
+	const frames = options.frames ?? DEFAULT_FRAMES;
+	return {
+		onStart(_span, _context) {},
+		onEnd(span) {
+			const { attributes } = span;
+			if (attributes["exception.fingerprint"] !== void 0) return;
+			const exception = readException(span);
+			if (!exception) return;
+			const fingerprint = fingerprintException(exception, frames);
+			if (fingerprint) attributes[EXCEPTION_FINGERPRINT_ATTRIBUTE] = fingerprint;
+		},
+		forceFlush() {
+			return Promise.resolve();
+		},
+		shutdown() {
+			return Promise.resolve();
+		}
+	};
+}
+
+//#endregion
+export { EXCEPTION_FINGERPRINT_ATTRIBUTE, exceptionFingerprint, fingerprintException, hashFingerprintParts, normalizeFilePath, normalizeMessage, normalizeStackFrames };

package/dist/{functional-C0uAZq2X.cjs → functional-C2ONG9PK.cjs}

@@ -1,8 +1,9 @@
 const require_rolldown_runtime = require('./rolldown-runtime-C_NdSu1c.cjs');
+const require_values = require('./values-DApyq53y.cjs');
 const require_tracer_provider = require('./tracer-provider.cjs');
 const require_config = require('./config.cjs');
 const require_sampling = require('./sampling.cjs');
-const require_init = require('./init-CTtHITlX.cjs');
+const require_init = require('./init-C5aHRqi2.cjs');
 const require_trace_helpers = require('./trace-helpers.cjs');
 let _opentelemetry_api = require("@opentelemetry/api");
 let node_fs = require("node:fs");
@@ -178,9 +179,9 @@ function getSpanName(options, fn, variableName) {
 	if (options.serviceName) return `${options.serviceName}.${fnName}`;
 	if (fnName !== "anonymous") return fnName;
 	const initConfig = require_init.getConfig();
-	if (typeof process !== "undefined" && process.env.NODE_ENV !== "production" && !unknownSpanNameWarningEmitted && initConfig?.logger?.warn) {
+	if (require_values.isDevelopment() && !unknownSpanNameWarningEmitted && initConfig?.logger?.warn) {
 		unknownSpanNameWarningEmitted = true;
-		initConfig.logger.warn({}, "[autotel] Span name resolved to \"unknown\". Pass an explicit name, for example trace(\"operation.name\", fn).");
+		initConfig.logger.warn({}, "[autotel] Span name resolved to \"unknown\". Use instrument({ key: \"operation.name\", fn }) for a reusable named wrapper.");
 	}
 	return "unknown";
 }
@@ -207,7 +208,7 @@ function createDummyCtx() {
 function serializeCapture(value) {
 	if (value === void 0) return void 0;
 	try {
-		const json = typeof value === "string" ? value : JSON.stringify(value);
+		const json = require_values.asString(value) ?? JSON.stringify(value);
 		if (json === void 0) return void 0;
 		return json.length > CAPTURE_MAX_CHARS ? `${json.slice(0, CAPTURE_MAX_CHARS)}…[truncated]` : json;
 	} catch {
@@ -333,7 +334,7 @@ function wrapWithTracingSync(fnFactory, options, variableName) {
 			const fn = fnFactory(require_init.createTraceContext(span));
 			const argsAttributes = {
 				...captureInputAttrs(args, options.captureInput),
-				...options.attributesFromArgs ? options.attributesFromArgs(args) : {}
+				...options.attributesFromArgs?.(args)
 			};
 			const handleTailSampling = (success, duration, error) => {
 				if (needsTailSampling && sampler.shouldKeepTrace) {
@@ -358,9 +359,9 @@ function wrapWithTracingSync(fnFactory, options, variableName) {
 				});
 				const resultAttributes = {
 					...captureOutputAttrs(result, options.captureOutput),
-					...options.attributesFromResult ? options.attributesFromResult(result) : {}
+					...options.attributesFromResult?.(result)
 				};
-				span.setStatus({ code: _opentelemetry_api.SpanStatusCode.OK });
+				if (!require_init.hasExplicitSpanStatus(span)) span.setStatus({ code: _opentelemetry_api.SpanStatusCode.OK });
 				span.setAttributes({
 					...argsAttributes,
 					...resultAttributes,
@@ -373,8 +374,8 @@ function wrapWithTracingSync(fnFactory, options, variableName) {
 				span.end();
 				return result;
 			};
-			const onError = (error) => {
-				finalizeThrownSpan(error, options.isError, {
+			const onError = (cause) => {
+				finalizeThrownSpan(cause, options.isError, {
 					span,
 					spanName,
 					duration: performance.now() - startTime,
@@ -383,7 +384,7 @@ function wrapWithTracingSync(fnFactory, options, variableName) {
 					handleTailSampling,
 					extraAttributes: argsAttributes
 				});
-				throw error;
+				throw cause;
 			};
 			try {
 				callCounter?.add(1, {
@@ -428,6 +429,10 @@ function wrapFactoryWithTracing(factory, options, variableName) {
 function wrapPlainWithTracing(fn, options, variableName) {
 	return wrapWithTracingSync((_ctx) => fn, options, resolveVariableName(fn, variableName));
 }
+/** Run one operation immediately with its span-bound context. */
+function runWithTraceContext(operation, options) {
+	return wrapFactoryWithTracing((ctx) => () => operation(ctx), options)();
+}
 
 //#endregion
 //#region src/functional.ts
@@ -493,7 +498,7 @@ function getCtxValue() {
 *
 * @example
 * ```typescript
-* const getUser = trace('getUser', async (id: string) => {
+* const getUser = trace(async function getUser(id: string) {
 *   getActiveTraceContext()?.setAttribute('user.id', id);
 *   return db.users.find(id);
 * });
@@ -523,7 +528,8 @@ function getActiveTraceContext() {
 * })
 * ```
 */
-const ctx = new Proxy({}, {
+const ctxProxyTarget = {};
+const ctx = new Proxy(ctxProxyTarget, {
 	get(_target, prop) {
 		const ctxValue = getCtxValue();
 		if (!ctxValue) return;
@@ -545,11 +551,17 @@ const ctx = new Proxy({}, {
 		return Object.getOwnPropertyDescriptor(ctxValue, prop);
 	}
 });
-function trace(fnOrNameOrOptions, maybeFn) {
+function traceImpl(fnOrNameOrOptions, maybeFn) {
 	if (typeof fnOrNameOrOptions === "function") return wrapPlainWithTracing(fnOrNameOrOptions, {});
-	if (!maybeFn) throw new Error("trace(name|options, fn): fn is required");
-	return wrapPlainWithTracing(maybeFn, typeof fnOrNameOrOptions === "string" ? { name: fnOrNameOrOptions } : fnOrNameOrOptions);
+	const options = typeof fnOrNameOrOptions === "string" ? { name: fnOrNameOrOptions } : fnOrNameOrOptions;
+	if (maybeFn === void 0) return ((fn) => wrapPlainWithTracing(fn, options));
+	return wrapPlainWithTracing(maybeFn, options);
+}
+function run(nameOrOptions, operation) {
+	if (typeof operation !== "function") throw new TypeError("trace.run(name, operation): operation must be a function");
+	return runWithTraceContext(operation, typeof nameOrOptions === "string" ? { name: nameOrOptions } : nameOrOptions);
 }
+const trace = Object.assign(traceImpl, { run });
 /**
 * Approach 2: withTracing() - Middleware-style composable wrapper
 *

package/dist/{functional-e6jw5zQj.d.cts → functional-CJn2zY4o.d.cts}

@@ -1,6 +1,6 @@
-import { n as TraceContext } from "./trace-context-IuyoPyNq.cjs";
-import { p as Sampler } from "./sampling-BR9fkSwx.cjs";
-import { Span, SpanKind } from "@opentelemetry/api";
+import { n as TraceContext } from "./trace-context-C1Cn1q0y.cjs";
+import { p as Sampler } from "./sampling-CmRdnXUi.cjs";
+import { Attributes, Span, SpanKind } from "@opentelemetry/api";
 //#region src/functional-wrapper.d.ts
 type WrappedFunction<TArgs extends unknown[], TReturn> = (...args: TArgs) => TReturn | Promise<TReturn>;
 /**
@@ -35,9 +35,10 @@ interface TracingOptions<TArgs extends unknown[] = unknown[], TReturn = unknown>
    */
   withMetrics?: boolean;
   /** Extract attributes from function arguments. */
-  attributesFromArgs?: (args: TArgs) => Record<string, unknown>;
+  attributesFromArgs?: (args: TArgs) => Attributes;
   /** Extract attributes from the function result. */
-  attributesFromResult?: (result: TReturn) => Record<string, unknown>;
+  /** Receives the resolved value when the function returns a Promise. */
+  attributesFromResult?: (result: Awaited<TReturn>) => Attributes;
   /**
    * Capture arguments on the span as the truncated JSON `autotel.input`
    * attribute. One argument is captured directly; multiple arguments are an
@@ -72,7 +73,7 @@ interface TracingOptions<TArgs extends unknown[] = unknown[], TReturn = unknown>
    * as `redirect()` and `notFound()`.
    * @default every throw is treated as an error
    */
-  isError?: (error: unknown) => boolean;
+  isError?: (cause: unknown) => boolean;
 }
 /** Options for `instrument()` batch instrumentation. */
 interface InstrumentOptions<T extends Record<string, AnyInstrumentable> = Record<string, AnyInstrumentable>> extends TracingOptions {
@@ -95,6 +96,33 @@ interface SingleInstrumentOptions<TFunction extends AnyInstrumentable = AnyInstr
 }
 //#endregion
 //#region src/functional.d.ts
+/**
+ * Complete trace context containing trace identifiers and span methods
+ *
+ * The ctx parameter in trace() functions provides:
+ * - traceId, spanId, correlationId from the active span
+ * - Span manipulation methods (setAttribute, setAttributes, setStatus, recordException)
+ *
+ * For custom context, access it directly in your functions (standard OpenTelemetry pattern).
+ *
+ * @example
+ * ```typescript
+ * import { trace } from 'autotel'
+ *
+ * export const createUser = withTracing({})((ctx) => async (data: CreateUserData) => {
+ *   // Get custom context directly (standard OTel approach)
+ *   const userId = getCurrentUserId()
+ *   const tenantId = getCurrentTenant()
+ *
+ *   // Use ctx for span operations and trace IDs
+ *   ctx.setAttribute('user.id', data.id)
+ *   ctx.setAttribute('user.tenant', tenantId)
+ *   console.log(ctx.traceId)  // Trace IDs available
+ * })
+ * ```
+ */
+/** Baggage entries: values that survive the W3C baggage header. */
+type BaggageValues = Record<string, string | number | boolean>;
 /**
  * Get the autotel {@link TraceContext} for the currently active span.
  *
@@ -105,7 +133,7 @@ interface SingleInstrumentOptions<TFunction extends AnyInstrumentable = AnyInstr
  *
  * @example
  * ```typescript
- * const getUser = trace('getUser', async (id: string) => {
+ * const getUser = trace(async function getUser(id: string) {
  *   getActiveTraceContext()?.setAttribute('user.id', id);
  *   return db.users.find(id);
  * });
@@ -114,34 +142,17 @@ interface SingleInstrumentOptions<TFunction extends AnyInstrumentable = AnyInstr
  * @see getActiveSpan for the raw OpenTelemetry span
  * @see getRequestLogger which reads the active context when called with no args
  */
-declare function getActiveTraceContext<TBaggage extends Record<string, unknown> | undefined = undefined>(): TraceContext<TBaggage> | undefined;
-/**
- * Context object that lazily evaluates the active span on property access
- *
- * Access trace context directly without function call syntax.
- *
- * @example
- * ```typescript
- * import { trace, ctx } from 'autotel'
- *
- * export const createUser = trace(async (data) => {
- *   // Direct property access - no function call!
- *   if (ctx.traceId) {
- *     ctx.setAttribute('user.id', data.id)
- *     console.log('Trace:', ctx.traceId)
- *   }
- * })
- * ```
- */
+declare function getActiveTraceContext<TBaggage extends BaggageValues | undefined = undefined>(): TraceContext<TBaggage> | undefined;
 declare const ctx: TraceContext;
 /**
- * Wrap a plain function with automatic tracing. The function receives its real
- * arguments; no context parameter is injected. Use
- * {@link getActiveTraceContext} inside the function, or use {@link withTracing}
- * for the explicit `(ctx) => (...args) => result` factory form.
+ * Wrap a plain function with a traced wrapper, or run one named operation
+ * immediately with {@link trace.run}.
  *
- * `trace()` never executes or inspects the function during wrapper
- * construction.
+ * Every `trace(...)` call returns a **wrapper**. Nothing runs until you call
+ * what you get back, so a `trace()` call can never execute your function at
+ * module load. Reach the span from inside the body through the ambient
+ * {@link ctx} - it resolves at any depth, so a helper three frames down sees
+ * the same span without being handed anything.
  *
  * @example Auto-inferred name
  * ```typescript
@@ -150,24 +161,70 @@ declare const ctx: TraceContext;
  * })
  * ```
  *
- * @example Ambient context access
+ * @example Explicit name
  * ```typescript
- * export const createUser = trace(async (data) => {
- *   getActiveTraceContext()?.setAttribute('user.id', data.id)
+ * export const createUser = trace('user.create', async (data) => {
  *   return await db.users.create(data)
  * })
  * ```
  *
- * @example Explicit name
+ * @example Ambient context, at any depth
  * ```typescript
+ * import { trace, ctx } from 'autotel'
+ *
  * export const createUser = trace('user.create', async (data) => {
+ *   ctx.setAttribute('user.id', data.id)
  *   return await db.users.create(data)
  * })
  * ```
+ *
+ * @example Curried, for a shared configuration
+ * ```typescript
+ * const traced = trace({ serviceName: 'users' })
+ * export const createUser = traced(async (data) => db.users.create(data))
+ * ```
+ *
+ * @example One operation, run now - see {@link trace.run}
+ * ```typescript
+ * const user = await trace.run('user.create', async (ctx) => {
+ *   ctx.setAttribute('user.id', input.id)
+ *   return db.users.create(input)
+ * })
+ * ```
+ */
+declare function traceImpl<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function traceImpl<TArgs extends unknown[], TReturn>(name: string, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function traceImpl<TArgs extends unknown[], TReturn>(options: TracingOptions<TArgs, TReturn>, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function traceImpl(name: string): <TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
+declare function traceImpl<TArgs extends unknown[], TReturn>(options: TracingOptions<TArgs, TReturn>): (fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
+/**
+ * Run one named operation immediately and return its result, with the
+ * {@link TraceContext} passed in.
+ *
+ * This is the counterpart to {@link trace}: `trace(...)` always hands back a
+ * wrapper to call later, `trace.run(...)` runs the operation now. Keeping them
+ * under separate names is deliberate - a single call shape that sometimes
+ * wrapped and sometimes ran is what made dispatch depend on a callback's
+ * parameter name, which a minifier is free to rewrite (#166).
+ *
+ * The body can equally read the ambient {@link ctx}; the parameter is here for
+ * when an explicit binding reads better.
+ *
+ * @example
+ * ```typescript
+ * const user = await trace.run('user.create', async (ctx) => {
+ *   ctx.setAttribute('user.id', input.id)
+ *   return db.users.create(input)
+ * })
+ * ```
  */
-declare function trace$1<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-declare function trace$1<TArgs extends unknown[], TReturn>(name: string, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-declare function trace$1<TArgs extends unknown[], TReturn>(options: TracingOptions<TArgs, TReturn>, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function run<TReturn>(name: string, operation: (ctx: TraceContext) => Promise<TReturn>): Promise<TReturn>;
+declare function run<TReturn>(name: string, operation: (ctx: TraceContext) => TReturn): TReturn;
+declare function run<TReturn>(options: TracingOptions<[], TReturn>, operation: (ctx: TraceContext) => Promise<TReturn>): Promise<TReturn>;
+declare function run<TReturn>(options: TracingOptions<[], TReturn>, operation: (ctx: TraceContext) => TReturn): TReturn;
+declare const trace$1: typeof traceImpl & {
+  run: typeof run;
+};
 /**
  * Approach 2: withTracing() - Middleware-style composable wrapper
  *