@vercube/telemetry 1.3.0

package/dist/VercubeContextManager-n4jHlB-w.mjs

@@ -0,0 +1,197 @@
+import { ROOT_CONTEXT, TraceFlags, createTraceState, isSpanContextValid, trace } from "@opentelemetry/api";
+//#region src/Common/Propagation.ts
+/** Header carrying the sampled parent span, per W3C Trace Context. */
+const TRACEPARENT_HEADER = "traceparent";
+/** Header carrying vendor-specific trace state, per W3C Trace Context. */
+const TRACESTATE_HEADER = "tracestate";
+/**
+* `version-traceid-spanid-flags`, with anything after the flags tolerated so
+* that a future version of the spec still parses as version `00` would.
+*/
+const TRACEPARENT_REGEX = /^([\da-f]{2})-([\da-f]{32})-([\da-f]{16})-([\da-f]{2})(-.*)?$/;
+/** All-zero ids are explicitly invalid. */
+const INVALID_TRACE_ID = "0".repeat(32);
+const INVALID_SPAN_ID = "0".repeat(16);
+/**
+* W3C Trace Context propagator.
+*
+* The reference implementation lives in `@opentelemetry/core`, which is an SDK
+* package. Propagation has to work with nothing but `@opentelemetry/api`
+* installed - a service that only forwards trace context should not need an
+* exporter - so the format is implemented here instead. It is two headers and a
+* fixed-width string.
+*/
+var W3CTraceContextPropagator = class {
+	/**
+	* Writes the active span context into the carrier.
+	*
+	* @param context - The context to read the active span from
+	* @param carrier - The carrier to write into
+	* @param setter - Writer for the carrier
+	*/
+	inject(context, carrier, setter) {
+		const spanContext = trace.getSpanContext(context);
+		if (!spanContext || !isSpanContextValid(spanContext)) return;
+		const flags = (spanContext.traceFlags ?? TraceFlags.NONE).toString(16).padStart(2, "0");
+		setter.set(carrier, TRACEPARENT_HEADER, `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`);
+		const state = spanContext.traceState?.serialize();
+		if (state) setter.set(carrier, TRACESTATE_HEADER, state);
+	}
+	/**
+	* Reads a remote span context out of the carrier.
+	*
+	* @param context - The context to extend
+	* @param carrier - The carrier to read from
+	* @param getter - Reader for the carrier
+	* @returns The context, with the remote span context attached when the headers were valid
+	*/
+	extract(context, carrier, getter) {
+		const header = firstValue(getter.get(carrier, TRACEPARENT_HEADER));
+		if (header === void 0) return context;
+		const match = TRACEPARENT_REGEX.exec(header.trim());
+		if (!match) return context;
+		const [, version, traceId, spanId, flags] = match;
+		if (version === "ff" || traceId === INVALID_TRACE_ID || spanId === INVALID_SPAN_ID) return context;
+		const state = firstValue(getter.get(carrier, TRACESTATE_HEADER));
+		return trace.setSpanContext(context, {
+			traceId,
+			spanId,
+			traceFlags: Number.parseInt(flags, 16) & TraceFlags.SAMPLED,
+			isRemote: true,
+			traceState: state ? createTraceState(state) : void 0
+		});
+	}
+	/**
+	* The header names this propagator manages.
+	*
+	* @returns The list of header names
+	*/
+	fields() {
+		return [TRACEPARENT_HEADER, TRACESTATE_HEADER];
+	}
+};
+/**
+* Reads headers off a `Headers` object or a plain record.
+*/
+const headersGetter = {
+	keys(carrier) {
+		if (carrier instanceof Headers) return [...carrier.keys()];
+		return carrier ? Object.keys(carrier) : [];
+	},
+	get(carrier, key) {
+		if (carrier instanceof Headers) return carrier.get(key) ?? void 0;
+		const value = carrier?.[key];
+		return typeof value === "string" ? value : void 0;
+	}
+};
+/**
+* Writes headers to a `Headers` object or a plain record.
+*/
+const headersSetter = { set(carrier, key, value) {
+	if (carrier instanceof Headers) {
+		carrier.set(key, value);
+		return;
+	}
+	if (carrier && typeof carrier === "object") carrier[key] = value;
+} };
+/**
+* Normalizes the `string | string[] | undefined` a getter may return.
+*
+* @param value - The raw getter result
+* @returns The first value, or undefined
+*/
+function firstValue(value) {
+	if (Array.isArray(value)) return value[0];
+	return value ?? void 0;
+}
+//#endregion
+//#region src/Context/VercubeContextManager.ts
+/**
+* OpenTelemetry context manager backed by Vercube's request context.
+*
+* OpenTelemetry ships `AsyncLocalStorageContextManager`, which allocates its
+* own `AsyncLocalStorage`. Vercube already opens one frame per request for
+* {@link RequestContext}, and a second async-context frame costs a measurable
+* slice of throughput on a framework whose fast path is otherwise
+* allocation-free. This manager stores the OpenTelemetry context inside the
+* frame that already exists.
+*
+* Nested frames share the request's root frame, so values written with
+* `RequestContext.set()` from inside a span are still visible after it ends.
+*/
+var VercubeContextManager = class {
+	/** The request context this manager stores OpenTelemetry contexts in. */
+	fRequestContext;
+	/** Whether the manager is currently active. */
+	fEnabled = false;
+	/**
+	* @param requestContext - The application's request context service
+	*/
+	constructor(requestContext) {
+		this.fRequestContext = requestContext;
+	}
+	/**
+	* The context active in the current async frame.
+	*
+	* @returns The active context, or the root context outside any frame
+	*/
+	active() {
+		if (!this.fEnabled) return ROOT_CONTEXT;
+		return this.fRequestContext.getOtelContext() ?? ROOT_CONTEXT;
+	}
+	/**
+	* Runs `fn` with `context` active.
+	*
+	* The result is passed through unchanged, so a synchronous callback stays
+	* synchronous - the request fast path depends on it.
+	*
+	* @param context - The context to activate
+	* @param fn - The function to run
+	* @param thisArg - `this` for the call
+	* @param args - Arguments for the call
+	* @returns Whatever `fn` returned
+	*/
+	with(context, fn, thisArg, ...args) {
+		if (!this.fEnabled) return fn.call(thisArg, ...args);
+		return this.fRequestContext.runWithOtelContext(context, () => fn.call(thisArg, ...args));
+	}
+	/**
+	* Binds a target to a context.
+	*
+	* Only functions are bound. OpenTelemetry's own manager additionally rebinds
+	* every listener of an `EventEmitter`; nothing in Vercube relies on that, and
+	* doing it would mean reaching into Node's emitter internals.
+	*
+	* @param context - The context to bind to
+	* @param target - The value to bind
+	* @returns The bound value, or the value unchanged when it is not a function
+	*/
+	bind(context, target) {
+		if (typeof target !== "function") return target;
+		const fn = target;
+		const activate = (run) => this.with(context, run);
+		return function bound(...args) {
+			return activate(() => fn.apply(this, args));
+		};
+	}
+	/**
+	* Activates the manager.
+	*
+	* @returns This manager
+	*/
+	enable() {
+		this.fEnabled = true;
+		return this;
+	}
+	/**
+	* Deactivates the manager. Everything falls back to the root context.
+	*
+	* @returns This manager
+	*/
+	disable() {
+		this.fEnabled = false;
+		return this;
+	}
+};
+//#endregion
+export { headersSetter as i, W3CTraceContextPropagator as n, headersGetter as r, VercubeContextManager as t };

package/dist/index.d.mts

@@ -0,0 +1,125 @@
+import { Context, Meter, Span, SpanOptions, Tracer } from "@opentelemetry/api";
+import { App, BasePlugin, ConfigTypes, TelemetryTypes } from "@vercube/core";
+//#region src/Common/Telemetry.d.ts
+/**
+ * Dependency-injection token and public API for telemetry.
+ *
+ * Injected the same way as `Logger`:
+ *
+ * ```ts
+ * class InvoiceService {
+ *   @Inject(Telemetry)
+ *   private gTelemetry!: Telemetry;
+ *
+ *   public async refund(id: string) {
+ *     return this.gTelemetry.span('invoice.refund', (span) => {
+ *       span.setAttribute('invoice.id', id);
+ *       return this.doRefund(id);
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * The token is only bound when telemetry is enabled, so inject it with
+ * `@InjectOptional` from code that must also run without it.
+ */
+export declare abstract class Telemetry {
+  /** Tracer for the application's own spans. */
+  abstract get tracer(): Tracer;
+  /** Meter for the application's own instruments. */
+  abstract get meter(): Meter;
+  /**
+   * Runs `fn` inside a new span that ends when the work settles.
+   *
+   * The return value is passed through unchanged, so wrapping synchronous code
+   * does not make it asynchronous.
+   *
+   * @param name - Span name
+   * @param fn - The work to trace
+   * @param options - Span kind, attributes and links
+   * @returns Whatever `fn` returned
+   */
+  abstract span<T>(name: string, fn: (span: Span) => T, options?: SpanOptions): T;
+  /** The span currently active on this async execution path, if any. */
+  abstract activeSpan(): Span | undefined;
+  /** Trace id of the active span, in lowercase hex. */
+  abstract get traceId(): string | undefined;
+  /** Span id of the active span, in lowercase hex. */
+  abstract get spanId(): string | undefined;
+  /**
+   * Writes W3C trace context headers for the active span into a carrier, so a
+   * downstream service continues the same trace.
+   *
+   * @param carrier - `Headers` or a plain header record to write into
+   */
+  abstract inject(carrier: Headers | Record<string, string>): void;
+  /**
+   * Reads W3C trace context headers into a context usable as a span parent.
+   *
+   * @param headers - Incoming headers
+   * @returns A context carrying the remote parent
+   */
+  abstract extract(headers: Headers | Record<string, string>): Context;
+  /**
+   * Registers work to run on {@link Telemetry.flush}.
+   *
+   * @param flush - Flushes whatever the caller has buffered
+   */
+  abstract onFlush(flush: () => Promise<void>): void;
+  /**
+   * Pushes out everything buffered by batching drains and exporters.
+   *
+   * Call it before a process that may be frozen or killed goes away - a
+   * serverless invocation, a graceful shutdown - or telemetry produced at the
+   * very end of its life never leaves.
+   */
+  abstract flush(): Promise<void>;
+}
+//#endregion
+//#region src/Plugins/TelemetryPlugin.d.ts
+/**
+ * Activates OpenTelemetry instrumentation for the application.
+ *
+ * Register it in `vercube.config.ts`:
+ *
+ * ```ts
+ * export default defineConfig({
+ *   telemetry: true,
+ *   plugins: [TelemetryPlugin],
+ * });
+ * ```
+ *
+ * The plugin only wires the OpenTelemetry **API**: it registers a context
+ * manager and a W3C propagator, binds the {@link Telemetry} token and installs
+ * the hooks core calls into. Producing actual spans additionally requires a
+ * `TracerProvider`, which either the application registers through the standard
+ * OpenTelemetry SDK, `@vercube/telemetry/sdk`, or `@vercube/devtools`.
+ *
+ * Options given at registration time win over the `telemetry` field of the
+ * application config.
+ */
+export declare class TelemetryPlugin extends BasePlugin<TelemetryTypes.Options> {
+  /** @inheritdoc */
+  name: string;
+  /**
+   * Starts watching container construction.
+   *
+   * This runs while the config is still being loaded, which is the only phase
+   * early enough: by the time `use()` runs the container has already built a
+   * good part of the application. Registering the plugin through
+   * `defineConfig({ plugins })` rather than `app.addPlugin()` is therefore what
+   * makes bootstrap spans complete.
+   *
+   * @param config - The merged configuration
+   * @param options - Options overriding the `telemetry` config field
+   */
+  configure(config: ConfigTypes.Config, options?: TelemetryTypes.Options): void;
+  /**
+   * Installs telemetry into the running application.
+   *
+   * @param app - The application
+   * @param options - Options overriding the `telemetry` config field
+   */
+  use(app: App, options?: TelemetryTypes.Options): void | Promise<void>;
+}
+//#endregion