@zudojs/observability 1.0.1 → 1.1.0

package/README.md

@@ -2,6 +2,12 @@
 
 Structured logging, metrics, tracing, context propagation, and telemetry exporters for Zudojs applications.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-observability](https://zudojs.oyinlola.site/docs/packages-observability) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-observability.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -68,6 +74,12 @@ await obs.logger.flush();
 Every record carries `traceId` and `spanId` when a propagation context is
 active, so logs and traces line up without threading IDs by hand.
 
+`LogLevel` here counts upward in severity (`TRACE = 0 … FATAL = 5`), the
+opposite of `@zudojs/logger`'s `LoggerLevel` (`FATAL = 0 … TRACE = 5`).
+Never pass a raw level number between the two; convert with
+`toLoggerLevel(LogLevel.ERROR)` (→ `1`) and `fromLoggerLevel(1)`
+(→ `LogLevel.ERROR`).
+
 ## Redaction
 
 Redaction is off unless you configure it, and on once you do. The logger
@@ -143,6 +155,10 @@ const obs = createObservability({
 });
 ```
 
+`metrics.onCardinalityLimit` fires once per rejected series, and the facade
+raises `onError` once per metric name, so a label explosion is one report
+rather than one per metric call.
+
 One metric name may only ever be one type: registering `counter("latency")`
 and then `histogram("latency")` throws, because a document carrying the same
 name as two types is rejected wholesale by OTLP and Prometheus.
@@ -218,6 +234,38 @@ obs.propagation.current(); // undefined outside a run() scope
 `current()` returns `undefined` when there is no active context, so "no trace"
 stays distinguishable from a real one.
 
+A span started without an explicit `parent` joins the active context, so the
+span and the log records written in the same scope share one `traceId`. To
+make a span itself the active context — so logs inside it carry its `spanId`
+and nested spans become its children — use `withSpan` (or
+`tracer.startActiveSpan` on a `DefaultTracer`). It ends the span when the
+callback returns or its promise settles, and records a throw or rejection:
+
+```typescript
+import { withSpan } from "@zudojs/observability";
+
+const rows = await withSpan(obs.tracer, "db.query", async (span) => {
+  span.setAttribute("db.system", "postgresql");
+  obs.logger.info("querying"); // carries this span's traceId and spanId
+  return [1, 2, 3];
+});
+```
+
+Inbound trace IDs are validated. `parseTraceparent` reads a W3C
+`traceparent` header and returns `undefined` for anything malformed;
+`formatTraceparent` writes one for an outgoing request. A parent or
+propagation context whose trace or span ID is not valid W3C hex is never
+joined — the span starts a fresh trace instead:
+
+```typescript
+import { formatTraceparent, parseTraceparent } from "@zudojs/observability";
+
+const parent = parseTraceparent(request.headers["traceparent"]);
+const span = obs.tracer.startSpan("handle", { parent }); // fresh trace if absent
+const outgoing = formatTraceparent(span.context); // "00-<trace>-<span>-01"
+span.end();
+```
+
 ## Exporters
 
 Console exporters ship for development. They serialize defensively — a

package/dist/errors/observabilityError.core.d.ts

@@ -6,15 +6,14 @@
  * recorded with a value that cannot be aggregated. Failures in the transport
  * layer are reported through `ObservabilityConfig.onError` instead.
  */
-import { BaseError, ErrorCode } from "@zudojs/errors";
-/** Base error for all observability failures. */
-export declare class ObservabilityError extends BaseError {
-    constructor(message: string, options?: {
-        readonly code?: ErrorCode;
-        readonly metadata?: Readonly<Record<string, unknown>>;
-        readonly cause?: unknown;
-    });
-}
+import { ObservabilityError } from "@zudojs/errors";
+/**
+ * Base error for all observability failures (500, not exposed). Owned by
+ * `@zudojs/errors` and re-exported here, so `instanceof` matches across
+ * both import paths.
+ */
+export { ObservabilityError };
+export type { ObservabilityErrorOptions } from "@zudojs/errors";
 /** An exporter failed to deliver telemetry. */
 export declare class ExporterError extends ObservabilityError {
     constructor(exporterName: string, cause?: unknown);

package/dist/errors/observabilityError.core.js

@@ -6,22 +6,13 @@
  * recorded with a value that cannot be aggregated. Failures in the transport
  * layer are reported through `ObservabilityConfig.onError` instead.
  */
-import { BaseError, ErrorCode, ErrorCategory, ErrorSeverity, } from "@zudojs/errors";
-/** Base error for all observability failures. */
-export class ObservabilityError extends BaseError {
-    constructor(message, options) {
-        super(message, {
-            code: options?.code ?? ErrorCode.OPERATION_FAILED,
-            category: ErrorCategory.INTERNAL,
-            severity: ErrorSeverity.ERROR,
-            statusCode: 500,
-            expose: false,
-            metadata: options?.metadata,
-            cause: options?.cause,
-        });
-        this.name = "ObservabilityError";
-    }
-}
+import { ErrorCode, ObservabilityError } from "@zudojs/errors";
+/**
+ * Base error for all observability failures (500, not exposed). Owned by
+ * `@zudojs/errors` and re-exported here, so `instanceof` matches across
+ * both import paths.
+ */
+export { ObservabilityError };
 /** An exporter failed to deliver telemetry. */
 export class ExporterError extends ObservabilityError {
     constructor(exporterName, cause) {

package/dist/index.d.ts

@@ -33,12 +33,12 @@
 export { LogLevel, SpanStatus, SpanKind, TraceFlags, type LogLevelName, type LogRecord, type LogRecordError, type Logger, type LoggerOptions, type LogTransport, type PropagationContext, type PropagationContextOptions, type PropagationManager, type Counter, type Gauge, type Histogram, type HistogramValue, type MetricsRegistry, type MetricSnapshot, type Span, type SpanContext, type SpanEvent, type SpanOptions, type SpanLimits, type Tracer, type ReadableSpan, type SpanExporter, type LogExporter, type MetricExporter, type SpanProcessor, type SamplingResult, type Sampler, type RedactionConfig, type RedactionMatchMode, type Observability, type ObservabilityConfig, } from "./types.js";
 export { ObservabilityError, ExporterError, ObservabilityConfigError, MetricValueError, isObservabilityError, } from "./errors/index.js";
 export { generateTraceId, generateSpanId, isValidTraceId, isValidSpanId, } from "./internal/index.js";
-export { logLevelToName, logLevelFromName, parseLogLevel, shouldLog, getLogLevelNames, } from "./logLevel/index.js";
+export { logLevelToName, logLevelFromName, parseLogLevel, shouldLog, getLogLevelNames, toLoggerLevel, fromLoggerLevel, } from "./logLevel/index.js";
 export { createLogRecord, createErrorLogRecord, serializeError, } from "./logRecord/index.js";
 export { StructuredLogger, createStructuredLogger } from "./logger/index.js";
-export { createPropagationContext, derivePropagationContext, getCurrentContext, requireCurrentContext, AsyncPropagationManager, createPropagationManager, } from "./propagation/index.js";
+export { createPropagationContext, derivePropagationContext, getCurrentContext, requireCurrentContext, AsyncPropagationManager, createPropagationManager, parseTraceparent, formatTraceparent, TRACEPARENT_HEADER, } from "./propagation/index.js";
 export { DefaultCounter, createCounter, DefaultGauge, createGauge, DefaultHistogram, createHistogram, DEFAULT_BUCKET_BOUNDARIES, DefaultMetricsRegistry, createMetricsRegistry, metricKey, PeriodicMetricReader, createPeriodicMetricReader, type MetricsRegistryOptions, type PeriodicMetricReaderOptions, } from "./metrics/index.js";
-export { DefaultSpan, createSpan, createSpanContext, createChildSpanContext, isSampledContext, DefaultTracer, createTracer, type TracerOptions, } from "./tracing/index.js";
+export { DefaultSpan, createSpan, createSpanContext, createChildSpanContext, isSampledContext, isValidSpanContext, DefaultTracer, createTracer, withSpan, type TracerOptions, } from "./tracing/index.js";
 export { AlwaysOnSampler, AlwaysOffSampler, ProbabilitySampler, ParentBasedSampler, createAlwaysOnSampler, createAlwaysOffSampler, createProbabilitySampler, createParentBasedSampler, isSampled, isRecording, type ParentBasedSamplerOptions, } from "./sampling/index.js";
 export { ConsoleSpanExporter, ConsoleLogExporter, ConsoleMetricExporter, createConsoleSpanExporter, createConsoleLogExporter, createConsoleMetricExporter, noopLogExporter, noopMetricExporter, safeStringify, type ConsoleExporterOptions, type ConsoleLike, } from "./exporter/index.js";
 export { BatchSpanProcessor, createBatchSpanProcessor, SimpleSpanProcessor, createSimpleSpanProcessor, BatchLogProcessor, createBatchLogProcessor, noopSpanExporter, type BatchSpanProcessorOptions, type BatchLogProcessorOptions, } from "./processor/index.js";

package/dist/index.js

@@ -37,17 +37,17 @@ export { ObservabilityError, ExporterError, ObservabilityConfigError, MetricValu
 /* ─── Identifiers ───────────────────────────────────────────────────────── */
 export { generateTraceId, generateSpanId, isValidTraceId, isValidSpanId, } from "./internal/index.js";
 /* ─── Log Level ─────────────────────────────────────────────────────────── */
-export { logLevelToName, logLevelFromName, parseLogLevel, shouldLog, getLogLevelNames, } from "./logLevel/index.js";
+export { logLevelToName, logLevelFromName, parseLogLevel, shouldLog, getLogLevelNames, toLoggerLevel, fromLoggerLevel, } from "./logLevel/index.js";
 /* ─── Log Record ────────────────────────────────────────────────────────── */
 export { createLogRecord, createErrorLogRecord, serializeError, } from "./logRecord/index.js";
 /* ─── Logger ────────────────────────────────────────────────────────────── */
 export { StructuredLogger, createStructuredLogger } from "./logger/index.js";
 /* ─── Propagation ───────────────────────────────────────────────────────── */
-export { createPropagationContext, derivePropagationContext, getCurrentContext, requireCurrentContext, AsyncPropagationManager, createPropagationManager, } from "./propagation/index.js";
+export { createPropagationContext, derivePropagationContext, getCurrentContext, requireCurrentContext, AsyncPropagationManager, createPropagationManager, parseTraceparent, formatTraceparent, TRACEPARENT_HEADER, } from "./propagation/index.js";
 /* ─── Metrics ───────────────────────────────────────────────────────────── */
 export { DefaultCounter, createCounter, DefaultGauge, createGauge, DefaultHistogram, createHistogram, DEFAULT_BUCKET_BOUNDARIES, DefaultMetricsRegistry, createMetricsRegistry, metricKey, PeriodicMetricReader, createPeriodicMetricReader, } from "./metrics/index.js";
 /* ─── Tracing ───────────────────────────────────────────────────────────── */
-export { DefaultSpan, createSpan, createSpanContext, createChildSpanContext, isSampledContext, DefaultTracer, createTracer, } from "./tracing/index.js";
+export { DefaultSpan, createSpan, createSpanContext, createChildSpanContext, isSampledContext, isValidSpanContext, DefaultTracer, createTracer, withSpan, } from "./tracing/index.js";
 /* ─── Sampling ──────────────────────────────────────────────────────────── */
 export { AlwaysOnSampler, AlwaysOffSampler, ProbabilitySampler, ParentBasedSampler, createAlwaysOnSampler, createAlwaysOffSampler, createProbabilitySampler, createParentBasedSampler, isSampled, isRecording, } from "./sampling/index.js";
 /* ─── Exporters ─────────────────────────────────────────────────────────── */

package/dist/logLevel/index.d.ts

@@ -4,4 +4,5 @@
  * Level names, conversion, and filtering utilities.
  */
 export { logLevelToName, logLevelFromName, parseLogLevel, shouldLog, getLogLevelNames, } from "./logLevel.type.js";
+export { toLoggerLevel, fromLoggerLevel } from "./logLevel.bridge.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/logLevel/index.js

@@ -4,4 +4,5 @@
  * Level names, conversion, and filtering utilities.
  */
 export { logLevelToName, logLevelFromName, parseLogLevel, shouldLog, getLogLevelNames, } from "./logLevel.type.js";
+export { toLoggerLevel, fromLoggerLevel } from "./logLevel.bridge.js";
 //# sourceMappingURL=index.js.map

package/dist/logLevel/logLevel.bridge.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @zudojs/observability — Level bridge to @zudojs/logger
+ *
+ * The two packages number their levels in opposite directions: here a higher
+ * value is more severe (`TRACE = 0 … FATAL = 5`), in `@zudojs/logger` a lower
+ * value is more severe (`FATAL = 0 … TRACE = 5`). Passing a raw number from
+ * one to the other inverts filtering, so convert explicitly with these.
+ */
+import { LogLevel } from "../types.js";
+/**
+ * Converts an observability {@link LogLevel} to the numeric value of the
+ * same-named `@zudojs/logger` `LoggerLevel`.
+ *
+ * Returns `undefined` for {@link LogLevel.OFF}, which has no logger
+ * counterpart, and for any value outside the enum.
+ */
+export declare function toLoggerLevel(level: LogLevel): number | undefined;
+/**
+ * Converts a numeric `@zudojs/logger` `LoggerLevel` to the same-named
+ * observability {@link LogLevel}.
+ *
+ * Returns `undefined` for a value outside `LoggerLevel` (`0`–`5`).
+ */
+export declare function fromLoggerLevel(level: number): LogLevel | undefined;
+//# sourceMappingURL=logLevel.bridge.d.ts.map

package/dist/logLevel/logLevel.bridge.js

@@ -0,0 +1,38 @@
+/**
+ * @zudojs/observability — Level bridge to @zudojs/logger
+ *
+ * The two packages number their levels in opposite directions: here a higher
+ * value is more severe (`TRACE = 0 … FATAL = 5`), in `@zudojs/logger` a lower
+ * value is more severe (`FATAL = 0 … TRACE = 5`). Passing a raw number from
+ * one to the other inverts filtering, so convert explicitly with these.
+ */
+import { LogLevel } from "../types.js";
+/** The most verbose `@zudojs/logger` `LoggerLevel` value (`TRACE`). */
+const LOGGER_TRACE = 5;
+/**
+ * Converts an observability {@link LogLevel} to the numeric value of the
+ * same-named `@zudojs/logger` `LoggerLevel`.
+ *
+ * Returns `undefined` for {@link LogLevel.OFF}, which has no logger
+ * counterpart, and for any value outside the enum.
+ */
+export function toLoggerLevel(level) {
+    if (!Number.isInteger(level) || level < LogLevel.TRACE)
+        return undefined;
+    if (level > LogLevel.FATAL)
+        return undefined;
+    return LOGGER_TRACE - level;
+}
+/**
+ * Converts a numeric `@zudojs/logger` `LoggerLevel` to the same-named
+ * observability {@link LogLevel}.
+ *
+ * Returns `undefined` for a value outside `LoggerLevel` (`0`–`5`).
+ */
+export function fromLoggerLevel(level) {
+    if (!Number.isInteger(level) || level < 0 || level > LOGGER_TRACE) {
+        return undefined;
+    }
+    return (LOGGER_TRACE - level);
+}
+//# sourceMappingURL=logLevel.bridge.js.map

package/dist/metrics/metrics.registry.d.ts

@@ -52,6 +52,12 @@ export declare class DefaultMetricsRegistry implements MetricsRegistry {
      * documented ceiling is not quietly doubled by the overflow path.
      */
     private readonly maxOverflow;
+    /**
+     * Series already reported to `onCardinalityLimit`. Kept apart from the
+     * overflow cache, whose small bound made the callback re-fire for every
+     * repeat of an already-rejected series once it was full.
+     */
+    private readonly rejected;
     constructor(options?: MetricsRegistryOptions);
     private create;
     private obtain;

package/dist/metrics/metrics.registry.js

@@ -25,6 +25,8 @@ export function metricKey(type, name, labels) {
 const DEFAULT_MAX_SERIES = 10_000;
 /** Upper bound on the detached series kept for callers past the cap. */
 const MAX_OVERFLOW_SERIES = 1_024;
+/** Upper bound on the rejected series remembered for de-duplicated reporting. */
+const MAX_REJECTED_KEYS = 10_000;
 /**
  * In-memory metrics registry. Creates, caches, and manages metrics.
  */
@@ -50,6 +52,12 @@ export class DefaultMetricsRegistry {
      * documented ceiling is not quietly doubled by the overflow path.
      */
     maxOverflow;
+    /**
+     * Series already reported to `onCardinalityLimit`. Kept apart from the
+     * overflow cache, whose small bound made the callback re-fire for every
+     * repeat of an already-rejected series once it was full.
+     */
+    rejected = new Set();
     constructor(options) {
         this.maxSeries = options?.maxSeries ?? DEFAULT_MAX_SERIES;
         this.maxOverflow = Math.max(1, Math.min(this.maxSeries, MAX_OVERFLOW_SERIES));
@@ -83,7 +91,11 @@ export class DefaultMetricsRegistry {
             const cached = this.overflow.get(key);
             if (cached)
                 return cached;
-            this.onCardinalityLimit?.(name, this.metrics.size);
+            if (!this.rejected.has(key)) {
+                if (this.rejected.size < MAX_REJECTED_KEYS)
+                    this.rejected.add(key);
+                this.onCardinalityLimit?.(name, this.metrics.size);
+            }
             const detached = this.create(type, name, labels);
             if (this.overflow.size < this.maxOverflow)
                 this.overflow.set(key, detached);
@@ -170,6 +182,7 @@ export class DefaultMetricsRegistry {
     clear() {
         this.metrics.clear();
         this.overflow.clear();
+        this.rejected.clear();
         this.typeByName.clear();
     }
 }

package/dist/observability/observability.core.js

@@ -185,10 +185,16 @@ function buildPipeline(config) {
     // When the caller supplied their own processors, they own the exporter's
     // lifecycle too; otherwise our processor closes it on shutdown.
     /* ── Metrics ─────────────────────────────────────────────────────────── */
+    // onError hears about each over-cardinality metric name once: a label
+    // explosion is one problem, not one Error allocation per metric call.
+    const reportedNames = new Set();
     const metrics = new DefaultMetricsRegistry({
         ...(config.metrics ?? {}),
         onCardinalityLimit: (name, size) => {
             config.metrics?.onCardinalityLimit?.(name, size);
+            if (reportedNames.has(name) || reportedNames.size >= 1_024)
+                return;
+            reportedNames.add(name);
             config.onError?.(new Error(`Metric "${name}" exceeded the registry's series limit (${size}); ` +
                 `check for a high-cardinality label`), "MetricsRegistry");
         },

package/dist/propagation/index.d.ts

@@ -4,4 +4,5 @@
  * Context propagation with AsyncLocalStorage for request-scoped IDs.
  */
 export { createPropagationContext, derivePropagationContext, getCurrentContext, requireCurrentContext, AsyncPropagationManager, createPropagationManager, } from "./propagation.core.js";
+export { parseTraceparent, formatTraceparent, TRACEPARENT_HEADER, } from "./propagation.traceparent.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/propagation/index.js

@@ -4,4 +4,5 @@
  * Context propagation with AsyncLocalStorage for request-scoped IDs.
  */
 export { createPropagationContext, derivePropagationContext, getCurrentContext, requireCurrentContext, AsyncPropagationManager, createPropagationManager, } from "./propagation.core.js";
+export { parseTraceparent, formatTraceparent, TRACEPARENT_HEADER, } from "./propagation.traceparent.js";
 //# sourceMappingURL=index.js.map

package/dist/propagation/propagation.core.d.ts

@@ -5,7 +5,13 @@
  * trace, span, request, and correlation IDs.
  */
 import type { PropagationContext, PropagationContextOptions, PropagationManager } from "../types.js";
-/** Creates a new propagation context. */
+/**
+ * Creates a new propagation context.
+ *
+ * Supplied trace and span IDs are validated: an invalid `traceId` or
+ * `parentSpanId` starts a fresh trace (and drops the untrusted sampling
+ * flags), and an invalid `spanId` is replaced.
+ */
 export declare function createPropagationContext(options?: PropagationContextOptions): PropagationContext;
 /**
  * Derives a child context from a parent.

package/dist/propagation/propagation.core.js

@@ -5,19 +5,29 @@
  * trace, span, request, and correlation IDs.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
-import { generateSpanId, generateTraceId } from "../internal/index.js";
+import { generateSpanId, generateTraceId, isValidSpanId, isValidTraceId, } from "../internal/index.js";
 const storage = new AsyncLocalStorage();
-/** Creates a new propagation context. */
+/**
+ * Creates a new propagation context.
+ *
+ * Supplied trace and span IDs are validated: an invalid `traceId` or
+ * `parentSpanId` starts a fresh trace (and drops the untrusted sampling
+ * flags), and an invalid `spanId` is replaced.
+ */
 export function createPropagationContext(options) {
+    const joins = (options?.traceId === undefined || isValidTraceId(options.traceId)) &&
+        (options?.parentSpanId === undefined ||
+            isValidSpanId(options.parentSpanId));
+    const spanId = options?.spanId;
     return {
-        traceId: options?.traceId ?? generateTraceId(),
-        spanId: options?.spanId ?? generateSpanId(),
-        parentSpanId: options?.parentSpanId,
+        traceId: (joins ? options?.traceId : undefined) ?? generateTraceId(),
+        spanId: spanId !== undefined && isValidSpanId(spanId) ? spanId : generateSpanId(),
+        parentSpanId: joins ? options?.parentSpanId : undefined,
         requestId: options?.requestId,
         correlationId: options?.correlationId,
         userId: options?.userId,
         service: options?.service,
-        traceFlags: options?.traceFlags,
+        traceFlags: joins ? options?.traceFlags : undefined,
         baggage: options?.baggage
             ? Object.freeze({ ...options.baggage })
             : undefined,

package/dist/propagation/propagation.traceparent.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @zudojs/observability — W3C `traceparent` header
+ *
+ * Parses and formats the W3C Trace Context `traceparent` header, using the
+ * same ID validators as the span and propagation factories so an inbound
+ * header can never smuggle a malformed ID into a trace.
+ */
+import type { SpanContext } from "../types.js";
+/** Name of the W3C trace context header. */
+export declare const TRACEPARENT_HEADER = "traceparent";
+/**
+ * Parses a `traceparent` header value.
+ *
+ * Returns the remote span context (its `spanId` is the caller's span, to be
+ * used as `parent` when starting the local span), or `undefined` when the
+ * header is missing or malformed in any way — including an all-zero trace or
+ * span ID, uppercase hex, the forbidden version `ff`, or extra fields on
+ * version `00`.
+ */
+export declare function parseTraceparent(header: string | readonly string[] | undefined | null): SpanContext | undefined;
+/**
+ * Formats a span context as a version-`00` `traceparent` header value.
+ *
+ * Returns `undefined` when the context's trace or span ID is invalid, so a
+ * malformed context is never propagated downstream.
+ */
+export declare function formatTraceparent(context: Pick<SpanContext, "traceId" | "spanId" | "traceFlags">): string | undefined;
+//# sourceMappingURL=propagation.traceparent.d.ts.map

package/dist/propagation/propagation.traceparent.js

@@ -0,0 +1,58 @@
+/**
+ * @zudojs/observability — W3C `traceparent` header
+ *
+ * Parses and formats the W3C Trace Context `traceparent` header, using the
+ * same ID validators as the span and propagation factories so an inbound
+ * header can never smuggle a malformed ID into a trace.
+ */
+import { isValidSpanId, isValidTraceId } from "../internal/index.js";
+/** Name of the W3C trace context header. */
+export const TRACEPARENT_HEADER = "traceparent";
+const HEX2 = /^[0-9a-f]{2}$/;
+/**
+ * Parses a `traceparent` header value.
+ *
+ * Returns the remote span context (its `spanId` is the caller's span, to be
+ * used as `parent` when starting the local span), or `undefined` when the
+ * header is missing or malformed in any way — including an all-zero trace or
+ * span ID, uppercase hex, the forbidden version `ff`, or extra fields on
+ * version `00`.
+ */
+export function parseTraceparent(header) {
+    const value = Array.isArray(header) ? header[0] : header;
+    if (typeof value !== "string")
+        return undefined;
+    const parts = value.trim().split("-");
+    if (parts.length < 4)
+        return undefined;
+    const [version, traceId, spanId, flags] = parts;
+    if (!HEX2.test(version) || version === "ff")
+        return undefined;
+    if (version === "00" && parts.length !== 4)
+        return undefined;
+    if (!HEX2.test(flags))
+        return undefined;
+    if (!isValidTraceId(traceId) || !isValidSpanId(spanId))
+        return undefined;
+    return Object.freeze({
+        traceId,
+        spanId,
+        traceFlags: Number.parseInt(flags, 16),
+    });
+}
+/**
+ * Formats a span context as a version-`00` `traceparent` header value.
+ *
+ * Returns `undefined` when the context's trace or span ID is invalid, so a
+ * malformed context is never propagated downstream.
+ */
+export function formatTraceparent(context) {
+    if (!isValidTraceId(context.traceId) || !isValidSpanId(context.spanId)) {
+        return undefined;
+    }
+    const flags = (context.traceFlags ?? 0) & 0xff;
+    return `00-${context.traceId}-${context.spanId}-${flags
+        .toString(16)
+        .padStart(2, "0")}`;
+}
+//# sourceMappingURL=propagation.traceparent.js.map

package/dist/redaction/redaction.core.js

@@ -210,8 +210,14 @@ function walk(value, compiled, depth, seen) {
             const redacted = redactField(key, entry, compiled);
             // A field the matcher replaced is done — never walk into it, or a
             // nested object under a sensitive key would leak through its children.
-            result[key] =
-                redacted === entry ? walk(entry, compiled, depth + 1, seen) : redacted;
+            // defineProperty, not assignment: an own `__proto__` key (JSON.parse
+            // makes one) would otherwise replace the output's prototype.
+            Object.defineProperty(result, key, {
+                value: redacted === entry ? walk(entry, compiled, depth + 1, seen) : redacted,
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
         }
         seen.delete(value);
         return result;

package/dist/tracing/index.d.ts

@@ -3,6 +3,6 @@
  *
  * Distributed tracing with spans, context, and exporters.
  */
-export { DefaultSpan, createSpan, createSpanContext, createChildSpanContext, isSampledContext, } from "./span/index.js";
-export { DefaultTracer, createTracer, type TracerOptions, } from "./tracer/index.js";
+export { DefaultSpan, createSpan, createSpanContext, createChildSpanContext, isSampledContext, isValidSpanContext, } from "./span/index.js";
+export { DefaultTracer, createTracer, withSpan, type TracerOptions, } from "./tracer/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/tracing/index.js

@@ -3,6 +3,6 @@
  *
  * Distributed tracing with spans, context, and exporters.
  */
-export { DefaultSpan, createSpan, createSpanContext, createChildSpanContext, isSampledContext, } from "./span/index.js";
-export { DefaultTracer, createTracer, } from "./tracer/index.js";
+export { DefaultSpan, createSpan, createSpanContext, createChildSpanContext, isSampledContext, isValidSpanContext, } from "./span/index.js";
+export { DefaultTracer, createTracer, withSpan, } from "./tracer/index.js";
 //# sourceMappingURL=index.js.map

package/dist/tracing/span/index.d.ts

@@ -4,5 +4,5 @@
  * Span implementation and context creation.
  */
 export { DefaultSpan, createSpan } from "./span.core.js";
-export { createSpanContext, createChildSpanContext, isSampledContext, } from "./spanContext.type.js";
+export { createSpanContext, createChildSpanContext, isSampledContext, isValidSpanContext, } from "./spanContext.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/tracing/span/index.js

@@ -4,5 +4,5 @@
  * Span implementation and context creation.
  */
 export { DefaultSpan, createSpan } from "./span.core.js";
-export { createSpanContext, createChildSpanContext, isSampledContext, } from "./spanContext.type.js";
+export { createSpanContext, createChildSpanContext, isSampledContext, isValidSpanContext, } from "./spanContext.type.js";
 //# sourceMappingURL=index.js.map

package/dist/tracing/span/spanContext.type.d.ts

@@ -4,7 +4,21 @@
  * Factory for creating span context identifiers.
  */
 import type { SpanContext } from "../../types.js";
-/** Creates a new span context with cryptographically random IDs. */
+/**
+ * True when `context` carries a valid W3C trace ID and span ID.
+ *
+ * A context that fails this check must never be adopted as a parent: its IDs
+ * usually come from an inbound header and would otherwise flow verbatim into
+ * every span, log record and exporter.
+ */
+export declare function isValidSpanContext(context: Pick<SpanContext, "traceId" | "spanId"> | undefined): boolean;
+/**
+ * Creates a new span context with cryptographically random IDs.
+ *
+ * Supplied IDs are validated. An invalid `traceId` or `parentSpanId` starts
+ * a fresh trace (new trace ID, no parent) instead of joining a trace the
+ * caller cannot vouch for; an invalid `spanId` is replaced with a new one.
+ */
 export declare function createSpanContext(options?: {
     readonly traceId?: string;
     readonly spanId?: string;
@@ -16,6 +30,8 @@ export declare function createSpanContext(options?: {
  *
  * The trace ID and the trace flags both carry over: dropping the flags is
  * what makes a parent-based sampler discard every child of a sampled trace.
+ * A parent with an invalid trace or span ID is not joined: the result is the
+ * root of a fresh trace.
  */
 export declare function createChildSpanContext(parent: SpanContext, overrides?: {
     readonly traceFlags?: number;

package/dist/tracing/span/spanContext.type.js

@@ -4,14 +4,39 @@
  * Factory for creating span context identifiers.
  */
 import { TraceFlags } from "../../types.js";
-import { generateSpanId, generateTraceId } from "../../internal/index.js";
-/** Creates a new span context with cryptographically random IDs. */
+import { generateSpanId, generateTraceId, isValidSpanId, isValidTraceId, } from "../../internal/index.js";
+/**
+ * True when `context` carries a valid W3C trace ID and span ID.
+ *
+ * A context that fails this check must never be adopted as a parent: its IDs
+ * usually come from an inbound header and would otherwise flow verbatim into
+ * every span, log record and exporter.
+ */
+export function isValidSpanContext(context) {
+    if (context === undefined || context === null)
+        return false;
+    return (typeof context.traceId === "string" &&
+        typeof context.spanId === "string" &&
+        isValidTraceId(context.traceId) &&
+        isValidSpanId(context.spanId));
+}
+/**
+ * Creates a new span context with cryptographically random IDs.
+ *
+ * Supplied IDs are validated. An invalid `traceId` or `parentSpanId` starts
+ * a fresh trace (new trace ID, no parent) instead of joining a trace the
+ * caller cannot vouch for; an invalid `spanId` is replaced with a new one.
+ */
 export function createSpanContext(options) {
+    const traceOk = options?.traceId === undefined || isValidTraceId(options.traceId);
+    const parentOk = options?.parentSpanId === undefined || isValidSpanId(options.parentSpanId);
+    const joins = traceOk && parentOk;
+    const spanId = options?.spanId;
     return {
-        traceId: options?.traceId ?? generateTraceId(),
-        spanId: options?.spanId ?? generateSpanId(),
-        parentSpanId: options?.parentSpanId,
-        traceFlags: options?.traceFlags ?? TraceFlags.NONE,
+        traceId: (joins ? options?.traceId : undefined) ?? generateTraceId(),
+        spanId: spanId !== undefined && isValidSpanId(spanId) ? spanId : generateSpanId(),
+        parentSpanId: joins ? options?.parentSpanId : undefined,
+        traceFlags: (joins ? options?.traceFlags : undefined) ?? TraceFlags.NONE,
     };
 }
 /**
@@ -19,8 +44,13 @@ export function createSpanContext(options) {
  *
  * The trace ID and the trace flags both carry over: dropping the flags is
  * what makes a parent-based sampler discard every child of a sampled trace.
+ * A parent with an invalid trace or span ID is not joined: the result is the
+ * root of a fresh trace.
  */
 export function createChildSpanContext(parent, overrides) {
+    if (!isValidSpanContext(parent)) {
+        return createSpanContext({ traceFlags: overrides?.traceFlags });
+    }
     return createSpanContext({
         traceId: parent.traceId,
         parentSpanId: parent.spanId,

package/dist/tracing/tracer/index.d.ts

@@ -4,4 +4,5 @@
  * Span creation, sampling, and processor notification.
  */
 export { DefaultTracer, createTracer, type TracerOptions, } from "./tracer.core.js";
+export { withSpan } from "./tracer.active.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/tracing/tracer/index.js

@@ -4,4 +4,5 @@
  * Span creation, sampling, and processor notification.
  */
 export { DefaultTracer, createTracer, } from "./tracer.core.js";
+export { withSpan } from "./tracer.active.js";
 //# sourceMappingURL=index.js.map

package/dist/tracing/tracer/tracer.active.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @zudojs/observability — Active spans
+ *
+ * Runs a callback with a span as the active propagation context, so logs
+ * and child spans created inside it join the span's trace automatically.
+ */
+import type { Span, SpanOptions, Tracer } from "../../types.js";
+/**
+ * Starts a span, runs `fn` with it as the active context, and ends it.
+ *
+ * Inside `fn`, `getCurrentContext()` returns a context carrying the span's
+ * trace and span IDs (plus the request, correlation, user and baggage of
+ * the surrounding context), so log records are correlated with the span and
+ * spans started without an explicit parent become its children. The span
+ * ends when `fn` returns or, for a promise, when it settles; a throw or a
+ * rejection is recorded on the span and re-thrown.
+ */
+export declare function withSpan<T>(tracer: Tracer, name: string, fn: (span: Span) => T, options?: SpanOptions): T;
+//# sourceMappingURL=tracer.active.d.ts.map

package/dist/tracing/tracer/tracer.active.js

@@ -0,0 +1,67 @@
+/**
+ * @zudojs/observability — Active spans
+ *
+ * Runs a callback with a span as the active propagation context, so logs
+ * and child spans created inside it join the span's trace automatically.
+ */
+import { SpanStatus } from "../../types.js";
+import { createPropagationContext, createPropagationManager, getCurrentContext, } from "../../propagation/index.js";
+const manager = createPropagationManager();
+function fail(span, error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    span.recordError(err);
+    span.setStatus(SpanStatus.ERROR, err.message);
+    span.end();
+}
+function isThenable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
+/**
+ * Starts a span, runs `fn` with it as the active context, and ends it.
+ *
+ * Inside `fn`, `getCurrentContext()` returns a context carrying the span's
+ * trace and span IDs (plus the request, correlation, user and baggage of
+ * the surrounding context), so log records are correlated with the span and
+ * spans started without an explicit parent become its children. The span
+ * ends when `fn` returns or, for a promise, when it settles; a throw or a
+ * rejection is recorded on the span and re-thrown.
+ */
+export function withSpan(tracer, name, fn, options) {
+    const span = tracer.startSpan(name, options);
+    const ambient = getCurrentContext();
+    const context = createPropagationContext({
+        requestId: ambient?.requestId,
+        correlationId: ambient?.correlationId,
+        userId: ambient?.userId,
+        service: ambient?.service,
+        baggage: ambient?.baggage,
+        traceId: span.context.traceId,
+        spanId: span.context.spanId,
+        parentSpanId: span.context.parentSpanId,
+        traceFlags: span.context.traceFlags,
+    });
+    return manager.runSync(context, () => {
+        let result;
+        try {
+            result = fn(span);
+        }
+        catch (error) {
+            fail(span, error);
+            throw error;
+        }
+        if (!isThenable(result)) {
+            span.end();
+            return result;
+        }
+        return Promise.resolve(result).then((value) => {
+            span.end();
+            return value;
+        }, (error) => {
+            fail(span, error);
+            throw error;
+        });
+    });
+}
+//# sourceMappingURL=tracer.active.js.map

package/dist/tracing/tracer/tracer.core.d.ts

@@ -43,6 +43,11 @@ export declare class DefaultTracer implements Tracer {
     private readonly onError?;
     constructor(options?: TracerOptions);
     startSpan(name: string, options?: SpanOptions): Span;
+    /**
+     * Starts a span and runs `fn` with it as the active context.
+     * @see withSpan
+     */
+    startActiveSpan<T>(name: string, fn: (span: Span) => T, options?: SpanOptions): T;
     private notifyEnd;
     /** Exports a completed span directly, bypassing the processors. */
     exportSpan(span: ReadableSpan): Promise<void>;

package/dist/tracing/tracer/tracer.core.js

@@ -8,6 +8,8 @@ import { TraceFlags } from "../../types.js";
 import { DefaultSpan } from "../span/span.core.js";
 import { createChildSpanContext, createSpanContext, } from "../span/spanContext.type.js";
 import { AlwaysOnSampler } from "../../sampling/index.js";
+import { resolveSpanParent } from "./tracer.parent.js";
+import { withSpan } from "./tracer.active.js";
 /**
  * Default tracer that creates spans and notifies processors on start/end.
  */
@@ -31,12 +33,12 @@ export class DefaultTracer {
         this.onError = options?.onError;
     }
     startSpan(name, options) {
-        // Build the context first so the sampler can key on the real trace ID,
-        // then stamp the decision into traceFlags so children inherit it.
-        const base = options?.parent
-            ? createChildSpanContext(options.parent)
-            : createSpanContext();
-        const decision = this.sampler.shouldSample(options?.parent, base.traceId);
+        // Join the explicit parent, else the ambient propagation context. Build
+        // the context first so the sampler can key on the real trace ID, then
+        // stamp the decision into traceFlags so children inherit it.
+        const { parent, samplerParent } = resolveSpanParent(options?.parent);
+        const base = parent ? createChildSpanContext(parent) : createSpanContext();
+        const decision = this.sampler.shouldSample(samplerParent, base.traceId);
         const sampled = decision.decision === "RECORD_AND_SAMPLE";
         const recording = decision.decision !== "DO_NOT_RECORD";
         const context = {
@@ -71,6 +73,13 @@ export class DefaultTracer {
         }
         return span;
     }
+    /**
+     * Starts a span and runs `fn` with it as the active context.
+     * @see withSpan
+     */
+    startActiveSpan(name, fn, options) {
+        return withSpan(this, name, fn, options);
+    }
     notifyEnd(readable) {
         for (const processor of this.processors) {
             try {

package/dist/tracing/tracer/tracer.parent.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @zudojs/observability — Tracer parent resolution
+ *
+ * Decides which context a new span joins: the explicit `parent` when it is
+ * valid, otherwise the ambient propagation context, otherwise none.
+ */
+import type { SpanContext } from "../../types.js";
+/** The parent a span joins, and the parent the sampler should consult. */
+export interface ResolvedSpanParent {
+    /** Context the new span becomes a child of; `undefined` starts a trace. */
+    readonly parent?: SpanContext;
+    /**
+     * Context handed to the sampler. `undefined` when no upstream sampling
+     * decision exists, so the root sampler decides — an ambient context
+     * created without trace flags is not a "not sampled" parent.
+     */
+    readonly samplerParent?: SpanContext;
+}
+/**
+ * Resolves the parent for a new span.
+ *
+ * An explicit parent with invalid IDs is never joined (the span starts a
+ * fresh trace). Without an explicit parent, the span joins the active
+ * propagation context so logs and spans written in one request share one
+ * trace ID.
+ */
+export declare function resolveSpanParent(explicit?: SpanContext): ResolvedSpanParent;
+//# sourceMappingURL=tracer.parent.d.ts.map

package/dist/tracing/tracer/tracer.parent.js

@@ -0,0 +1,36 @@
+/**
+ * @zudojs/observability — Tracer parent resolution
+ *
+ * Decides which context a new span joins: the explicit `parent` when it is
+ * valid, otherwise the ambient propagation context, otherwise none.
+ */
+import { getCurrentContext } from "../../propagation/index.js";
+import { isValidSpanContext } from "../span/spanContext.type.js";
+/**
+ * Resolves the parent for a new span.
+ *
+ * An explicit parent with invalid IDs is never joined (the span starts a
+ * fresh trace). Without an explicit parent, the span joins the active
+ * propagation context so logs and spans written in one request share one
+ * trace ID.
+ */
+export function resolveSpanParent(explicit) {
+    if (explicit !== undefined) {
+        return isValidSpanContext(explicit)
+            ? { parent: explicit, samplerParent: explicit }
+            : {};
+    }
+    const ambient = getCurrentContext();
+    if (!ambient || !isValidSpanContext(ambient))
+        return {};
+    const parent = {
+        traceId: ambient.traceId,
+        spanId: ambient.spanId,
+        traceFlags: ambient.traceFlags,
+    };
+    return {
+        parent,
+        samplerParent: ambient.traceFlags === undefined ? undefined : parent,
+    };
+}
+//# sourceMappingURL=tracer.parent.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/observability",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Structured logging, metrics, tracing, context propagation, and exporters for Zudojs applications.",
   "license": "MIT",
   "author": {
@@ -26,7 +26,7 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.1"
+    "@zudojs/errors": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",