@zudojs/observability 0.1.0 → 1.0.0

package/dist/exporter/exporter.console.js

@@ -2,14 +2,73 @@
  * @zudojs/observability — Console Exporter
  *
  * Exports telemetry to the console for development and debugging.
+ *
+ * Serialization is defensive, because everything here is fed values the API
+ * declares as `unknown`: circular structures, BigInts and throwing getters all
+ * reach `JSON.stringify` eventually, and an exporter that throws inside the
+ * logging path takes the process with it.
  */
+import { LogLevel } from "../types.js";
+/**
+ * JSON.stringify that cannot throw.
+ *
+ * Cycles become `"[Circular]"`, BigInts become their decimal string, and a
+ * value that defeats serialization entirely falls back to `String(value)`.
+ *
+ * "Cycle" means an ancestor, not "seen before". A `WeakSet` of every object
+ * already visited also matches a value referenced twice from different
+ * branches — `{ user, actor: user }` — and silently replaced the second copy
+ * with `[Circular]`, losing real telemetry that was never circular. The
+ * replacer's `this` is the object currently being serialized, which is what
+ * lets the ancestor chain be tracked exactly.
+ */
+export function safeStringify(value, pretty = false) {
+    const ancestors = [];
+    try {
+        return (JSON.stringify(value, function replacer(_key, entry) {
+            // Unwind to the holder of the value being visited.
+            while (ancestors.length > 0 &&
+                ancestors[ancestors.length - 1] !== this) {
+                ancestors.pop();
+            }
+            if (typeof entry === "bigint")
+                return entry.toString();
+            if (typeof entry === "function")
+                return "[Function]";
+            if (typeof entry === "symbol")
+                return entry.toString();
+            if (entry instanceof Error) {
+                return {
+                    name: entry.name,
+                    message: entry.message,
+                    stack: entry.stack,
+                };
+            }
+            if (typeof entry === "object" && entry !== null) {
+                if (ancestors.includes(entry))
+                    return "[Circular]";
+                ancestors.push(entry);
+            }
+            return entry;
+        }, pretty ? 2 : undefined) ?? String(value));
+    }
+    catch {
+        return String(value);
+    }
+}
 /**
  * Exports completed spans to the console.
  */
 export class ConsoleSpanExporter {
+    pretty;
+    out;
+    constructor(options) {
+        this.pretty = options?.pretty ?? false;
+        this.out = options?.console ?? console;
+    }
     async export(spans) {
         for (const span of spans) {
-            console.log(JSON.stringify({
+            this.out.log(safeStringify({
                 type: "span",
                 name: span.name,
                 traceId: span.context.traceId,
@@ -17,13 +76,20 @@ export class ConsoleSpanExporter {
                 parentSpanId: span.context.parentSpanId,
                 kind: span.kind,
                 status: span.status,
-                duration: `${span.duration}ms`,
+                statusMessage: span.statusMessage,
+                durationMs: span.duration,
                 startTime: span.startTime.toISOString(),
                 endTime: span.endTime.toISOString(),
                 attributes: span.attributes,
                 events: span.events,
                 resource: span.resource,
-            }, null, 2));
+                ...(span.droppedAttributes > 0
+                    ? { droppedAttributes: span.droppedAttributes }
+                    : {}),
+                ...(span.droppedEvents > 0
+                    ? { droppedEvents: span.droppedEvents }
+                    : {}),
+            }, this.pretty));
         }
     }
     async shutdown() {
@@ -34,25 +100,30 @@ export class ConsoleSpanExporter {
  * Exports log records to the console.
  */
 export class ConsoleLogExporter {
+    pretty;
+    out;
+    constructor(options) {
+        this.pretty = options?.pretty ?? false;
+        this.out = options?.console ?? console;
+    }
     async export(records) {
         for (const record of records) {
-            const output = {
+            const line = safeStringify({
                 timestamp: record.timestamp.toISOString(),
                 level: record.levelName,
                 logger: record.loggerName,
                 message: record.message,
+                ...(record.traceId ? { traceId: record.traceId } : {}),
+                ...(record.spanId ? { spanId: record.spanId } : {}),
                 ...(record.context ? { context: record.context } : {}),
                 ...(record.error ? { error: record.error } : {}),
-            };
-            if (record.level >= 4) {
-                console.error(JSON.stringify(output, null, 2));
-            }
-            else if (record.level >= 3) {
-                console.warn(JSON.stringify(output, null, 2));
-            }
-            else {
-                console.log(JSON.stringify(output, null, 2));
-            }
+            }, this.pretty);
+            if (record.level >= LogLevel.ERROR)
+                this.out.error(line);
+            else if (record.level >= LogLevel.WARN)
+                this.out.warn(line);
+            else
+                this.out.log(line);
         }
     }
     async shutdown() {
@@ -63,32 +134,48 @@ export class ConsoleLogExporter {
  * Exports metric snapshots to the console.
  */
 export class ConsoleMetricExporter {
+    pretty;
+    out;
+    constructor(options) {
+        this.pretty = options?.pretty ?? false;
+        this.out = options?.console ?? console;
+    }
     async export(snapshots) {
         for (const snapshot of snapshots) {
-            console.log(JSON.stringify({
+            this.out.log(safeStringify({
                 type: "metric",
                 metricType: snapshot.type,
                 name: snapshot.name,
                 value: snapshot.value,
                 labels: snapshot.labels,
-                timestamp: new Date().toISOString(),
-            }, null, 2));
+                timestamp: snapshot.timestamp.toISOString(),
+            }, this.pretty));
         }
     }
     async shutdown() {
         // No resources to clean up
     }
 }
+/** A log exporter that discards everything. */
+export const noopLogExporter = {
+    export: async () => { },
+    shutdown: async () => { },
+};
+/** A metric exporter that discards everything. */
+export const noopMetricExporter = {
+    export: async () => { },
+    shutdown: async () => { },
+};
 /** Creates a console span exporter. */
-export function createConsoleSpanExporter() {
-    return new ConsoleSpanExporter();
+export function createConsoleSpanExporter(options) {
+    return new ConsoleSpanExporter(options);
 }
 /** Creates a console log exporter. */
-export function createConsoleLogExporter() {
-    return new ConsoleLogExporter();
+export function createConsoleLogExporter(options) {
+    return new ConsoleLogExporter(options);
 }
 /** Creates a console metric exporter. */
-export function createConsoleMetricExporter() {
-    return new ConsoleMetricExporter();
+export function createConsoleMetricExporter(options) {
+    return new ConsoleMetricExporter(options);
 }
 //# sourceMappingURL=exporter.console.js.map

package/dist/exporter/index.d.ts

@@ -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, type ConsoleExporterOptions, type ConsoleLike, } from "./exporter.console.js";
 //# sourceMappingURL=index.d.ts.map

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