@zudojs/observability 0.0.1 → 1.0.0

package/dist/exporter/index.js

@@ -1,7 +1,7 @@
 /**
  * @zudojs/observability — Exporters
  *
- * Console exporters for spans, logs, and metrics.
+ * Console exporters for spans, logs, and metrics, plus no-op exporters.
  */
-export { ConsoleSpanExporter, ConsoleLogExporter, ConsoleMetricExporter, createConsoleSpanExporter, createConsoleLogExporter, createConsoleMetricExporter, } from "./exporter.console.js";
+export { ConsoleSpanExporter, ConsoleLogExporter, ConsoleMetricExporter, createConsoleSpanExporter, createConsoleLogExporter, createConsoleMetricExporter, noopLogExporter, noopMetricExporter, safeStringify, } from "./exporter.console.js";
 //# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -16,27 +16,33 @@
  * const obs = createObservability({
  *   serviceName: "my-api",
  *   logLevel: LogLevel.INFO,
+ *   redaction: {},                 // opt in to redaction
+ *   sampler: createProbabilitySampler(0.1),
  * });
  *
  * obs.logger.info("Server started", { port: 3000 });
  * obs.metrics.counter("http.requests.total").increment();
  * const span = obs.tracer.startSpan("handle-request");
  * span.end();
+ *
+ * await obs.shutdown();
  * ```
  *
  * @packageDocumentation
  */
-export { LogLevel, SpanStatus, SpanKind, type LogLevelName, type LogRecord, type Logger, type LoggerOptions, type LogTransport, type PropagationContext, type PropagationContextOptions, type PropagationManager, type Counter, type Gauge, type Histogram, type MetricsRegistry, type MetricSnapshot, type Span, type SpanContext, type SpanEvent, type SpanOptions, type Tracer, type ReadableSpan, type SpanExporter, type LogExporter, type MetricExporter, type SpanProcessor, type SamplingResult, type Sampler, type RedactionConfig, type Observability, type ObservabilityConfig, } from "./types.js";
-export { logLevelToName, logLevelFromName, shouldLog, getLogLevelNames, } from "./logLevel/index.js";
-export { createLogRecord, createErrorLogRecord } from "./logRecord/index.js";
+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 { createLogRecord, createErrorLogRecord, serializeError, } from "./logRecord/index.js";
 export { StructuredLogger, createStructuredLogger } from "./logger/index.js";
-export { createPropagationContext, derivePropagationContext, getCurrentContext, AsyncPropagationManager, createPropagationManager, } from "./propagation/index.js";
-export { DefaultCounter, createCounter, DefaultGauge, createGauge, DefaultHistogram, createHistogram, DefaultMetricsRegistry, createMetricsRegistry, } from "./metrics/index.js";
-export { DefaultSpan, createSpan, createSpanContext, createChildSpanContext, DefaultTracer, createTracer, } from "./tracing/index.js";
-export { AlwaysOnSampler, AlwaysOffSampler, ProbabilitySampler, ParentBasedSampler, createAlwaysOnSampler, createAlwaysOffSampler, createProbabilitySampler, createParentBasedSampler, } from "./sampling/index.js";
-export { ConsoleSpanExporter, ConsoleLogExporter, ConsoleMetricExporter, createConsoleSpanExporter, createConsoleLogExporter, createConsoleMetricExporter, } from "./exporter/index.js";
-export { BatchSpanProcessor, createBatchSpanProcessor, } from "./processor/index.js";
-export { createRedactor, redactObject, isSensitiveField, } from "./redaction/index.js";
-export { NoopObservability, createNoopObservability, noopLogger, noopCounter, noopGauge, noopHistogram, noopMetricsRegistry, noopSpan, noopTracer, noopPropagationManager, } from "./noop/index.js";
+export { createPropagationContext, derivePropagationContext, getCurrentContext, requireCurrentContext, AsyncPropagationManager, createPropagationManager, } 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 { 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";
+export { createRedactor, createStructureRedactor, redactObject, redactValue, isSensitiveField, DEFAULT_SENSITIVE_FIELDS, CIRCULAR_MARKER, MAX_DEPTH_MARKER, } from "./redaction/index.js";
+export { NoopObservability, createNoopObservability, noopLogger, noopCounter, noopGauge, noopHistogram, noopMetricsRegistry, noopSpan, noopTracer, noopPropagationManager, INVALID_PROPAGATION_CONTEXT, } from "./noop/index.js";
 export { DefaultObservability, createObservability, } from "./observability/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -16,40 +16,48 @@
  * const obs = createObservability({
  *   serviceName: "my-api",
  *   logLevel: LogLevel.INFO,
+ *   redaction: {},                 // opt in to redaction
+ *   sampler: createProbabilitySampler(0.1),
  * });
  *
  * obs.logger.info("Server started", { port: 3000 });
  * obs.metrics.counter("http.requests.total").increment();
  * const span = obs.tracer.startSpan("handle-request");
  * span.end();
+ *
+ * await obs.shutdown();
  * ```
  *
  * @packageDocumentation
  */
 /* ─── Core Types ────────────────────────────────────────────────────────── */
-export { LogLevel, SpanStatus, SpanKind, } from "./types.js";
+export { LogLevel, SpanStatus, SpanKind, TraceFlags, } from "./types.js";
+/* ─── Errors ────────────────────────────────────────────────────────────── */
+export { ObservabilityError, ExporterError, ObservabilityConfigError, MetricValueError, isObservabilityError, } from "./errors/index.js";
+/* ─── Identifiers ───────────────────────────────────────────────────────── */
+export { generateTraceId, generateSpanId, isValidTraceId, isValidSpanId, } from "./internal/index.js";
 /* ─── Log Level ─────────────────────────────────────────────────────────── */
-export { logLevelToName, logLevelFromName, shouldLog, getLogLevelNames, } from "./logLevel/index.js";
+export { logLevelToName, logLevelFromName, parseLogLevel, shouldLog, getLogLevelNames, } from "./logLevel/index.js";
 /* ─── Log Record ────────────────────────────────────────────────────────── */
-export { createLogRecord, createErrorLogRecord } from "./logRecord/index.js";
+export { createLogRecord, createErrorLogRecord, serializeError, } from "./logRecord/index.js";
 /* ─── Logger ────────────────────────────────────────────────────────────── */
 export { StructuredLogger, createStructuredLogger } from "./logger/index.js";
 /* ─── Propagation ───────────────────────────────────────────────────────── */
-export { createPropagationContext, derivePropagationContext, getCurrentContext, AsyncPropagationManager, createPropagationManager, } from "./propagation/index.js";
+export { createPropagationContext, derivePropagationContext, getCurrentContext, requireCurrentContext, AsyncPropagationManager, createPropagationManager, } from "./propagation/index.js";
 /* ─── Metrics ───────────────────────────────────────────────────────────── */
-export { DefaultCounter, createCounter, DefaultGauge, createGauge, DefaultHistogram, createHistogram, DefaultMetricsRegistry, createMetricsRegistry, } from "./metrics/index.js";
+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, DefaultTracer, createTracer, } from "./tracing/index.js";
+export { DefaultSpan, createSpan, createSpanContext, createChildSpanContext, isSampledContext, DefaultTracer, createTracer, } from "./tracing/index.js";
 /* ─── Sampling ──────────────────────────────────────────────────────────── */
-export { AlwaysOnSampler, AlwaysOffSampler, ProbabilitySampler, ParentBasedSampler, createAlwaysOnSampler, createAlwaysOffSampler, createProbabilitySampler, createParentBasedSampler, } from "./sampling/index.js";
+export { AlwaysOnSampler, AlwaysOffSampler, ProbabilitySampler, ParentBasedSampler, createAlwaysOnSampler, createAlwaysOffSampler, createProbabilitySampler, createParentBasedSampler, isSampled, isRecording, } from "./sampling/index.js";
 /* ─── Exporters ─────────────────────────────────────────────────────────── */
-export { ConsoleSpanExporter, ConsoleLogExporter, ConsoleMetricExporter, createConsoleSpanExporter, createConsoleLogExporter, createConsoleMetricExporter, } from "./exporter/index.js";
-/* ─── Processor ─────────────────────────────────────────────────────────── */
-export { BatchSpanProcessor, createBatchSpanProcessor, } from "./processor/index.js";
+export { ConsoleSpanExporter, ConsoleLogExporter, ConsoleMetricExporter, createConsoleSpanExporter, createConsoleLogExporter, createConsoleMetricExporter, noopLogExporter, noopMetricExporter, safeStringify, } from "./exporter/index.js";
+/* ─── Processors ────────────────────────────────────────────────────────── */
+export { BatchSpanProcessor, createBatchSpanProcessor, SimpleSpanProcessor, createSimpleSpanProcessor, BatchLogProcessor, createBatchLogProcessor, noopSpanExporter, } from "./processor/index.js";
 /* ─── Redaction ─────────────────────────────────────────────────────────── */
-export { createRedactor, redactObject, isSensitiveField, } from "./redaction/index.js";
+export { createRedactor, createStructureRedactor, redactObject, redactValue, isSensitiveField, DEFAULT_SENSITIVE_FIELDS, CIRCULAR_MARKER, MAX_DEPTH_MARKER, } from "./redaction/index.js";
 /* ─── Noop ──────────────────────────────────────────────────────────────── */
-export { NoopObservability, createNoopObservability, noopLogger, noopCounter, noopGauge, noopHistogram, noopMetricsRegistry, noopSpan, noopTracer, noopPropagationManager, } from "./noop/index.js";
+export { NoopObservability, createNoopObservability, noopLogger, noopCounter, noopGauge, noopHistogram, noopMetricsRegistry, noopSpan, noopTracer, noopPropagationManager, INVALID_PROPAGATION_CONTEXT, } from "./noop/index.js";
 /* ─── Observability Facade ──────────────────────────────────────────────── */
 export { DefaultObservability, createObservability, } from "./observability/index.js";
 //# sourceMappingURL=index.js.map

package/dist/internal/ids.core.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @zudojs/observability — Identifier generation
+ *
+ * One generator, used by both the propagation context and the span context.
+ * IDs come from `node:crypto`, not `Math.random()`: trace, span, request and
+ * correlation IDs routinely end up in idempotency keys, log correlation and
+ * access decisions, and a predictable stream of them is a liability that a
+ * CSPRNG costs nothing to avoid.
+ */
+/** Bytes in a W3C trace ID. */
+export declare const TRACE_ID_BYTES = 16;
+/** Bytes in a W3C span ID. */
+export declare const SPAN_ID_BYTES = 8;
+/** Generates a cryptographically random lowercase hex ID. */
+export declare function generateHexId(byteLength: number): string;
+/** Generates a 16-byte trace ID, never the all-zero (invalid) value. */
+export declare function generateTraceId(): string;
+/** Generates an 8-byte span ID, never the all-zero (invalid) value. */
+export declare function generateSpanId(): string;
+/** True when `id` is valid lowercase hex of the expected width and non-zero. */
+export declare function isValidId(id: string, byteLength: number): boolean;
+/** True when `traceId` is a valid W3C trace ID. */
+export declare function isValidTraceId(traceId: string): boolean;
+/** True when `spanId` is a valid W3C span ID. */
+export declare function isValidSpanId(spanId: string): boolean;
+//# sourceMappingURL=ids.core.d.ts.map

package/dist/internal/ids.core.js

@@ -0,0 +1,51 @@
+/**
+ * @zudojs/observability — Identifier generation
+ *
+ * One generator, used by both the propagation context and the span context.
+ * IDs come from `node:crypto`, not `Math.random()`: trace, span, request and
+ * correlation IDs routinely end up in idempotency keys, log correlation and
+ * access decisions, and a predictable stream of them is a liability that a
+ * CSPRNG costs nothing to avoid.
+ */
+import { randomBytes } from "node:crypto";
+/** Bytes in a W3C trace ID. */
+export const TRACE_ID_BYTES = 16;
+/** Bytes in a W3C span ID. */
+export const SPAN_ID_BYTES = 8;
+const INVALID_TRACE_ID = "0".repeat(TRACE_ID_BYTES * 2);
+const INVALID_SPAN_ID = "0".repeat(SPAN_ID_BYTES * 2);
+/** Generates a cryptographically random lowercase hex ID. */
+export function generateHexId(byteLength) {
+    return randomBytes(byteLength).toString("hex");
+}
+/** Generates a 16-byte trace ID, never the all-zero (invalid) value. */
+export function generateTraceId() {
+    let id = generateHexId(TRACE_ID_BYTES);
+    while (id === INVALID_TRACE_ID)
+        id = generateHexId(TRACE_ID_BYTES);
+    return id;
+}
+/** Generates an 8-byte span ID, never the all-zero (invalid) value. */
+export function generateSpanId() {
+    let id = generateHexId(SPAN_ID_BYTES);
+    while (id === INVALID_SPAN_ID)
+        id = generateHexId(SPAN_ID_BYTES);
+    return id;
+}
+/** True when `id` is valid lowercase hex of the expected width and non-zero. */
+export function isValidId(id, byteLength) {
+    if (id.length !== byteLength * 2)
+        return false;
+    if (!/^[0-9a-f]+$/.test(id))
+        return false;
+    return !/^0+$/.test(id);
+}
+/** True when `traceId` is a valid W3C trace ID. */
+export function isValidTraceId(traceId) {
+    return isValidId(traceId, TRACE_ID_BYTES);
+}
+/** True when `spanId` is a valid W3C span ID. */
+export function isValidSpanId(spanId) {
+    return isValidId(spanId, SPAN_ID_BYTES);
+}
+//# sourceMappingURL=ids.core.js.map

package/dist/internal/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @zudojs/observability — Internal helpers shared across modules.
+ */
+export { generateHexId, generateTraceId, generateSpanId, isValidId, isValidTraceId, isValidSpanId, TRACE_ID_BYTES, SPAN_ID_BYTES, } from "./ids.core.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/internal/index.js

@@ -0,0 +1,5 @@
+/**
+ * @zudojs/observability — Internal helpers shared across modules.
+ */
+export { generateHexId, generateTraceId, generateSpanId, isValidId, isValidTraceId, isValidSpanId, TRACE_ID_BYTES, SPAN_ID_BYTES, } from "./ids.core.js";
+//# sourceMappingURL=index.js.map

package/dist/logLevel/index.d.ts

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

package/dist/logLevel/index.js

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

package/dist/logLevel/logLevel.type.d.ts

@@ -1,14 +1,20 @@
 /**
  * @zudojs/observability — Log Level
  *
- * Utility functions for converting between log levels and names,
- * and checking whether a message should be logged.
+ * The single source of truth for the level↔name mapping, and the filtering
+ * predicate every logger uses.
  */
 import { LogLevel, type LogLevelName } from "../types.js";
 /** Converts a numeric level to its name. */
 export declare function logLevelToName(level: LogLevel): LogLevelName;
 /** Converts a level name to its numeric value. */
 export declare function logLevelFromName(name: LogLevelName): LogLevel;
+/**
+ * Parses an arbitrary string — an environment variable, a config file entry —
+ * into a level, returning `undefined` when it names no level. Use this at a
+ * trust boundary; {@link logLevelFromName} assumes the name is already valid.
+ */
+export declare function parseLogLevel(value: string): LogLevel | undefined;
 /** Returns true if a message at `messageLevel` should pass the `threshold`. */
 export declare function shouldLog(threshold: LogLevel, messageLevel: LogLevel): boolean;
 /** Returns all log level names. */

package/dist/logLevel/logLevel.type.js

@@ -1,38 +1,45 @@
 /**
  * @zudojs/observability — Log Level
  *
- * Utility functions for converting between log levels and names,
- * and checking whether a message should be logged.
+ * The single source of truth for the level↔name mapping, and the filtering
+ * predicate every logger uses.
  */
 import { LogLevel } from "../types.js";
-const LEVEL_NAMES = [
-    "trace",
-    "debug",
-    "info",
-    "warn",
-    "error",
-    "fatal",
-    "off",
-];
-const NAME_TO_LEVEL = new Map([
-    ["trace", LogLevel.TRACE],
-    ["debug", LogLevel.DEBUG],
-    ["info", LogLevel.INFO],
-    ["warn", LogLevel.WARN],
-    ["error", LogLevel.ERROR],
-    ["fatal", LogLevel.FATAL],
-    ["off", LogLevel.OFF],
+const LEVEL_TO_NAME = new Map([
+    [LogLevel.TRACE, "trace"],
+    [LogLevel.DEBUG, "debug"],
+    [LogLevel.INFO, "info"],
+    [LogLevel.WARN, "warn"],
+    [LogLevel.ERROR, "error"],
+    [LogLevel.FATAL, "fatal"],
+    [LogLevel.OFF, "off"],
+]);
+const NAME_TO_LEVEL = new Map([...LEVEL_TO_NAME].map(([level, name]) => [name, level]));
+// Frozen: this array is handed straight to callers, and an unfrozen module
+// singleton is one `push` away from corrupting every later reader.
+const LEVEL_NAMES = Object.freeze([
+    ...LEVEL_TO_NAME.values(),
 ]);
 /** Converts a numeric level to its name. */
 export function logLevelToName(level) {
-    return LEVEL_NAMES[level] ?? "off";
+    return LEVEL_TO_NAME.get(level) ?? "off";
 }
 /** Converts a level name to its numeric value. */
 export function logLevelFromName(name) {
     return NAME_TO_LEVEL.get(name) ?? LogLevel.OFF;
 }
+/**
+ * Parses an arbitrary string — an environment variable, a config file entry —
+ * into a level, returning `undefined` when it names no level. Use this at a
+ * trust boundary; {@link logLevelFromName} assumes the name is already valid.
+ */
+export function parseLogLevel(value) {
+    return NAME_TO_LEVEL.get(value.trim().toLowerCase());
+}
 /** Returns true if a message at `messageLevel` should pass the `threshold`. */
 export function shouldLog(threshold, messageLevel) {
+    if (threshold >= LogLevel.OFF)
+        return false;
     return messageLevel >= threshold;
 }
 /** Returns all log level names. */

package/dist/logRecord/index.d.ts

@@ -3,5 +3,5 @@
  *
  * Structured log record creation and error log records.
  */
-export { createLogRecord, createErrorLogRecord } from "./logRecord.core.js";
+export { createLogRecord, createErrorLogRecord, serializeError, } from "./logRecord.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/logRecord/index.js

@@ -3,5 +3,5 @@
  *
  * Structured log record creation and error log records.
  */
-export { createLogRecord, createErrorLogRecord } from "./logRecord.core.js";
+export { createLogRecord, createErrorLogRecord, serializeError, } from "./logRecord.core.js";
 //# sourceMappingURL=index.js.map

package/dist/logRecord/logRecord.core.d.ts

@@ -3,16 +3,28 @@
  *
  * Factory functions for creating structured log records.
  */
-import type { LogRecord } from "../types.js";
+import type { LogRecord, LogRecordError } from "../types.js";
 import { LogLevel } from "../types.js";
+/**
+ * Serializes a thrown value into something a JSON transport can carry.
+ *
+ * `Error`'s own fields are non-enumerable, so an error placed in a log
+ * context stringifies to `{}` — this is what turns it back into data.
+ * `cause` chains are followed, with a depth cap so a self-referential cause
+ * cannot recurse forever.
+ */
+export declare function serializeError(error: unknown, depth?: number): LogRecordError;
 /** Creates a structured log record. */
 export declare function createLogRecord(options: {
     readonly level: LogLevel;
     readonly message: string;
     readonly loggerName: string;
     readonly context?: Record<string, unknown>;
-    readonly error?: Error;
+    readonly error?: unknown;
+    readonly traceId?: string;
+    readonly spanId?: string;
+    readonly timestamp?: Date;
 }): LogRecord;
 /** Creates a log record for an error. */
-export declare function createErrorLogRecord(error: Error, level: LogLevel, loggerName: string): LogRecord;
+export declare function createErrorLogRecord(error: unknown, level: LogLevel, loggerName: string, context?: Record<string, unknown>): LogRecord;
 //# sourceMappingURL=logRecord.core.d.ts.map

package/dist/logRecord/logRecord.core.js

@@ -4,46 +4,68 @@
  * Factory functions for creating structured log records.
  */
 import { LogLevel } from "../types.js";
+import { logLevelToName } from "../logLevel/index.js";
+/**
+ * Serializes a thrown value into something a JSON transport can carry.
+ *
+ * `Error`'s own fields are non-enumerable, so an error placed in a log
+ * context stringifies to `{}` — this is what turns it back into data.
+ * `cause` chains are followed, with a depth cap so a self-referential cause
+ * cannot recurse forever.
+ */
+export function serializeError(error, depth = 0) {
+    if (error instanceof Error) {
+        const cause = error.cause !== undefined && depth < 4
+            ? serializeError(error.cause, depth + 1)
+            : undefined;
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+            cause,
+        };
+    }
+    if (typeof error === "object" && error !== null) {
+        const record = error;
+        const name = typeof record["name"] === "string" ? record["name"] : "Error";
+        const message = typeof record["message"] === "string"
+            ? record["message"]
+            : safeStringify(error);
+        return { name, message };
+    }
+    return { name: "Error", message: String(error) };
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
 /** Creates a structured log record. */
 export function createLogRecord(options) {
-    const error = options.error
-        ? {
-            name: options.error.name,
-            message: options.error.message,
-            stack: options.error.stack,
-            cause: options.error.cause,
-        }
-        : undefined;
     return {
         level: options.level,
-        levelName: logLevelToNameInternal(options.level),
+        levelName: logLevelToName(options.level),
         message: options.message,
-        timestamp: new Date(),
+        timestamp: options.timestamp ?? new Date(),
         loggerName: options.loggerName,
         context: options.context,
-        error,
+        error: options.error === undefined ? undefined : serializeError(options.error),
+        traceId: options.traceId,
+        spanId: options.spanId,
     };
 }
 /** Creates a log record for an error. */
-export function createErrorLogRecord(error, level, loggerName) {
+export function createErrorLogRecord(error, level, loggerName, context) {
+    const serialized = serializeError(error);
     return createLogRecord({
         level,
-        message: error.message,
+        message: serialized.message,
         loggerName,
-        context: { stack: error.stack },
+        context,
         error,
     });
 }
-function logLevelToNameInternal(level) {
-    const names = {
-        [LogLevel.TRACE]: "trace",
-        [LogLevel.DEBUG]: "debug",
-        [LogLevel.INFO]: "info",
-        [LogLevel.WARN]: "warn",
-        [LogLevel.ERROR]: "error",
-        [LogLevel.FATAL]: "fatal",
-        [LogLevel.OFF]: "off",
-    };
-    return names[level] ?? "off";
-}
 //# sourceMappingURL=logRecord.core.js.map

package/dist/logger/logger.core.d.ts

@@ -2,26 +2,34 @@
  * @zudojs/observability — Logger Core
  *
  * Structured logger implementation with level filtering, transport support,
- * child loggers, and persistent context.
+ * child loggers, persistent context, trace correlation and redaction.
  */
 import type { Logger, LoggerOptions } from "../types.js";
 import { LogLevel } from "../types.js";
 /**
  * Core structured logger with level filtering, child loggers,
  * persistent context, and transport support.
+ *
+ * Every record is stamped with the ambient `traceId`/`spanId` when a
+ * propagation context is active, so logs and traces line up without the
+ * caller threading IDs through by hand.
  */
 export declare class StructuredLogger implements Logger {
     readonly name: string;
-    readonly level: LogLevel;
+    private currentLevel;
     private readonly context;
     private readonly transport;
+    private readonly correlate;
+    private readonly redact?;
     constructor(options: LoggerOptions);
-    trace(message: string, context?: Record<string, unknown>): void;
-    debug(message: string, context?: Record<string, unknown>): void;
-    info(message: string, context?: Record<string, unknown>): void;
-    warn(message: string, context?: Record<string, unknown>): void;
-    error(message: string, context?: Record<string, unknown>): void;
-    fatal(message: string, context?: Record<string, unknown>): void;
+    get level(): LogLevel;
+    setLevel(level: LogLevel): void;
+    trace(message: string, context?: Record<string, unknown>, error?: unknown): void;
+    debug(message: string, context?: Record<string, unknown>, error?: unknown): void;
+    info(message: string, context?: Record<string, unknown>, error?: unknown): void;
+    warn(message: string, context?: Record<string, unknown>, error?: unknown): void;
+    error(message: string, context?: Record<string, unknown>, error?: unknown): void;
+    fatal(message: string, context?: Record<string, unknown>, error?: unknown): void;
     child(name: string, context?: Record<string, unknown>): Logger;
     isLevelEnabled(level: LogLevel): boolean;
     flush(): Promise<void>;

package/dist/logger/logger.core.js

@@ -2,11 +2,12 @@
  * @zudojs/observability — Logger Core
  *
  * Structured logger implementation with level filtering, transport support,
- * child loggers, and persistent context.
+ * child loggers, persistent context, trace correlation and redaction.
  */
 import { LogLevel } from "../types.js";
-import { shouldLog, logLevelToName } from "../logLevel/index.js";
+import { shouldLog } from "../logLevel/index.js";
 import { createLogRecord } from "../logRecord/index.js";
+import { getCurrentContext } from "../propagation/index.js";
 /** Default no-op transport that discards all records. */
 const noopTransport = {
     name: "noop",
@@ -15,63 +16,93 @@ const noopTransport = {
 /**
  * Core structured logger with level filtering, child loggers,
  * persistent context, and transport support.
+ *
+ * Every record is stamped with the ambient `traceId`/`spanId` when a
+ * propagation context is active, so logs and traces line up without the
+ * caller threading IDs through by hand.
  */
 export class StructuredLogger {
     name;
-    level;
+    currentLevel;
     context;
     transport;
+    correlate;
+    redact;
     constructor(options) {
         this.name = options.name;
-        this.level = options.level ?? LogLevel.INFO;
+        this.currentLevel = options.level ?? LogLevel.INFO;
         this.context = { ...(options.context ?? {}) };
         this.transport = options.transport ?? noopTransport;
+        this.correlate = options.correlate ?? true;
+        this.redact = options.redact;
+    }
+    get level() {
+        return this.currentLevel;
+    }
+    setLevel(level) {
+        this.currentLevel = level;
     }
-    trace(message, context) {
-        this.log(LogLevel.TRACE, message, context);
+    trace(message, context, error) {
+        this.log(LogLevel.TRACE, message, context, error);
     }
-    debug(message, context) {
-        this.log(LogLevel.DEBUG, message, context);
+    debug(message, context, error) {
+        this.log(LogLevel.DEBUG, message, context, error);
     }
-    info(message, context) {
-        this.log(LogLevel.INFO, message, context);
+    info(message, context, error) {
+        this.log(LogLevel.INFO, message, context, error);
     }
-    warn(message, context) {
-        this.log(LogLevel.WARN, message, context);
+    warn(message, context, error) {
+        this.log(LogLevel.WARN, message, context, error);
     }
-    error(message, context) {
-        this.log(LogLevel.ERROR, message, context);
+    error(message, context, error) {
+        this.log(LogLevel.ERROR, message, context, error);
     }
-    fatal(message, context) {
-        this.log(LogLevel.FATAL, message, context);
+    fatal(message, context, error) {
+        this.log(LogLevel.FATAL, message, context, error);
     }
     child(name, context) {
         const childName = `${this.name}.${name}`;
         const childContext = { ...this.context, ...(context ?? {}) };
         return new StructuredLogger({
             name: childName,
-            level: this.level,
+            level: this.currentLevel,
             context: childContext,
             transport: this.transport,
+            correlate: this.correlate,
+            redact: this.redact,
         });
     }
     isLevelEnabled(level) {
-        return shouldLog(this.level, level);
+        return shouldLog(this.currentLevel, level);
     }
     async flush() {
-        // Transport-specific flush; default is no-op
+        await this.transport.flush?.();
     }
-    log(level, message, context) {
+    log(level, message, context, error) {
         if (!this.isLevelEnabled(level))
             return;
-        const mergedContext = { ...this.context, ...(context ?? {}) };
+        const merged = { ...this.context, ...(context ?? {}) };
+        const redacted = this.redact ? this.redact(merged) : merged;
+        const propagation = this.correlate ? getCurrentContext() : undefined;
         const record = createLogRecord({
             level,
             message,
             loggerName: this.name,
-            context: Object.keys(mergedContext).length > 0 ? mergedContext : undefined,
+            context: Object.keys(redacted).length > 0 ? redacted : undefined,
+            error,
+            traceId: propagation?.traceId,
+            spanId: propagation?.spanId,
         });
-        this.transport.write(record);
+        // A transport must never take the caller down with it. A failing sink is
+        // reported through the transport's own channel, not raised here.
+        try {
+            const written = this.transport.write(record);
+            if (written instanceof Promise)
+                written.catch(() => { });
+        }
+        catch {
+            // Intentionally swallowed: logging is not allowed to throw.
+        }
     }
 }
 /** Creates a structured logger. */