@vercube/telemetry 1.3.0

package/dist/index.mjs

@@ -0,0 +1,1085 @@
+import { a as INSTRUMENTATION_SCOPE, c as URL_PATH, d as USER_AGENT_ORIGINAL, f as VERCUBE_CONTROLLER, h as VERCUBE_HANDLER, i as HTTP_ROUTE, l as URL_QUERY, m as VERCUBE_DI_KIND, n as HTTP_REQUEST_METHOD, o as SERVER_ADDRESS, p as VERCUBE_DI_KEY, r as HTTP_RESPONSE_STATUS_CODE, s as SERVER_PORT, t as ERROR_TYPE, u as URL_SCHEME } from "./Attributes-QVHj8ZgV.mjs";
+import { i as headersSetter, n as W3CTraceContextPropagator, r as headersGetter, t as VercubeContextManager } from "./VercubeContextManager-n4jHlB-w.mjs";
+import { n as errorType, o as runInSpan, r as failSpan } from "./SpanUtils-t3NCeswB.mjs";
+import { ROOT_CONTEXT, SpanKind, ValueType, context, metrics, propagation, trace } from "@opentelemetry/api";
+import { BasePlugin, RequestContext, TelemetryRegistry, getRequestPathname, getRequestSearch, isSecretKey, resolveTelemetryOptions } from "@vercube/core";
+import { Logger, enricherPlugin } from "@vercube/logger";
+import { IOC, addIOCDevtoolsHook } from "@vercube/di";
+import { monitorEventLoopDelay, performance as performance$1 } from "node:perf_hooks";
+import { getHeapStatistics } from "node:v8";
+//#region src/Common/Telemetry.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.
+*/
+var Telemetry = class {};
+//#endregion
+//#region src/Bootstrap/BootstrapSpans.ts
+/** Upper bound on buffered construction records, so a pathological app cannot exhaust memory. */
+const MAX_RECORDS = 2e4;
+/** Name of the span every construction span hangs under. */
+const BOOTSTRAP_SPAN_NAME = "vercube.bootstrap";
+/**
+* Buffers container constructions and replays them as a trace.
+*
+* Bootstrap has to be observed before the container exists, which is earlier
+* than any tracer is available, so the records are buffered and turned into
+* spans afterwards with their original timestamps. The result is that the
+* application's startup shows up in a trace viewer as an ordinary waterfall
+* rather than as a bespoke profiler view.
+*/
+var BootstrapRecorder = class {
+	/** Buffered construction records, in emission order. */
+	fRecords = [];
+	/** Removes the container observer. */
+	fDetach = null;
+	/** Whether the records have already been turned into spans. */
+	fEmitted = false;
+	/**
+	* Starts observing container construction.
+	*
+	* @returns This recorder
+	*/
+	install() {
+		if (this.fDetach) return this;
+		this.fDetach = addIOCDevtoolsHook({ onResolved: (record) => {
+			if (this.fEmitted || this.fRecords.length >= MAX_RECORDS) return;
+			this.fRecords.push(record);
+		} });
+		return this;
+	}
+	/** Whether anything is still waiting to be emitted. */
+	get pending() {
+		return !this.fEmitted && this.fRecords.length > 0;
+	}
+	/**
+	* Replays the buffered constructions as spans and stops observing.
+	*
+	* @param tracer - Tracer the spans are created on
+	*/
+	emit(tracer) {
+		if (this.fEmitted) return;
+		this.fEmitted = true;
+		this.fDetach?.();
+		this.fDetach = null;
+		const records = this.fRecords;
+		this.fRecords = [];
+		if (records.length === 0) return;
+		const origin = Math.min(...records.map((record) => record.start));
+		const end = Math.max(...records.map((record) => record.end));
+		const root = tracer.startSpan(BOOTSTRAP_SPAN_NAME, {
+			kind: SpanKind.INTERNAL,
+			root: true,
+			startTime: toEpoch(origin)
+		}, ROOT_CONTEXT);
+		for (const node of buildIntervalTree(records)) emitNode(tracer, node, trace.setSpan(ROOT_CONTEXT, root));
+		root.end(toEpoch(end));
+	}
+	/**
+	* Discards buffered records and stops observing. Used between tests.
+	*/
+	reset() {
+		this.fDetach?.();
+		this.fDetach = null;
+		this.fRecords = [];
+		this.fEmitted = false;
+	}
+};
+/**
+* The process-wide recorder.
+*
+* Bootstrap profiling has to start during config load, before any container or
+* DI-resolved service exists, so this cannot live in the container.
+*/
+const bootstrapRecorder = new BootstrapRecorder();
+/**
+* Emits one construction span and everything nested inside it.
+*
+* @param tracer - Tracer the span is created on
+* @param node - The construction to emit
+* @param parent - Context carrying the parent span
+*/
+function emitNode(tracer, node, parent) {
+	const { record } = node;
+	const span = tracer.startSpan(record.name, {
+		kind: SpanKind.INTERNAL,
+		startTime: toEpoch(record.start),
+		attributes: {
+			[VERCUBE_DI_KEY]: record.name,
+			[VERCUBE_DI_KIND]: toKind(record.type),
+			"vercube.di.context": record.context
+		}
+	}, parent);
+	const childContext = trace.setSpan(parent, span);
+	for (const child of node.children) emitNode(tracer, child, childContext);
+	span.end(toEpoch(record.end));
+}
+/**
+* Rebuilds the construction call tree from nested intervals.
+*
+* The container reports a flat stream of completed constructions, but a
+* construction that finished inside another one was nested in it, which is
+* enough to recover the tree.
+*
+* @param records - Flat records in emission order
+* @returns The roots of the reconstructed tree
+*/
+function buildIntervalTree(records) {
+	const sorted = [...records].sort((a, b) => a.start - b.start || b.end - a.end);
+	const roots = [];
+	const stack = [];
+	for (const record of sorted) {
+		const node = {
+			record,
+			children: []
+		};
+		while (stack.length > 0 && stack.at(-1).record.end < record.end) stack.pop();
+		if (stack.length === 0) roots.push(node);
+		else stack.at(-1).children.push(node);
+		stack.push(node);
+	}
+	return roots;
+}
+/**
+* Converts a `performance.now()` reading into epoch milliseconds.
+*
+* @param value - Monotonic timestamp
+* @returns Epoch milliseconds
+*/
+function toEpoch(value) {
+	return performance.timeOrigin + value;
+}
+/**
+* Names a binding's factory type.
+*
+* @param type - Factory type recorded by the container
+* @returns The kind name
+*/
+function toKind(type) {
+	if (type === IOC.ServiceFactoryType.CLASS_SINGLETON) return "singleton";
+	return type === IOC.ServiceFactoryType.CLASS ? "transient" : "instance";
+}
+//#endregion
+//#region src/Common/BodyCapture.ts
+/** Content types whose bodies are safe to decode as text. */
+const TEXT_CONTENT_TYPES = [
+	"application/json",
+	"application/ld+json",
+	"application/x-www-form-urlencoded",
+	"application/xml",
+	"application/javascript",
+	"application/graphql",
+	"text/",
+	"+json",
+	"+xml"
+];
+/** Default cap on how much of a body is kept, in bytes. */
+const DEFAULT_MAX_BODY_BYTES = 65536;
+/** Span event name carrying the request body. */
+const REQUEST_BODY_EVENT = "http.request.body";
+/** Span event name carrying the response body. */
+const RESPONSE_BODY_EVENT = "http.response.body";
+/**
+* Starts reading the incoming request body.
+*
+* The clone has to be taken **before** the application reads the stream, so
+* this must be called before the handler runs, not from the span's settle
+* callback.
+*
+* @param request - The incoming request
+* @param maxBytes - Cap on the kept prefix
+* @returns The pending preview, or undefined when there is no body worth reading
+*/
+function captureRequestBody(request, maxBytes) {
+	if (!request.body || request.method === "GET" || request.method === "HEAD") return;
+	return readBody(request.clone(), request.headers, maxBytes);
+}
+/**
+* Starts reading the outgoing response body.
+*
+* Must be called synchronously once the response exists: after the runtime
+* starts writing it to the socket there is nothing left to tee.
+*
+* @param response - The outgoing response
+* @param maxBytes - Cap on the kept prefix
+* @returns The pending preview, or undefined when there is no body
+*/
+function captureResponseBody(response, maxBytes) {
+	if (!response.body) return;
+	const contentType = response.headers.get("content-type");
+	if (contentType?.includes("text/event-stream")) return Promise.resolve(omitted(contentType, "streaming"));
+	return readBody(response.clone(), response.headers, maxBytes);
+}
+/**
+* Records a captured body as a span event.
+*
+* @param span - The span to annotate
+* @param name - Event name
+* @param preview - The captured body
+*/
+function addBodyEvent(span, name, preview) {
+	span.addEvent(name, {
+		"body.content_type": preview.contentType ?? void 0,
+		"body.size": preview.size,
+		"body.truncated": preview.truncated,
+		"body.omitted": preview.omitted,
+		"body.text": preview.text
+	});
+}
+/**
+* Reads a message body into a capped, decoded preview.
+*
+* @param message - A clone of the request or response
+* @param headers - Headers of the original message
+* @param maxBytes - Cap on the kept prefix
+* @returns The preview
+*/
+async function readBody(message, headers, maxBytes) {
+	const contentType = headers.get("content-type");
+	const declared = Number.parseInt(headers.get("content-length") ?? "", 10);
+	if (Number.isFinite(declared) && declared > maxBytes) return omitted(contentType, "too-large", declared);
+	let bytes;
+	let size;
+	try {
+		({bytes, size} = await readCapped(message, maxBytes));
+	} catch {
+		return omitted(contentType, "unreadable");
+	}
+	if (size === 0) return omitted(contentType, "empty");
+	if (!isTextual(contentType)) return omitted(contentType, "binary", size);
+	if (size > maxBytes) return {
+		contentType,
+		size,
+		text: new TextDecoder().decode(bytes).replace(/�+$/, ""),
+		truncated: true
+	};
+	try {
+		return {
+			contentType,
+			size,
+			text: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+			truncated: false
+		};
+	} catch {
+		return omitted(contentType, "binary", size);
+	}
+}
+/**
+* Streams a body, keeping at most `maxBytes` of it in memory.
+*
+* The remainder is drained rather than cancelled, so the reported size stays
+* exact and the clone's tee buffer does not grow unbounded.
+*
+* @param message - A clone of the request or response
+* @param maxBytes - Cap on the kept prefix
+* @returns The captured prefix and the total size
+*/
+async function readCapped(message, maxBytes) {
+	const reader = message.body?.getReader();
+	if (!reader) return {
+		bytes: /* @__PURE__ */ new Uint8Array(0),
+		size: 0
+	};
+	const chunks = [];
+	let captured = 0;
+	let size = 0;
+	try {
+		for (;;) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			size += value.byteLength;
+			if (captured < maxBytes) {
+				const slice = value.subarray(0, maxBytes - captured);
+				chunks.push(slice);
+				captured += slice.byteLength;
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const bytes = new Uint8Array(captured);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return {
+		bytes,
+		size
+	};
+}
+/**
+* Whether a body of this content type should be decoded as text.
+*
+* @param contentType - Declared content type, when any
+* @returns True for textual bodies
+*/
+function isTextual(contentType) {
+	if (!contentType) return true;
+	const normalized = contentType.toLowerCase();
+	return TEXT_CONTENT_TYPES.some((candidate) => normalized.includes(candidate));
+}
+/**
+* Builds a preview that carries no text, only the reason.
+*
+* @param contentType - Declared content type, when known
+* @param reason - Why the body is not shown
+* @param size - Body size in bytes, when known
+* @returns The placeholder preview
+*/
+function omitted(contentType, reason, size = 0) {
+	return {
+		contentType,
+		size,
+		truncated: false,
+		omitted: reason
+	};
+}
+//#endregion
+//#region src/Common/HeaderCapture.ts
+/**
+* Headers whose values are never recorded, whatever the configuration says.
+*
+* A recorded `Authorization` header is a leaked credential the moment the trace
+* leaves the process, and an inspector screenshot is enough. The names are
+* still recorded so it stays visible that the header was present.
+*/
+const ALWAYS_REDACTED = /* @__PURE__ */ new Set([
+	"authorization",
+	"proxy-authorization",
+	"cookie",
+	"set-cookie",
+	"x-api-key",
+	"x-auth-token",
+	"x-csrf-token"
+]);
+/** Placeholder written in place of a withheld value. */
+const REDACTED = "<redacted>";
+/** Span event name carrying the request headers. */
+const REQUEST_HEADERS_EVENT = "http.request.headers";
+/** Span event name carrying the response headers. */
+const RESPONSE_HEADERS_EVENT = "http.response.headers";
+/**
+* Records a message's headers as a span event.
+*
+* Recorded as one event with one attribute per header rather than as span
+* attributes, so they stay grouped and cannot collide with the semantic
+* conventions.
+*
+* @param span - The span to annotate
+* @param name - Event name
+* @param headers - The headers to record
+* @param extraRedacted - Additional header names to withhold, lowercase
+*/
+function addHeadersEvent(span, name, headers, extraRedacted) {
+	const attributes = {};
+	for (const [key, value] of headers) {
+		const lower = key.toLowerCase();
+		attributes[lower] = ALWAYS_REDACTED.has(lower) || extraRedacted.has(lower) ? REDACTED : value;
+	}
+	span.addEvent(name, attributes);
+}
+//#endregion
+//#region src/Hooks/CoreTelemetryHooks.ts
+/**
+* Bucket boundaries for `http.server.request.duration`, in seconds.
+* Taken from the OpenTelemetry HTTP semantic conventions.
+*/
+const DURATION_BUCKETS = [
+	.005,
+	.01,
+	.025,
+	.05,
+	.075,
+	.1,
+	.25,
+	.5,
+	.75,
+	1,
+	2.5,
+	5,
+	7.5,
+	10
+];
+/** Milliseconds per second, for converting the monotonic clock. */
+const MS_PER_SECOND$1 = 1e3;
+/**
+* The implementation core calls into.
+*
+* Turns every request into a `SERVER` span parented on the incoming
+* `traceparent`, and records the standard request duration histogram.
+*/
+var CoreTelemetryHooks = class {
+	/** The telemetry facade used for tracing and propagation. */
+	fTelemetry;
+	/** Whether to read `traceparent` from incoming requests. */
+	fPropagation;
+	/** Whether to record the request duration histogram. */
+	fMetrics;
+	/** Cap on captured body bytes, or 0 when body capture is off. */
+	fBodyBytes;
+	/** Whether buffered bootstrap constructions still have to be replayed. */
+	fBootstrapPending;
+	/** Path prefixes that produce no telemetry. */
+	fExclude;
+	/** Extra header names to withhold, or null when headers are not captured. */
+	fRedactHeaders;
+	/** Lazily created duration histogram. */
+	fDuration;
+	/**
+	* @param telemetry - The telemetry facade
+	* @param options - Resolved telemetry options
+	*/
+	constructor(telemetry, options) {
+		this.fTelemetry = telemetry;
+		this.fPropagation = options.propagation !== false;
+		this.fMetrics = options.metrics !== false;
+		this.fBodyBytes = resolveBodyBytes(options.spans?.bodies);
+		this.fBootstrapPending = options.spans?.di !== false;
+		this.fExclude = options.exclude ?? [];
+		this.fRedactHeaders = resolveHeaderRedaction(options.spans?.headers);
+	}
+	/** @inheritdoc */
+	server(spanContext, fn) {
+		if (this.fExclude.length > 0 && this.isExcluded(getRequestPathname(spanContext.request))) return fn();
+		if (this.fBootstrapPending) {
+			this.fBootstrapPending = false;
+			bootstrapRecorder.emit(this.fTelemetry.tracer);
+		}
+		const parent = this.fPropagation ? this.fTelemetry.extract(spanContext.request.headers) : context.active();
+		const attributes = toAttributes(spanContext);
+		const startedAt = this.fMetrics ? performance.now() : 0;
+		const requestBody = this.fBodyBytes > 0 ? captureRequestBody(spanContext.request, this.fBodyBytes) : void 0;
+		const redact = this.fRedactHeaders;
+		return runInSpan(this.fTelemetry.tracer, spanContext.name, {
+			kind: SpanKind.SERVER,
+			attributes
+		}, parent, (span) => {
+			if (redact) addHeadersEvent(span, REQUEST_HEADERS_EVENT, spanContext.request.headers, redact);
+			return fn();
+		}, this.fMetrics || this.fBodyBytes > 0 || redact !== null ? (span, value, error) => {
+			if (this.fMetrics) this.recordDuration(attributes, startedAt, value, error);
+			if (redact && value instanceof Response) addHeadersEvent(span, RESPONSE_HEADERS_EVENT, value.headers, redact);
+			return this.fBodyBytes > 0 ? this.attachBodies(span, requestBody, value) : void 0;
+		} : void 0);
+	}
+	/**
+	* Attaches the captured request and response bodies to the span.
+	*
+	* The response clone is taken here rather than later: once the runtime starts
+	* writing the response there is nothing left to tee.
+	*
+	* @param span - The server span
+	* @param requestBody - The pending request body capture, if any
+	* @param value - The value the request produced
+	* @returns A promise that settles once both bodies have been read
+	*/
+	attachBodies(span, requestBody, value) {
+		const responseBody = value instanceof Response ? captureResponseBody(value, this.fBodyBytes) : void 0;
+		if (!requestBody && !responseBody) return;
+		return Promise.all([requestBody, responseBody]).then(([request, response]) => {
+			if (request) addBodyEvent(span, REQUEST_BODY_EVENT, request);
+			if (response) addBodyEvent(span, RESPONSE_BODY_EVENT, response);
+		});
+	}
+	/** @inheritdoc */
+	recordError(error) {
+		const span = trace.getActiveSpan();
+		if (span) failSpan(span, error);
+	}
+	/**
+	* Whether a path is excluded from telemetry.
+	*
+	* @param path - Request pathname
+	* @returns True when nothing should be recorded
+	*/
+	isExcluded(path) {
+		return this.fExclude.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+	}
+	/** @inheritdoc */
+	flush() {
+		return this.fTelemetry.flush();
+	}
+	/** @inheritdoc */
+	traceId() {
+		return trace.getActiveSpan()?.spanContext().traceId;
+	}
+	/**
+	* Records one observation of `http.server.request.duration`.
+	*
+	* @param attributes - The span attributes to derive metric attributes from
+	* @param startedAt - `performance.now()` taken when the request started
+	* @param value - The value the request produced, normally a `Response`
+	* @param error - The thrown value, when the request failed
+	*/
+	recordDuration(attributes, startedAt, value, error) {
+		this.fDuration ??= this.fTelemetry.meter.createHistogram("http.server.request.duration", {
+			description: "Duration of HTTP server requests.",
+			unit: "s",
+			advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+		});
+		const metricAttributes = {
+			[HTTP_REQUEST_METHOD]: attributes[HTTP_REQUEST_METHOD],
+			[URL_SCHEME]: attributes[URL_SCHEME]
+		};
+		if (attributes["http.route"] !== void 0) metricAttributes[HTTP_ROUTE] = attributes[HTTP_ROUTE];
+		if (value instanceof Response) metricAttributes[HTTP_RESPONSE_STATUS_CODE] = value.status;
+		else if (error !== void 0) metricAttributes[ERROR_TYPE] = errorType(error);
+		this.fDuration.record((performance.now() - startedAt) / MS_PER_SECOND$1, metricAttributes);
+	}
+};
+/**
+* Builds the span attributes for a request.
+*
+* @param spanContext - Request and route metadata
+* @returns The span attributes
+*/
+function toAttributes(spanContext) {
+	const { request } = spanContext;
+	const attributes = {
+		[HTTP_REQUEST_METHOD]: request.method,
+		[URL_PATH]: getRequestPathname(request),
+		[URL_SCHEME]: request.url.startsWith("https") ? "https" : "http"
+	};
+	const query = getRequestSearch(request);
+	if (query.length > 1) attributes[URL_QUERY] = redactQuery(query.slice(1));
+	const host = request.headers.get("host");
+	if (host) {
+		const separator = host.lastIndexOf(":");
+		if (separator === -1) attributes[SERVER_ADDRESS] = host;
+		else {
+			attributes[SERVER_ADDRESS] = host.slice(0, separator);
+			attributes[SERVER_PORT] = Number(host.slice(separator + 1)) || void 0;
+		}
+	}
+	const userAgent = request.headers.get("user-agent");
+	if (userAgent) attributes[USER_AGENT_ORIGINAL] = userAgent;
+	if (spanContext.route !== void 0) attributes[HTTP_ROUTE] = spanContext.route;
+	if (spanContext.controller !== void 0) attributes[VERCUBE_CONTROLLER] = spanContext.controller;
+	if (spanContext.handler !== void 0) attributes[VERCUBE_HANDLER] = spanContext.handler;
+	return attributes;
+}
+/**
+* Rewrites a query string with credential-bearing values withheld.
+*
+* A secret in `?access_token=` is as sensitive as one in an `Authorization`
+* header, and it ends up in traces, downloadable snapshots and any exporter
+* that shares the pipeline. The same name matching used for configuration
+* values decides what to withhold.
+*
+* @param query - The raw query string, without the leading `?`
+* @returns The query string with secret values replaced
+*/
+function redactQuery(query) {
+	const params = new URLSearchParams(query);
+	let redacted = false;
+	for (const key of new Set(params.keys())) if (isSecretKey(key)) {
+		params.set(key, "<redacted>");
+		redacted = true;
+	}
+	return redacted ? params.toString() : query;
+}
+/**
+* Resolves the body capture cap from the option.
+*
+* @param bodies - The `spans.bodies` option
+* @returns The cap in bytes, or 0 when capture is off
+*/
+function resolveBodyBytes(bodies) {
+	if (!bodies) return 0;
+	return bodies === true ? DEFAULT_MAX_BODY_BYTES : bodies.maxBytes ?? 65536;
+}
+/**
+* Resolves the header capture setting.
+*
+* @param headers - The `spans.headers` option
+* @returns Extra names to withhold, or null when headers are not captured
+*/
+function resolveHeaderRedaction(headers) {
+	if (!headers) return null;
+	return new Set((headers === true ? [] : headers.redact ?? []).map((name) => name.toLowerCase()));
+}
+//#endregion
+//#region src/Hooks/TraceCorrelation.ts
+/** Plugin name, used by evlog for de-duplication. */
+const TRACE_CORRELATION_PLUGIN = "vercube:trace-correlation";
+/** Plugin name of the OTLP log drain. */
+const OTLP_LOGS_PLUGIN = "vercube:otlp-logs";
+/**
+* Ids of the span active right now, shaped the way `evlog/otlp` expects.
+*
+* @returns The trace and span ids, or undefined outside a span
+*/
+function activeIds() {
+	const spanContext = trace.getActiveSpan()?.spanContext();
+	return spanContext ? {
+		traceId: spanContext.traceId,
+		spanId: spanContext.spanId
+	} : void 0;
+}
+/**
+* The evlog plugin half of the correlation, covering request wide events.
+*
+* evlog also ships `createTraceContextEnricher()`, which reads the inbound
+* `traceparent` header. That is not enough: a request without one still has an
+* in-process trace, and an event emitted inside a nested span belongs to that
+* span rather than the request's. This reads whatever span is actually active.
+*
+* @returns The evlog plugin
+*/
+function createTraceCorrelationPlugin() {
+	return enricherPlugin(TRACE_CORRELATION_PLUGIN, ({ event }) => {
+		Object.assign(event, activeIds());
+	});
+}
+/**
+* Makes every log line carry the ids of the span it was written under.
+*
+* Two mechanisms are needed because evlog runs `enrich` only for request wide
+* events - a plain `logger.info()` never passes through it - while a context
+* provider covers exactly the calls that `enrich` misses. Registering both is
+* what makes correlation hold for every log line rather than most of them.
+*
+* @param logger - The application logger
+* @returns A function that removes the correlation again
+*/
+function installTraceCorrelation(logger) {
+	logger.addPlugin(createTraceCorrelationPlugin());
+	return logger.addContextProvider(activeIds);
+}
+/**
+* Ships every log event to an OTLP collector, correlated with its trace.
+*
+* evlog's OTLP adapter already emits `traceId` / `spanId` on the log record,
+* and {@link installTraceCorrelation} is what fills them in, so logs and spans
+* land in the same backend already joined.
+*
+* Batching, retry and backoff come from evlog's drain pipeline rather than a
+* hand-rolled queue.
+*
+* @param logger - The application logger
+* @param options - Endpoint and batching settings
+* @returns Flushes anything still buffered; call it on shutdown
+*/
+async function installOtlpLogs(logger, options = {}) {
+	const { createDrainPipeline, createOTLPDrain } = await import("@vercube/logger/otlp");
+	const drain = createDrainPipeline({ batch: {
+		size: 50,
+		intervalMs: 5e3
+	} })(createOTLPDrain(options.endpoint ? {
+		endpoint: options.endpoint,
+		headers: options.headers
+	} : {}));
+	logger.addDrain(OTLP_LOGS_PLUGIN, drain);
+	return () => drain.flush();
+}
+//#endregion
+//#region src/Metrics/ProcessMetrics.ts
+/**
+* Resolution of the event loop delay histogram, in milliseconds.
+*
+* Also the floor subtracted from every reading: `monitorEventLoopDelay`
+* schedules a timer every `resolution` ms and records how late it fired, so an
+* idle loop reports roughly one resolution rather than zero. Without the
+* subtraction a healthy server permanently claims ~10 ms of lag and any alert
+* on it cries wolf.
+*/
+const LOOP_RESOLUTION_MS = 10;
+/** Nanoseconds per millisecond. */
+const NS_PER_MS = 1e6;
+/** Milliseconds per second. */
+const MS_PER_SECOND = 1e3;
+/** Microseconds per millisecond, for the CPU counter. */
+const US_PER_MS = 1e3;
+/**
+* Registers observable instruments describing the Node.js process.
+*
+* Everything here is an *observable* instrument, so nothing is measured until a
+* metric reader collects: with no reader registered the callbacks never run and
+* the event loop monitor is the only cost. That is the same "only sample while
+* someone is watching" property the devtools sampler had, without a bespoke
+* timer.
+*
+* @param telemetry - The telemetry facade whose meter the instruments belong to
+* @returns A function that unregisters the callback and stops the loop monitor
+*/
+function installProcessMetrics(telemetry) {
+	const meter = telemetry.meter;
+	const cpu = meter.createObservableGauge("process.cpu.utilization", {
+		description: "Process CPU usage since the previous collection, as a fraction of one core.",
+		unit: "1",
+		valueType: ValueType.DOUBLE
+	});
+	const memory = meter.createObservableGauge("process.memory.usage", {
+		description: "Resident set size of the process.",
+		unit: "By",
+		valueType: ValueType.INT
+	});
+	const heapUsed = meter.createObservableGauge("v8js.memory.heap.used", {
+		description: "Heap memory currently in use.",
+		unit: "By",
+		valueType: ValueType.INT
+	});
+	const heapLimit = meter.createObservableGauge("v8js.memory.heap.limit", {
+		description: "Maximum heap size V8 will grow to.",
+		unit: "By",
+		valueType: ValueType.INT
+	});
+	const loopDelay = meter.createObservableGauge("nodejs.eventloop.delay.mean", {
+		description: "Mean event loop delay since the previous collection, with the sampling floor removed.",
+		unit: "s",
+		valueType: ValueType.DOUBLE
+	});
+	const loopDelayP99 = meter.createObservableGauge("nodejs.eventloop.delay.p99", {
+		description: "99th percentile event loop delay since the previous collection.",
+		unit: "s",
+		valueType: ValueType.DOUBLE
+	});
+	const loopUtilization = meter.createObservableGauge("nodejs.eventloop.utilization", {
+		description: "Fraction of time the event loop was busy since the previous collection.",
+		unit: "1",
+		valueType: ValueType.DOUBLE
+	});
+	const handles = meter.createObservableGauge("nodejs.process.handles", {
+		description: "Handles and requests keeping the process alive.",
+		unit: "{handle}",
+		valueType: ValueType.INT
+	});
+	const sampler = new ProcessSampler();
+	const instruments = [
+		cpu,
+		memory,
+		heapUsed,
+		heapLimit,
+		loopDelay,
+		loopDelayP99,
+		loopUtilization,
+		handles
+	];
+	const observe = (result) => {
+		const reading = sampler.read();
+		if (reading.cpu !== null) result.observe(cpu, reading.cpu);
+		result.observe(memory, reading.rss);
+		result.observe(heapUsed, reading.heapUsed);
+		if (reading.heapLimit !== null) result.observe(heapLimit, reading.heapLimit);
+		if (reading.loopDelayMeanSeconds !== null) {
+			result.observe(loopDelay, reading.loopDelayMeanSeconds);
+			result.observe(loopDelayP99, reading.loopDelayP99Seconds);
+		}
+		if (reading.loopUtilization !== null) result.observe(loopUtilization, reading.loopUtilization);
+		if (reading.handles !== null) result.observe(handles, reading.handles);
+	};
+	meter.addBatchObservableCallback(observe, instruments);
+	return () => {
+		meter.removeBatchObservableCallback(observe, instruments);
+		sampler.stop();
+	};
+}
+/**
+* Reads process counters, turning the cumulative ones into per-collection rates.
+*/
+var ProcessSampler = class {
+	/** CPU counter at the previous collection. */
+	fLastCpu = null;
+	/** Wall clock at the previous collection. */
+	fLastAt = Date.now();
+	/** Event loop utilisation at the previous collection. */
+	fLastElu = null;
+	/** Event loop delay histogram, reset after every reading. */
+	fLoop = null;
+	constructor() {
+		this.fLastCpu = safely(() => process.cpuUsage());
+		this.fLastElu = safely(() => performance$1.eventLoopUtilization());
+		this.fLoop = safely(() => {
+			const histogram = monitorEventLoopDelay({ resolution: LOOP_RESOLUTION_MS });
+			histogram.enable();
+			return histogram;
+		});
+	}
+	/**
+	* Takes one reading.
+	*
+	* @returns The current state of the process
+	*/
+	read() {
+		const usage = process.memoryUsage();
+		return {
+			cpu: this.readCpu(),
+			rss: usage.rss,
+			heapUsed: usage.heapUsed,
+			heapLimit: safely(() => getHeapStatistics().heap_size_limit),
+			...this.readLoop(),
+			handles: safely(() => countHandles())
+		};
+	}
+	/**
+	* Releases the event loop monitor.
+	*/
+	stop() {
+		this.fLoop?.disable();
+		this.fLoop = null;
+	}
+	/**
+	* CPU time consumed since the previous reading, as a fraction of one core.
+	*
+	* @returns The utilisation, or null when the counter is unavailable
+	*/
+	readCpu() {
+		const at = Date.now();
+		const current = safely(() => process.cpuUsage());
+		const previous = this.fLastCpu;
+		const elapsedMs = at - this.fLastAt;
+		this.fLastCpu = current;
+		this.fLastAt = at;
+		if (!current || !previous || elapsedMs <= 0) return null;
+		const window = elapsedMs * US_PER_MS;
+		return Math.max(0, (current.user - previous.user + (current.system - previous.system)) / window);
+	}
+	/**
+	* Event loop delay and utilisation since the previous reading.
+	*
+	* @returns The loop portion of a reading
+	*/
+	readLoop() {
+		const histogram = this.fLoop;
+		const previous = this.fLastElu;
+		const current = safely(() => performance$1.eventLoopUtilization());
+		this.fLastElu = current;
+		if (!histogram) return {
+			loopDelayMeanSeconds: null,
+			loopDelayP99Seconds: null,
+			loopUtilization: null
+		};
+		const meanMs = aboveFloor(histogram.mean / NS_PER_MS);
+		const p99Ms = aboveFloor(histogram.percentile(99) / NS_PER_MS);
+		histogram.reset();
+		return {
+			loopDelayMeanSeconds: meanMs / MS_PER_SECOND,
+			loopDelayP99Seconds: p99Ms / MS_PER_SECOND,
+			loopUtilization: current && previous ? safely(() => performance$1.eventLoopUtilization(current, previous).utilization) ?? null : null
+		};
+	}
+};
+/**
+* Removes the sampling floor from an event loop delay reading.
+*
+* @param value - Raw reading in milliseconds
+* @returns The delay above the floor, never negative
+*/
+function aboveFloor(value) {
+	return Number.isFinite(value) ? Math.max(0, value - LOOP_RESOLUTION_MS) : 0;
+}
+/**
+* Counts the handles and requests keeping the process alive.
+*
+* @returns The count
+*/
+function countHandles() {
+	const scope = process;
+	return (scope._getActiveHandles?.().length ?? 0) + (scope._getActiveRequests?.().length ?? 0);
+}
+/**
+* Runs a counter read, turning an unsupported runtime into `null`.
+*
+* Bun and Deno do not implement every Node counter, and a missing gauge is
+* better than a crashed collection.
+*
+* @param fn - The read to attempt
+* @returns The value, or null when it threw
+*/
+function safely(fn) {
+	try {
+		return fn();
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/Service/OtelTelemetry.ts
+/**
+* {@link Telemetry} implemented on the OpenTelemetry API.
+*
+* Everything here goes through `@opentelemetry/api`, never an SDK. With no
+* `TracerProvider` registered the API returns non-recording spans, so an
+* application that installs the plugin but no exporter pays almost nothing and
+* still propagates trace context correctly.
+*/
+var OtelTelemetry = class extends Telemetry {
+	/** Scope name reported for spans created through this instance. */
+	fScope;
+	/** Propagator used by {@link OtelTelemetry.inject} and {@link OtelTelemetry.extract}. */
+	fPropagator;
+	/** Callbacks run by {@link OtelTelemetry.flush}. */
+	fFlushers = [];
+	/**
+	* @param scope - Instrumentation scope name
+	* @param propagator - Trace context propagator
+	*/
+	constructor(scope = INSTRUMENTATION_SCOPE, propagator = new W3CTraceContextPropagator()) {
+		super();
+		this.fScope = scope;
+		this.fPropagator = propagator;
+	}
+	/** @inheritdoc */
+	get tracer() {
+		return trace.getTracer(this.fScope);
+	}
+	/** @inheritdoc */
+	get meter() {
+		return metrics.getMeter(this.fScope);
+	}
+	/** @inheritdoc */
+	span(name, fn, options = {}) {
+		return runInSpan(this.tracer, name, options, context.active(), fn);
+	}
+	/** @inheritdoc */
+	activeSpan() {
+		return trace.getActiveSpan();
+	}
+	/** @inheritdoc */
+	get traceId() {
+		return this.activeSpan()?.spanContext().traceId;
+	}
+	/** @inheritdoc */
+	get spanId() {
+		return this.activeSpan()?.spanContext().spanId;
+	}
+	/** @inheritdoc */
+	inject(carrier) {
+		this.fPropagator.inject(context.active(), carrier, headersSetter);
+	}
+	/** @inheritdoc */
+	extract(headers) {
+		return this.fPropagator.extract(ROOT_CONTEXT, headers, headersGetter);
+	}
+	/** @inheritdoc */
+	onFlush(flush) {
+		this.fFlushers.push(flush);
+	}
+	/** @inheritdoc */
+	async flush() {
+		await Promise.allSettled(this.fFlushers.map((flush) => flush()));
+	}
+};
+//#endregion
+//#region src/Plugins/TelemetryPlugin.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.
+*/
+var TelemetryPlugin = class extends BasePlugin {
+	/** @inheritdoc */
+	name = "TelemetryPlugin";
+	/**
+	* 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, options) {
+		const resolved = resolveTelemetryOptions({
+			...config,
+			telemetry: {
+				...normalize(config.telemetry),
+				...options
+			}
+		});
+		if (resolved.enabled && resolved.spans?.di !== false) bootstrapRecorder.install();
+	}
+	/**
+	* Installs telemetry into the running application.
+	*
+	* @param app - The application
+	* @param options - Options overriding the `telemetry` config field
+	*/
+	use(app, options) {
+		const resolved = resolveTelemetryOptions({
+			...app.config,
+			telemetry: {
+				...normalize(app.config.telemetry),
+				...options
+			}
+		});
+		if (!resolved.enabled) return;
+		const container = app.container;
+		const logger = container.getOptional(Logger);
+		const registry = container.get(TelemetryRegistry);
+		if (registry.enabled) {
+			logger?.debug("TelemetryPlugin", "Telemetry is already installed, skipping");
+			return;
+		}
+		let requestContext = container.getOptional(RequestContext);
+		if (!requestContext) {
+			container.bind(RequestContext);
+			requestContext = container.get(RequestContext);
+		}
+		context.setGlobalContextManager(new VercubeContextManager(requestContext).enable());
+		propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+		const telemetry = new OtelTelemetry(INSTRUMENTATION_SCOPE);
+		container.bindInstance(Telemetry, telemetry);
+		registry.install(new CoreTelemetryHooks(telemetry, resolved), resolved);
+		if (resolved.spans?.di !== false) bootstrapRecorder.install();
+		if (resolved.metrics !== false) installProcessMetrics(telemetry);
+		telemetry.onFlush(async () => {
+			await trace.getTracerProvider().forceFlush?.();
+		});
+		if (logger) installTraceCorrelation(logger);
+		logger?.debug("TelemetryPlugin", "OpenTelemetry instrumentation installed");
+		if (logger && resolved.logs) return installOtlpLogs(logger, { endpoint: resolved.endpoint }).then((flush) => {
+			telemetry.onFlush(flush);
+		});
+	}
+};
+/**
+* Turns the shorthand `telemetry: boolean` form into an options object.
+*
+* @param value - The raw config value
+* @returns The equivalent options object
+*/
+function normalize(value) {
+	if (value === void 0) return {};
+	return typeof value === "boolean" ? { enabled: value } : value;
+}
+//#endregion
+export { Telemetry, TelemetryPlugin };