@davidilie/telemetry-node 0.2.0 → 0.4.0

package/README.md

@@ -47,12 +47,24 @@ process.once("SIGTERM", async () => {
 ```
 
 `registerNodeTelemetry` installs one `NodeSDK` per JavaScript global. Repeated
-calls return the first client and ignore later configuration until that client
-successfully shuts down. Do not register this package beside another provider.
+calls return the first client and ignore later configuration. Registration is
+terminal after shutdown: restart the process to register again. OTel retains
+global provider references after shutdown, so another registration would
+otherwise silently use a stopped provider. Do not register this package beside another provider.
 
 The optional `sdk` property accepts `NodeSDKConfiguration` fields other than
 `resource` and `serviceName`. Use it for maintained instrumentations, readers,
 processors, or exporters when environment-based defaults are insufficient.
+Resource detectors default to an empty list, excluding automatic host/process
+metadata and `OTEL_RESOURCE_ATTRIBUTES` / `OTEL_SERVICE_NAME` overrides. Set
+`sdk.resourceDetectors` only for reviewed detectors: their output bypasses core
+redaction and may override the configured resource identity.
+
+Wrap a custom trace exporter in the exported `RedactingSpanExporter` to apply
+core privacy bounds to completed automatic spans as well. It redacts copies
+of span names, attributes, events, links, and status messages, leaving the
+original spans and trace context intact. Resource and instrumentation-scope
+metadata remain trusted configuration; configure those separately.
 
 ## Export configuration
 
@@ -60,7 +72,6 @@ The standalone SDK follows standard OpenTelemetry environment variables. For
 Alloy's private OTLP/HTTP receiver:
 
 ```sh
-OTEL_SERVICE_NAME=email-worker
 OTEL_EXPORTER_OTLP_ENDPOINT=http://alloy.observability.svc.cluster.local:4318
 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
 ```
@@ -165,10 +176,17 @@ collected into the same backend. Disable one route deliberately.
 
 ## Spans and context
 
-The `NodeTelemetryClient` overrides the generic core `withSpan` so the new span
-is active during the operation. Use it when events/logs need the same trace.
+The Node adapter supplies active-span execution to the shared core `withSpan`.
+The span is active during the operation, including asynchronous work, while
+core applies context, consent, sampling, and shutdown checks. Use it when events/logs need the same trace.
 `client.startSpan()` creates a span but does not make it active.
 
+The callback receives a safe span handle, including `traceContext()`.
+`client.traceWebhook({ destination: "discord.sales" }, send)` tracks one
+outgoing POST under the active parent. See the
+[webhook guide](https://github.com/DavidIlie/davidapps-telemetry/blob/main/docs/webhooks.md)
+for privacy, delivery outcomes, metrics, and Grafana Discord notifications.
+
 Both methods accept `{ kind: "internal" | "server" | "client" | "producer" |
 "consumer" }` after attributes. Manual span handles also expose
 `setStatus("unset" | "ok" | "error", message?)`.
@@ -211,9 +229,11 @@ context; `startSpan` does not.
   apply; set one layer to `1` if multiplied rates are not intentional.
 - State changes affect new work and do not erase an already exported or queued
   provider batch.
-- `flush()` drains core work, but the Node adapter does not own a provider
-  force-flush method. `shutdown()` on the `/register` client shuts down the
-  `NodeSDK` and its processors.
+- `flush()` drains core work, then calls the registered trace, log, and metric
+  providers' public `forceFlush()` methods when available. This flushes all
+  pending work on those providers, not only this client's records. Failures
+  are reported through `onError` without rejecting the client promise.
+  `shutdown()` on the `/register` client shuts down the `NodeSDK` and its processors.
 - Only a client returned by `/register` owns and shuts down the installed
   `NodeSDK`. A client created from the root entrypoint does not own the
   framework provider.

package/dist/{client-BzoFCwmQ.d.cts → client-DYrSJX10.d.cts}

@@ -9,6 +9,7 @@ declare class OpenTelemetrySpan implements TelemetrySpan {
   recordException(error: unknown, attributes?: Attributes$1): void;
   setStatus(status: TelemetrySpanStatus, message?: string): this;
   end(): void;
+  traceContext(): TraceContext | undefined;
 }
 interface OpenTelemetryAdapterConfig {
   resource: TelemetryResource;
@@ -31,7 +32,8 @@ declare class OpenTelemetryAdapter implements TelemetryAdapter {
   send(signal: TelemetrySignal): void;
   startSpan(name: string, attributes?: Attributes$1, options?: TelemetrySpanOptions): TelemetrySpan;
   currentTraceContext(): TraceContext | undefined;
-  withActiveSpan<T>(name: string, operation: () => T | Promise<T>, attributes?: Attributes$1, options?: TelemetrySpanOptions): Promise<T>;
+  withActiveSpan<T>(name: string, operation: (span: TelemetrySpan) => T | Promise<T>, attributes?: Attributes$1, options?: TelemetrySpanOptions): Promise<T>;
+  flush(): Promise<void>;
   shutdown(): Promise<void>;
 }
 declare function createOpenTelemetryAdapter(config: OpenTelemetryAdapterConfig): OpenTelemetryAdapter;
@@ -78,7 +80,6 @@ declare class NodeTelemetryClient extends TelemetryClient {
   constructor(config: NodeTelemetryInternalConfig);
   setEnabled(enabled: boolean): void;
   setConsent(consent: "granted" | "denied" | "pending"): void;
-  withSpan<T>(name: string, operation: () => T | Promise<T>, attributes?: Attributes$1, options?: TelemetrySpanOptions): Promise<T>;
 }
 declare function createNodeTelemetry(config: NodeTelemetryConfig): NodeTelemetryClient;
 //#endregion

package/dist/{client-BzoFCwmQ.d.mts → client-DYrSJX10.d.mts}

@@ -9,6 +9,7 @@ declare class OpenTelemetrySpan implements TelemetrySpan {
   recordException(error: unknown, attributes?: Attributes$1): void;
   setStatus(status: TelemetrySpanStatus, message?: string): this;
   end(): void;
+  traceContext(): TraceContext | undefined;
 }
 interface OpenTelemetryAdapterConfig {
   resource: TelemetryResource;
@@ -31,7 +32,8 @@ declare class OpenTelemetryAdapter implements TelemetryAdapter {
   send(signal: TelemetrySignal): void;
   startSpan(name: string, attributes?: Attributes$1, options?: TelemetrySpanOptions): TelemetrySpan;
   currentTraceContext(): TraceContext | undefined;
-  withActiveSpan<T>(name: string, operation: () => T | Promise<T>, attributes?: Attributes$1, options?: TelemetrySpanOptions): Promise<T>;
+  withActiveSpan<T>(name: string, operation: (span: TelemetrySpan) => T | Promise<T>, attributes?: Attributes$1, options?: TelemetrySpanOptions): Promise<T>;
+  flush(): Promise<void>;
   shutdown(): Promise<void>;
 }
 declare function createOpenTelemetryAdapter(config: OpenTelemetryAdapterConfig): OpenTelemetryAdapter;
@@ -78,7 +80,6 @@ declare class NodeTelemetryClient extends TelemetryClient {
   constructor(config: NodeTelemetryInternalConfig);
   setEnabled(enabled: boolean): void;
   setConsent(consent: "granted" | "denied" | "pending"): void;
-  withSpan<T>(name: string, operation: () => T | Promise<T>, attributes?: Attributes$1, options?: TelemetrySpanOptions): Promise<T>;
 }
 declare function createNodeTelemetry(config: NodeTelemetryConfig): NodeTelemetryClient;
 //#endregion

package/dist/index.cjs

@@ -1,9 +1,74 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sampler = require("./sampler-CGBWEZod.cjs");
+const require_sampler = require("./sampler-vVC2xXgy.cjs");
+let _davidilie_telemetry_core = require("@davidilie/telemetry-core");
+//#region src/exporter.ts
+function redactSpan(span) {
+	const name = span.name.replace(/https?:\/\/[^\s<>"']+/gi, (value) => {
+		try {
+			return new URL(value).origin;
+		} catch {
+			return "[REDACTED_URL]";
+		}
+	});
+	return {
+		name: (0, _davidilie_telemetry_core.redactText)(name, 256),
+		kind: span.kind,
+		spanContext: () => span.spanContext(),
+		...span.parentSpanContext ? { parentSpanContext: span.parentSpanContext } : {},
+		startTime: span.startTime,
+		endTime: span.endTime,
+		duration: span.duration,
+		ended: span.ended,
+		resource: span.resource,
+		instrumentationScope: span.instrumentationScope,
+		droppedAttributesCount: span.droppedAttributesCount,
+		droppedEventsCount: span.droppedEventsCount,
+		droppedLinksCount: span.droppedLinksCount,
+		attributes: require_sampler.toOtelAttributes((0, _davidilie_telemetry_core.sanitizeAttributes)(span.attributes)),
+		status: {
+			code: span.status.code,
+			...span.status.message ? { message: (0, _davidilie_telemetry_core.redactText)(span.status.message) } : {}
+		},
+		events: span.events.map((event) => ({
+			...event,
+			name: (0, _davidilie_telemetry_core.redactText)(event.name, 256),
+			attributes: require_sampler.toOtelAttributes((0, _davidilie_telemetry_core.sanitizeAttributes)(event.attributes))
+		})),
+		links: span.links.map((link) => ({
+			...link,
+			attributes: require_sampler.toOtelAttributes((0, _davidilie_telemetry_core.sanitizeAttributes)(link.attributes))
+		}))
+	};
+}
+/** Apply core privacy bounds to completed spans without mutating another processor's data. */
+var RedactingSpanExporter = class {
+	delegate;
+	constructor(delegate) {
+		this.delegate = delegate;
+	}
+	export(spans, done) {
+		let sanitized;
+		try {
+			sanitized = spans.map(redactSpan);
+		} catch {
+			done({ code: 1 });
+			return;
+		}
+		this.delegate.export(sanitized, done);
+	}
+	shutdown() {
+		return this.delegate.shutdown();
+	}
+	forceFlush() {
+		return this.delegate.forceFlush?.() ?? Promise.resolve();
+	}
+};
+//#endregion
 exports.DynamicTelemetrySampler = require_sampler.DynamicTelemetrySampler;
 exports.NodeTelemetryClient = require_sampler.NodeTelemetryClient;
 exports.OpenTelemetryAdapter = require_sampler.OpenTelemetryAdapter;
 exports.OpenTelemetrySpan = require_sampler.OpenTelemetrySpan;
+exports.RedactingSpanExporter = RedactingSpanExporter;
 exports.createNodeTelemetry = require_sampler.createNodeTelemetry;
 exports.createOpenTelemetryAdapter = require_sampler.createOpenTelemetryAdapter;
 exports.currentTraceContext = require_sampler.currentTraceContext;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { a as OpenTelemetryAdapter, c as createOpenTelemetryAdapter, d as startSpan, f as withSpan, i as MeasurementMode, l as currentTraceContext, n as NodeTelemetryConfig, o as OpenTelemetryAdapterConfig, r as createNodeTelemetry, s as OpenTelemetrySpan, t as NodeTelemetryClient, u as recordException } from "./client-BzoFCwmQ.cjs";
+import { a as OpenTelemetryAdapter, c as createOpenTelemetryAdapter, d as startSpan, f as withSpan, i as MeasurementMode, l as currentTraceContext, n as NodeTelemetryConfig, o as OpenTelemetryAdapterConfig, r as createNodeTelemetry, s as OpenTelemetrySpan, t as NodeTelemetryClient, u as recordException } from "./client-DYrSJX10.cjs";
 import { AttributeValue, Attributes, Context, Link, SpanKind } from "@opentelemetry/api";
 import { AttributeValue as AttributeValue$1, Attributes as Attributes$1, TelemetryResource } from "@davidilie/telemetry-core";
-import { Sampler, SamplingResult } from "@opentelemetry/sdk-trace-base";
+import { ReadableSpan, Sampler, SamplingResult, SpanExporter } from "@opentelemetry/sdk-trace-base";
 //#region src/attributes.d.ts
 declare function toOtelAttributeValue(value: AttributeValue$1): AttributeValue;
 declare function toOtelAttributes(attributes?: Attributes$1): Attributes;
@@ -31,4 +31,14 @@ declare class DynamicTelemetrySampler implements Sampler {
   toString(): string;
 }
 //#endregion
-export { DynamicTelemetrySampler, type MeasurementMode, NodeTelemetryClient, type NodeTelemetryConfig, OpenTelemetryAdapter, type OpenTelemetryAdapterConfig, OpenTelemetrySpan, type TelemetrySamplingState, createNodeTelemetry, createOpenTelemetryAdapter, currentTraceContext, recordException, startSpan, telemetryResourceAttributes, toOtelAttributeValue, toOtelAttributes, withSpan };
+//#region src/exporter.d.ts
+/** Apply core privacy bounds to completed spans without mutating another processor's data. */
+declare class RedactingSpanExporter implements SpanExporter {
+  private readonly delegate;
+  constructor(delegate: SpanExporter);
+  export(spans: ReadableSpan[], done: Parameters<SpanExporter["export"]>[1]): void;
+  shutdown(): Promise<void>;
+  forceFlush(): Promise<void>;
+}
+//#endregion
+export { DynamicTelemetrySampler, type MeasurementMode, NodeTelemetryClient, type NodeTelemetryConfig, OpenTelemetryAdapter, type OpenTelemetryAdapterConfig, OpenTelemetrySpan, RedactingSpanExporter, type TelemetrySamplingState, createNodeTelemetry, createOpenTelemetryAdapter, currentTraceContext, recordException, startSpan, telemetryResourceAttributes, toOtelAttributeValue, toOtelAttributes, withSpan };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { a as OpenTelemetryAdapter, c as createOpenTelemetryAdapter, d as startSpan, f as withSpan, i as MeasurementMode, l as currentTraceContext, n as NodeTelemetryConfig, o as OpenTelemetryAdapterConfig, r as createNodeTelemetry, s as OpenTelemetrySpan, t as NodeTelemetryClient, u as recordException } from "./client-BzoFCwmQ.mjs";
+import { a as OpenTelemetryAdapter, c as createOpenTelemetryAdapter, d as startSpan, f as withSpan, i as MeasurementMode, l as currentTraceContext, n as NodeTelemetryConfig, o as OpenTelemetryAdapterConfig, r as createNodeTelemetry, s as OpenTelemetrySpan, t as NodeTelemetryClient, u as recordException } from "./client-DYrSJX10.mjs";
 import { AttributeValue, Attributes, Context, Link, SpanKind } from "@opentelemetry/api";
 import { AttributeValue as AttributeValue$1, Attributes as Attributes$1, TelemetryResource } from "@davidilie/telemetry-core";
-import { Sampler, SamplingResult } from "@opentelemetry/sdk-trace-base";
+import { ReadableSpan, Sampler, SamplingResult, SpanExporter } from "@opentelemetry/sdk-trace-base";
 //#region src/attributes.d.ts
 declare function toOtelAttributeValue(value: AttributeValue$1): AttributeValue;
 declare function toOtelAttributes(attributes?: Attributes$1): Attributes;
@@ -31,4 +31,14 @@ declare class DynamicTelemetrySampler implements Sampler {
   toString(): string;
 }
 //#endregion
-export { DynamicTelemetrySampler, type MeasurementMode, NodeTelemetryClient, type NodeTelemetryConfig, OpenTelemetryAdapter, type OpenTelemetryAdapterConfig, OpenTelemetrySpan, type TelemetrySamplingState, createNodeTelemetry, createOpenTelemetryAdapter, currentTraceContext, recordException, startSpan, telemetryResourceAttributes, toOtelAttributeValue, toOtelAttributes, withSpan };
+//#region src/exporter.d.ts
+/** Apply core privacy bounds to completed spans without mutating another processor's data. */
+declare class RedactingSpanExporter implements SpanExporter {
+  private readonly delegate;
+  constructor(delegate: SpanExporter);
+  export(spans: ReadableSpan[], done: Parameters<SpanExporter["export"]>[1]): void;
+  shutdown(): Promise<void>;
+  forceFlush(): Promise<void>;
+}
+//#endregion
+export { DynamicTelemetrySampler, type MeasurementMode, NodeTelemetryClient, type NodeTelemetryConfig, OpenTelemetryAdapter, type OpenTelemetryAdapterConfig, OpenTelemetrySpan, RedactingSpanExporter, type TelemetrySamplingState, createNodeTelemetry, createOpenTelemetryAdapter, currentTraceContext, recordException, startSpan, telemetryResourceAttributes, toOtelAttributeValue, toOtelAttributes, withSpan };

package/dist/index.mjs

@@ -1,2 +1,66 @@
-import { a as OpenTelemetrySpan, c as recordException, d as telemetryResourceAttributes, f as toOtelAttributeValue, i as OpenTelemetryAdapter, l as startSpan, n as NodeTelemetryClient, o as createOpenTelemetryAdapter, p as toOtelAttributes, r as createNodeTelemetry, s as currentTraceContext, t as DynamicTelemetrySampler, u as withSpan } from "./sampler-ND4YGh_7.mjs";
-export { DynamicTelemetrySampler, NodeTelemetryClient, OpenTelemetryAdapter, OpenTelemetrySpan, createNodeTelemetry, createOpenTelemetryAdapter, currentTraceContext, recordException, startSpan, telemetryResourceAttributes, toOtelAttributeValue, toOtelAttributes, withSpan };
+import { a as OpenTelemetrySpan, c as recordException, d as telemetryResourceAttributes, f as toOtelAttributeValue, i as OpenTelemetryAdapter, l as startSpan, n as NodeTelemetryClient, o as createOpenTelemetryAdapter, p as toOtelAttributes, r as createNodeTelemetry, s as currentTraceContext, t as DynamicTelemetrySampler, u as withSpan } from "./sampler-80dS1PU-.mjs";
+import { redactText, sanitizeAttributes } from "@davidilie/telemetry-core";
+//#region src/exporter.ts
+function redactSpan(span) {
+	const name = span.name.replace(/https?:\/\/[^\s<>"']+/gi, (value) => {
+		try {
+			return new URL(value).origin;
+		} catch {
+			return "[REDACTED_URL]";
+		}
+	});
+	return {
+		name: redactText(name, 256),
+		kind: span.kind,
+		spanContext: () => span.spanContext(),
+		...span.parentSpanContext ? { parentSpanContext: span.parentSpanContext } : {},
+		startTime: span.startTime,
+		endTime: span.endTime,
+		duration: span.duration,
+		ended: span.ended,
+		resource: span.resource,
+		instrumentationScope: span.instrumentationScope,
+		droppedAttributesCount: span.droppedAttributesCount,
+		droppedEventsCount: span.droppedEventsCount,
+		droppedLinksCount: span.droppedLinksCount,
+		attributes: toOtelAttributes(sanitizeAttributes(span.attributes)),
+		status: {
+			code: span.status.code,
+			...span.status.message ? { message: redactText(span.status.message) } : {}
+		},
+		events: span.events.map((event) => ({
+			...event,
+			name: redactText(event.name, 256),
+			attributes: toOtelAttributes(sanitizeAttributes(event.attributes))
+		})),
+		links: span.links.map((link) => ({
+			...link,
+			attributes: toOtelAttributes(sanitizeAttributes(link.attributes))
+		}))
+	};
+}
+/** Apply core privacy bounds to completed spans without mutating another processor's data. */
+var RedactingSpanExporter = class {
+	delegate;
+	constructor(delegate) {
+		this.delegate = delegate;
+	}
+	export(spans, done) {
+		let sanitized;
+		try {
+			sanitized = spans.map(redactSpan);
+		} catch {
+			done({ code: 1 });
+			return;
+		}
+		this.delegate.export(sanitized, done);
+	}
+	shutdown() {
+		return this.delegate.shutdown();
+	}
+	forceFlush() {
+		return this.delegate.forceFlush?.() ?? Promise.resolve();
+	}
+};
+//#endregion
+export { DynamicTelemetrySampler, NodeTelemetryClient, OpenTelemetryAdapter, OpenTelemetrySpan, RedactingSpanExporter, createNodeTelemetry, createOpenTelemetryAdapter, currentTraceContext, recordException, startSpan, telemetryResourceAttributes, toOtelAttributeValue, toOtelAttributes, withSpan };

package/dist/register.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sampler = require("./sampler-CGBWEZod.cjs");
+const require_sampler = require("./sampler-vVC2xXgy.cjs");
 let _davidilie_telemetry_core = require("@davidilie/telemetry-core");
 let _opentelemetry_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
 let _opentelemetry_resources = require("@opentelemetry/resources");
@@ -13,7 +13,10 @@ function traceSampleRate(config) {
 function registerNodeTelemetry(config) {
 	const sharedGlobal = globalThis;
 	const existing = sharedGlobal[REGISTRATION];
-	if (existing) return existing.client;
+	if (existing) {
+		if (existing.stopped) throw new Error("Node telemetry registration is terminal after shutdown; restart the process to register again");
+		return existing.client;
+	}
 	const resource = (0, _davidilie_telemetry_core.sanitizeResource)(config.resource);
 	const sampler = new require_sampler.DynamicTelemetrySampler(config.sdk?.sampler ?? new _opentelemetry_sdk_trace_base.ParentBasedSampler({ root: new _opentelemetry_sdk_trace_base.TraceIdRatioBasedSampler(traceSampleRate(config)) }), {
 		enabled: config.enabled ?? true,
@@ -21,6 +24,7 @@ function registerNodeTelemetry(config) {
 	});
 	const sdk = new _opentelemetry_sdk_node.NodeSDK({
 		...config.sdk,
+		resourceDetectors: config.sdk?.resourceDetectors ?? [],
 		sampler,
 		resource: (0, _opentelemetry_resources.resourceFromAttributes)(require_sampler.telemetryResourceAttributes(resource)),
 		serviceName: resource.serviceName
@@ -37,13 +41,15 @@ function registerNodeTelemetry(config) {
 		},
 		measurementMode: config.measurementMode ?? (config.sdk?.metricReaders?.length ? "metrics" : "spans"),
 		shutdown: async () => {
+			const registration = sharedGlobal[REGISTRATION];
+			if (registration?.client === client) registration.stopped = true;
 			await sdk.shutdown();
-			if (sharedGlobal[REGISTRATION]?.client === client) delete sharedGlobal[REGISTRATION];
 		}
 	});
 	sharedGlobal[REGISTRATION] = {
 		client,
-		sdk
+		sdk,
+		stopped: false
 	};
 	return client;
 }

package/dist/register.d.cts

@@ -1,4 +1,4 @@
-import { n as NodeTelemetryConfig, t as NodeTelemetryClient } from "./client-BzoFCwmQ.cjs";
+import { n as NodeTelemetryConfig, t as NodeTelemetryClient } from "./client-DYrSJX10.cjs";
 import { NodeSDKConfiguration, NodeSDKConfiguration as NodeSDKConfiguration$1 } from "@opentelemetry/sdk-node";
 //#region src/register.d.ts
 interface RegisterNodeTelemetryConfig extends NodeTelemetryConfig {

package/dist/register.d.mts

@@ -1,4 +1,4 @@
-import { n as NodeTelemetryConfig, t as NodeTelemetryClient } from "./client-BzoFCwmQ.mjs";
+import { n as NodeTelemetryConfig, t as NodeTelemetryClient } from "./client-DYrSJX10.mjs";
 import { NodeSDKConfiguration, NodeSDKConfiguration as NodeSDKConfiguration$1 } from "@opentelemetry/sdk-node";
 //#region src/register.d.ts
 interface RegisterNodeTelemetryConfig extends NodeTelemetryConfig {

package/dist/register.mjs

@@ -1,4 +1,4 @@
-import { d as telemetryResourceAttributes, n as NodeTelemetryClient, t as DynamicTelemetrySampler } from "./sampler-ND4YGh_7.mjs";
+import { d as telemetryResourceAttributes, n as NodeTelemetryClient, t as DynamicTelemetrySampler } from "./sampler-80dS1PU-.mjs";
 import { sanitizeResource } from "@davidilie/telemetry-core";
 import { ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
 import { resourceFromAttributes } from "@opentelemetry/resources";
@@ -12,7 +12,10 @@ function traceSampleRate(config) {
 function registerNodeTelemetry(config) {
 	const sharedGlobal = globalThis;
 	const existing = sharedGlobal[REGISTRATION];
-	if (existing) return existing.client;
+	if (existing) {
+		if (existing.stopped) throw new Error("Node telemetry registration is terminal after shutdown; restart the process to register again");
+		return existing.client;
+	}
 	const resource = sanitizeResource(config.resource);
 	const sampler = new DynamicTelemetrySampler(config.sdk?.sampler ?? new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(traceSampleRate(config)) }), {
 		enabled: config.enabled ?? true,
@@ -20,6 +23,7 @@ function registerNodeTelemetry(config) {
 	});
 	const sdk = new NodeSDK({
 		...config.sdk,
+		resourceDetectors: config.sdk?.resourceDetectors ?? [],
 		sampler,
 		resource: resourceFromAttributes(telemetryResourceAttributes(resource)),
 		serviceName: resource.serviceName
@@ -36,13 +40,15 @@ function registerNodeTelemetry(config) {
 		},
 		measurementMode: config.measurementMode ?? (config.sdk?.metricReaders?.length ? "metrics" : "spans"),
 		shutdown: async () => {
+			const registration = sharedGlobal[REGISTRATION];
+			if (registration?.client === client) registration.stopped = true;
 			await sdk.shutdown();
-			if (sharedGlobal[REGISTRATION]?.client === client) delete sharedGlobal[REGISTRATION];
 		}
 	});
 	sharedGlobal[REGISTRATION] = {
 		client,
-		sdk
+		sdk,
+		stopped: false
 	};
 	return client;
 }

package/dist/{sampler-ND4YGh_7.mjs → sampler-80dS1PU-.mjs}

@@ -1,4 +1,4 @@
-import { SpanKind, SpanStatusCode, context, metrics, trace } from "@opentelemetry/api";
+import { SpanKind, SpanStatusCode, context, isSpanContextValid, metrics, trace } from "@opentelemetry/api";
 import { SeverityNumber, logs } from "@opentelemetry/api-logs";
 import { TelemetryClient, redactText, sanitizeAttributes, sanitizeResource, sanitizeSignal } from "@davidilie/telemetry-core";
 import { SamplingDecision } from "@opentelemetry/sdk-trace-base";
@@ -38,6 +38,22 @@ function telemetryResourceAttributes(resource) {
 	};
 }
 //#endregion
+//#region src/flush.ts
+/** Flush registered SDK providers using their public lifecycle methods. */
+async function flushOpenTelemetryProviders() {
+	let tracerProvider = trace.getTracerProvider();
+	if ("getDelegate" in tracerProvider && typeof tracerProvider.getDelegate === "function") tracerProvider = tracerProvider.getDelegate();
+	const providers = [
+		tracerProvider,
+		logs.getLoggerProvider(),
+		metrics.getMeterProvider()
+	];
+	const errors = (await Promise.allSettled(providers.map(async (provider) => {
+		if ("forceFlush" in provider && typeof provider.forceFlush === "function") await provider.forceFlush();
+	}))).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+	if (errors.length > 0) throw new AggregateError(errors, "OpenTelemetry provider flush failed");
+}
+//#endregion
 //#region src/adapter.ts
 const severityNumbers = {
 	debug: SeverityNumber.DEBUG,
@@ -46,13 +62,17 @@ const severityNumbers = {
 	error: SeverityNumber.ERROR
 };
 function exceptionForOtel(error) {
-	if (error instanceof Error) {
-		const safe = new Error(redactText(error.message), { ...error.cause !== void 0 ? { cause: redactText(String(error.cause)) } : {} });
-		safe.name = redactText(error.name, 256);
-		if (error.stack) safe.stack = redactText(error.stack, 16384);
-		return safe;
+	try {
+		if (error instanceof Error) {
+			const safe = new Error(redactText(error.message), { ...error.cause !== void 0 ? { cause: redactText(String(error.cause)) } : {} });
+			safe.name = redactText(error.name, 256);
+			if (error.stack) safe.stack = redactText(error.stack, 16384);
+			return safe;
+		}
+		return redactText(typeof error === "string" ? error : String(error));
+	} catch {
+		return "Unserializable exception";
 	}
-	return redactText(typeof error === "string" ? error : String(error));
 }
 function signalAttributes(signal) {
 	return {
@@ -100,6 +120,14 @@ var OpenTelemetrySpan = class {
 	end() {
 		this.#span.end();
 	}
+	traceContext() {
+		const value = this.#span.spanContext();
+		return isSpanContextValid(value) ? {
+			traceId: value.traceId,
+			spanId: value.spanId,
+			traceFlags: value.traceFlags
+		} : void 0;
+	}
 };
 var OpenTelemetryAdapter = class {
 	#instrumentationName;
@@ -112,6 +140,7 @@ var OpenTelemetryAdapter = class {
 	#logSampleRate;
 	#shutdown;
 	#histograms = /* @__PURE__ */ new Map();
+	#meterProvider;
 	constructor(config) {
 		this.#resource = sanitizeResource(config.resource);
 		this.#instrumentationName = config.instrumentationName ?? this.#resource.serviceName;
@@ -129,7 +158,7 @@ var OpenTelemetryAdapter = class {
 		switch (signal.type) {
 			case "event": {
 				const activeSpan = trace.getActiveSpan();
-				if (activeSpan) {
+				if (activeSpan?.isRecording()) {
 					activeSpan.addEvent(signal.name, attributes, new Date(signal.timestamp));
 					return;
 				}
@@ -144,22 +173,23 @@ var OpenTelemetryAdapter = class {
 			}
 			case "exception": {
 				const activeSpan = trace.getActiveSpan();
-				const span = activeSpan ?? this.#tracer().startSpan("exception", {
+				const recordingSpan = activeSpan?.isRecording() ? activeSpan : void 0;
+				const span = recordingSpan ?? this.#tracer().startSpan("exception", {
 					kind: SpanKind.INTERNAL,
 					attributes,
 					startTime: new Date(signal.timestamp)
 				});
-				span.setAttributes(attributes);
-				span.recordException({
-					name: signal.exception.name,
-					message: signal.exception.message,
-					...signal.exception.stack ? { stack: signal.exception.stack } : {}
-				});
+				span.addEvent("exception", {
+					...attributes,
+					"exception.type": signal.exception.name,
+					"exception.message": signal.exception.message,
+					...signal.exception.stack ? { "exception.stacktrace": signal.exception.stack } : {}
+				}, new Date(signal.timestamp));
 				span.setStatus({
 					code: SpanStatusCode.ERROR,
 					message: signal.exception.message
 				});
-				if (!activeSpan) span.end(new Date(signal.timestamp));
+				if (!recordingSpan) span.end(new Date(signal.timestamp));
 				return;
 			}
 			case "log":
@@ -200,11 +230,16 @@ var OpenTelemetryAdapter = class {
 				}).end(new Date(signal.timestamp));
 				if (this.#measurementMode === "spans") return;
 				if (!VALID_INSTRUMENT_NAME.test(signal.name)) return;
+				const meterProvider = metrics.getMeterProvider();
+				if (meterProvider !== this.#meterProvider) {
+					this.#histograms.clear();
+					this.#meterProvider = meterProvider;
+				}
 				const key = `${signal.name}\u0000${signal.unit ?? ""}`;
 				let histogram = this.#histograms.get(key);
 				if (!histogram) {
 					if (this.#histograms.size >= this.#maxMetricInstruments) return;
-					histogram = metrics.getMeter(this.#instrumentationName, this.#instrumentationVersion).createHistogram(signal.name, { ...signal.unit ? { unit: signal.unit } : {} });
+					histogram = meterProvider.getMeter(this.#instrumentationName, this.#instrumentationVersion).createHistogram(signal.name, { ...signal.unit ? { unit: signal.unit } : {} });
 					this.#histograms.set(key, histogram);
 				}
 				const metricAttributes = Object.fromEntries(Object.entries(signal.attributes).filter(([name]) => this.#metricAttributeAllowlist.has(name)));
@@ -239,7 +274,7 @@ var OpenTelemetryAdapter = class {
 			}, async (span) => {
 				operationRan = true;
 				try {
-					operationResult = await operation();
+					operationResult = await operation(new OpenTelemetrySpan(span));
 					operationSucceeded = true;
 				} catch (error) {
 					operationError = error;
@@ -261,7 +296,10 @@ var OpenTelemetryAdapter = class {
 		}
 		if (operationSucceeded) return operationResult;
 		if (operationRan) throw operationError;
-		return operation();
+		throw new Error("OpenTelemetry tracer did not invoke the span operation");
+	}
+	flush() {
+		return flushOpenTelemetryProviders();
 	}
 	async shutdown() {
 		await this.#shutdown?.();
@@ -275,7 +313,7 @@ function createOpenTelemetryAdapter(config) {
 }
 function currentTraceContext() {
 	const spanContext = trace.getSpan(context.active())?.spanContext();
-	if (!spanContext) return void 0;
+	if (!spanContext || !isSpanContextValid(spanContext)) return void 0;
 	return {
 		traceId: spanContext.traceId,
 		spanId: spanContext.spanId,
@@ -312,22 +350,25 @@ async function withSpan(name, operation, attributes = {}, options = {}) {
 	});
 }
 function recordException(error, attributes = {}) {
-	const activeSpan = trace.getActiveSpan();
-	const span = activeSpan ?? trace.getTracer("@davidilie/telemetry-node").startSpan("exception");
-	span.setAttributes(toOtelAttributes(sanitizeAttributes(attributes)));
-	span.recordException(exceptionForOtel(error));
-	span.setStatus({
-		code: SpanStatusCode.ERROR,
-		...error instanceof Error ? { message: redactText(error.message) } : {}
-	});
-	if (!activeSpan) span.end();
+	let ownedSpan;
+	try {
+		const span = trace.getActiveSpan() ?? (ownedSpan = trace.getTracer("@davidilie/telemetry-node").startSpan("exception"));
+		const exception = exceptionForOtel(error);
+		span.setAttributes(toOtelAttributes(sanitizeAttributes(attributes)));
+		span.recordException(exception);
+		span.setStatus({
+			code: SpanStatusCode.ERROR,
+			message: typeof exception === "string" ? exception : exception.message
+		});
+	} catch {} finally {
+		try {
+			ownedSpan?.end();
+		} catch {}
+	}
 }
 //#endregion
 //#region src/client.ts
 var NodeTelemetryClient = class extends TelemetryClient {
-	#adapter;
-	#sampleRate;
-	#onError;
 	#onCollectionStateChange;
 	#enabled;
 	#consent;
@@ -353,9 +394,6 @@ var NodeTelemetryClient = class extends TelemetryClient {
 			...config.debug !== void 0 ? { debug: config.debug } : {},
 			...config.onError ? { onError: config.onError } : {}
 		});
-		this.#adapter = adapter;
-		this.#sampleRate = config.providerManagedSampling ? 1 : Number.isFinite(config.sampleRate) ? Math.min(1, Math.max(0, config.sampleRate ?? 1)) : 1;
-		this.#onError = config.onError;
 		this.#onCollectionStateChange = config.onCollectionStateChange;
 		this.#enabled = config.enabled ?? true;
 		this.#consent = config.consent ?? "granted";
@@ -376,26 +414,6 @@ var NodeTelemetryClient = class extends TelemetryClient {
 			consent: this.#consent
 		});
 	}
-	async withSpan(name, operation, attributes = {}, options = {}) {
-		if (!this.#enabled || this.#consent !== "granted" || Math.random() >= this.#sampleRate) return operation();
-		let operationStarted = false;
-		try {
-			return await this.#adapter.withActiveSpan(redactText(name, 256), () => {
-				operationStarted = true;
-				return operation();
-			}, sanitizeAttributes(attributes), options);
-		} catch (error) {
-			if (operationStarted) throw error;
-			this.#reportAdapterError(error, { operation: "startSpan" });
-			return operation();
-		}
-	}
-	#reportAdapterError(error, context) {
-		if (!this.#onError) return;
-		try {
-			Promise.resolve(this.#onError(error, context)).catch(() => void 0);
-		} catch {}
-	}
 };
 function createNodeTelemetry(config) {
 	return new NodeTelemetryClient(config);

package/dist/{sampler-CGBWEZod.cjs → sampler-vVC2xXgy.cjs}

@@ -38,6 +38,22 @@ function telemetryResourceAttributes(resource) {
 	};
 }
 //#endregion
+//#region src/flush.ts
+/** Flush registered SDK providers using their public lifecycle methods. */
+async function flushOpenTelemetryProviders() {
+	let tracerProvider = _opentelemetry_api.trace.getTracerProvider();
+	if ("getDelegate" in tracerProvider && typeof tracerProvider.getDelegate === "function") tracerProvider = tracerProvider.getDelegate();
+	const providers = [
+		tracerProvider,
+		_opentelemetry_api_logs.logs.getLoggerProvider(),
+		_opentelemetry_api.metrics.getMeterProvider()
+	];
+	const errors = (await Promise.allSettled(providers.map(async (provider) => {
+		if ("forceFlush" in provider && typeof provider.forceFlush === "function") await provider.forceFlush();
+	}))).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+	if (errors.length > 0) throw new AggregateError(errors, "OpenTelemetry provider flush failed");
+}
+//#endregion
 //#region src/adapter.ts
 const severityNumbers = {
 	debug: _opentelemetry_api_logs.SeverityNumber.DEBUG,
@@ -46,13 +62,17 @@ const severityNumbers = {
 	error: _opentelemetry_api_logs.SeverityNumber.ERROR
 };
 function exceptionForOtel(error) {
-	if (error instanceof Error) {
-		const safe = new Error((0, _davidilie_telemetry_core.redactText)(error.message), { ...error.cause !== void 0 ? { cause: (0, _davidilie_telemetry_core.redactText)(String(error.cause)) } : {} });
-		safe.name = (0, _davidilie_telemetry_core.redactText)(error.name, 256);
-		if (error.stack) safe.stack = (0, _davidilie_telemetry_core.redactText)(error.stack, 16384);
-		return safe;
+	try {
+		if (error instanceof Error) {
+			const safe = new Error((0, _davidilie_telemetry_core.redactText)(error.message), { ...error.cause !== void 0 ? { cause: (0, _davidilie_telemetry_core.redactText)(String(error.cause)) } : {} });
+			safe.name = (0, _davidilie_telemetry_core.redactText)(error.name, 256);
+			if (error.stack) safe.stack = (0, _davidilie_telemetry_core.redactText)(error.stack, 16384);
+			return safe;
+		}
+		return (0, _davidilie_telemetry_core.redactText)(typeof error === "string" ? error : String(error));
+	} catch {
+		return "Unserializable exception";
 	}
-	return (0, _davidilie_telemetry_core.redactText)(typeof error === "string" ? error : String(error));
 }
 function signalAttributes(signal) {
 	return {
@@ -100,6 +120,14 @@ var OpenTelemetrySpan = class {
 	end() {
 		this.#span.end();
 	}
+	traceContext() {
+		const value = this.#span.spanContext();
+		return (0, _opentelemetry_api.isSpanContextValid)(value) ? {
+			traceId: value.traceId,
+			spanId: value.spanId,
+			traceFlags: value.traceFlags
+		} : void 0;
+	}
 };
 var OpenTelemetryAdapter = class {
 	#instrumentationName;
@@ -112,6 +140,7 @@ var OpenTelemetryAdapter = class {
 	#logSampleRate;
 	#shutdown;
 	#histograms = /* @__PURE__ */ new Map();
+	#meterProvider;
 	constructor(config) {
 		this.#resource = (0, _davidilie_telemetry_core.sanitizeResource)(config.resource);
 		this.#instrumentationName = config.instrumentationName ?? this.#resource.serviceName;
@@ -129,7 +158,7 @@ var OpenTelemetryAdapter = class {
 		switch (signal.type) {
 			case "event": {
 				const activeSpan = _opentelemetry_api.trace.getActiveSpan();
-				if (activeSpan) {
+				if (activeSpan?.isRecording()) {
 					activeSpan.addEvent(signal.name, attributes, new Date(signal.timestamp));
 					return;
 				}
@@ -144,22 +173,23 @@ var OpenTelemetryAdapter = class {
 			}
 			case "exception": {
 				const activeSpan = _opentelemetry_api.trace.getActiveSpan();
-				const span = activeSpan ?? this.#tracer().startSpan("exception", {
+				const recordingSpan = activeSpan?.isRecording() ? activeSpan : void 0;
+				const span = recordingSpan ?? this.#tracer().startSpan("exception", {
 					kind: _opentelemetry_api.SpanKind.INTERNAL,
 					attributes,
 					startTime: new Date(signal.timestamp)
 				});
-				span.setAttributes(attributes);
-				span.recordException({
-					name: signal.exception.name,
-					message: signal.exception.message,
-					...signal.exception.stack ? { stack: signal.exception.stack } : {}
-				});
+				span.addEvent("exception", {
+					...attributes,
+					"exception.type": signal.exception.name,
+					"exception.message": signal.exception.message,
+					...signal.exception.stack ? { "exception.stacktrace": signal.exception.stack } : {}
+				}, new Date(signal.timestamp));
 				span.setStatus({
 					code: _opentelemetry_api.SpanStatusCode.ERROR,
 					message: signal.exception.message
 				});
-				if (!activeSpan) span.end(new Date(signal.timestamp));
+				if (!recordingSpan) span.end(new Date(signal.timestamp));
 				return;
 			}
 			case "log":
@@ -200,11 +230,16 @@ var OpenTelemetryAdapter = class {
 				}).end(new Date(signal.timestamp));
 				if (this.#measurementMode === "spans") return;
 				if (!VALID_INSTRUMENT_NAME.test(signal.name)) return;
+				const meterProvider = _opentelemetry_api.metrics.getMeterProvider();
+				if (meterProvider !== this.#meterProvider) {
+					this.#histograms.clear();
+					this.#meterProvider = meterProvider;
+				}
 				const key = `${signal.name}\u0000${signal.unit ?? ""}`;
 				let histogram = this.#histograms.get(key);
 				if (!histogram) {
 					if (this.#histograms.size >= this.#maxMetricInstruments) return;
-					histogram = _opentelemetry_api.metrics.getMeter(this.#instrumentationName, this.#instrumentationVersion).createHistogram(signal.name, { ...signal.unit ? { unit: signal.unit } : {} });
+					histogram = meterProvider.getMeter(this.#instrumentationName, this.#instrumentationVersion).createHistogram(signal.name, { ...signal.unit ? { unit: signal.unit } : {} });
 					this.#histograms.set(key, histogram);
 				}
 				const metricAttributes = Object.fromEntries(Object.entries(signal.attributes).filter(([name]) => this.#metricAttributeAllowlist.has(name)));
@@ -239,7 +274,7 @@ var OpenTelemetryAdapter = class {
 			}, async (span) => {
 				operationRan = true;
 				try {
-					operationResult = await operation();
+					operationResult = await operation(new OpenTelemetrySpan(span));
 					operationSucceeded = true;
 				} catch (error) {
 					operationError = error;
@@ -261,7 +296,10 @@ var OpenTelemetryAdapter = class {
 		}
 		if (operationSucceeded) return operationResult;
 		if (operationRan) throw operationError;
-		return operation();
+		throw new Error("OpenTelemetry tracer did not invoke the span operation");
+	}
+	flush() {
+		return flushOpenTelemetryProviders();
 	}
 	async shutdown() {
 		await this.#shutdown?.();
@@ -275,7 +313,7 @@ function createOpenTelemetryAdapter(config) {
 }
 function currentTraceContext() {
 	const spanContext = _opentelemetry_api.trace.getSpan(_opentelemetry_api.context.active())?.spanContext();
-	if (!spanContext) return void 0;
+	if (!spanContext || !(0, _opentelemetry_api.isSpanContextValid)(spanContext)) return void 0;
 	return {
 		traceId: spanContext.traceId,
 		spanId: spanContext.spanId,
@@ -312,22 +350,25 @@ async function withSpan(name, operation, attributes = {}, options = {}) {
 	});
 }
 function recordException(error, attributes = {}) {
-	const activeSpan = _opentelemetry_api.trace.getActiveSpan();
-	const span = activeSpan ?? _opentelemetry_api.trace.getTracer("@davidilie/telemetry-node").startSpan("exception");
-	span.setAttributes(toOtelAttributes((0, _davidilie_telemetry_core.sanitizeAttributes)(attributes)));
-	span.recordException(exceptionForOtel(error));
-	span.setStatus({
-		code: _opentelemetry_api.SpanStatusCode.ERROR,
-		...error instanceof Error ? { message: (0, _davidilie_telemetry_core.redactText)(error.message) } : {}
-	});
-	if (!activeSpan) span.end();
+	let ownedSpan;
+	try {
+		const span = _opentelemetry_api.trace.getActiveSpan() ?? (ownedSpan = _opentelemetry_api.trace.getTracer("@davidilie/telemetry-node").startSpan("exception"));
+		const exception = exceptionForOtel(error);
+		span.setAttributes(toOtelAttributes((0, _davidilie_telemetry_core.sanitizeAttributes)(attributes)));
+		span.recordException(exception);
+		span.setStatus({
+			code: _opentelemetry_api.SpanStatusCode.ERROR,
+			message: typeof exception === "string" ? exception : exception.message
+		});
+	} catch {} finally {
+		try {
+			ownedSpan?.end();
+		} catch {}
+	}
 }
 //#endregion
 //#region src/client.ts
 var NodeTelemetryClient = class extends _davidilie_telemetry_core.TelemetryClient {
-	#adapter;
-	#sampleRate;
-	#onError;
 	#onCollectionStateChange;
 	#enabled;
 	#consent;
@@ -353,9 +394,6 @@ var NodeTelemetryClient = class extends _davidilie_telemetry_core.TelemetryClien
 			...config.debug !== void 0 ? { debug: config.debug } : {},
 			...config.onError ? { onError: config.onError } : {}
 		});
-		this.#adapter = adapter;
-		this.#sampleRate = config.providerManagedSampling ? 1 : Number.isFinite(config.sampleRate) ? Math.min(1, Math.max(0, config.sampleRate ?? 1)) : 1;
-		this.#onError = config.onError;
 		this.#onCollectionStateChange = config.onCollectionStateChange;
 		this.#enabled = config.enabled ?? true;
 		this.#consent = config.consent ?? "granted";
@@ -376,26 +414,6 @@ var NodeTelemetryClient = class extends _davidilie_telemetry_core.TelemetryClien
 			consent: this.#consent
 		});
 	}
-	async withSpan(name, operation, attributes = {}, options = {}) {
-		if (!this.#enabled || this.#consent !== "granted" || Math.random() >= this.#sampleRate) return operation();
-		let operationStarted = false;
-		try {
-			return await this.#adapter.withActiveSpan((0, _davidilie_telemetry_core.redactText)(name, 256), () => {
-				operationStarted = true;
-				return operation();
-			}, (0, _davidilie_telemetry_core.sanitizeAttributes)(attributes), options);
-		} catch (error) {
-			if (operationStarted) throw error;
-			this.#reportAdapterError(error, { operation: "startSpan" });
-			return operation();
-		}
-	}
-	#reportAdapterError(error, context) {
-		if (!this.#onError) return;
-		try {
-			Promise.resolve(this.#onError(error, context)).catch(() => void 0);
-		} catch {}
-	}
 };
 function createNodeTelemetry(config) {
 	return new NodeTelemetryClient(config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidilie/telemetry-node",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "OpenTelemetry-backed telemetry for Node.js services.",
   "keywords": [
     "analytics",
@@ -65,7 +65,7 @@
     "clean": "rm -rf dist coverage"
   },
   "dependencies": {
-    "@davidilie/telemetry-core": "0.2.0",
+    "@davidilie/telemetry-core": "0.4.0",
     "@opentelemetry/api-logs": "0.221.0",
     "@opentelemetry/resources": "2.10.0",
     "@opentelemetry/sdk-node": "0.221.0",