@zudojs/observability 0.0.1 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @zudojs/observability
 
-Structured logging, metrics, tracing, context propagation, and exporters for Zudojs applications.
+Structured logging, metrics, tracing, context propagation, and telemetry exporters for Zudojs applications.
 
 ## Installation
 
@@ -10,25 +10,272 @@ npm install @zudojs/observability
 
 ## Quick Start
 
+`createObservability` is the entry point. It wires the logger, the metrics
+registry, the tracer and the propagation manager into one object, and owns
+their shutdown.
+
 ```typescript
-import { createTracer, createMetricsRegistry } from "@zudojs/observability";
+import {
+  createObservability,
+  createProbabilitySampler,
+  LogLevel,
+} from "@zudojs/observability";
+
+const obs = createObservability({
+  serviceName: "checkout-api",
+  serviceVersion: "1.4.0",
+  environment: "production",
+  logLevel: LogLevel.INFO,
+
+  // Opt in to redaction — see "Redaction" below.
+  redaction: {},
+
+  // Sample 10% of traces. The decision is derived from the trace ID, so a
+  // trace is never sampled in half across services.
+  sampler: createProbabilitySampler(0.1),
+
+  // Console exporters are the development default; turn them off in
+  // production and supply real ones.
+  useConsoleExporters: false,
+});
 
-const tracer = createTracer({ service: "api" });
-const metrics = createMetricsRegistry();
+obs.logger.info("server started", { port: 3000 });
+obs.metrics.counter("http.requests.total", { route: "/checkout" }).increment();
 
-const span = tracer.startSpan("handle-request");
-span.setAttribute("http.method", "GET");
-await handleRequest();
+const span = obs.tracer.startSpan("handle-request");
+span.setAttribute("http.method", "POST");
 span.end();
+
+await obs.shutdown(); // drains every buffer, then closes the exporters
+```
+
+## Logging
+
+Records are structured, level-filtered, and stamped with the ambient trace.
+
+```typescript
+obs.logger.info("order placed", { orderId: 42 });
+
+// An Error goes in the third parameter. Putting it in the context would
+// serialize to {} — Error's fields are non-enumerable.
+obs.logger.error("charge failed", { orderId: 42 }, error);
+
+const child = obs.logger.child("payments", { provider: "stripe" });
+child.setLevel(LogLevel.DEBUG); // adjustable at runtime
+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.
+
+## Redaction
+
+Redaction is off unless you configure it, and on once you do. The logger
+applies it to every record before any transport sees it, and the tracer
+applies it to every span attribute and span event attribute before any
+processor or exporter sees it — a `Bearer` token attached to a span is
+redacted the same way one written to a log field is.
+
+```typescript
+const obs = createObservability({
+  serviceName: "api",
+  redaction: {
+    // Defaults cover passwords, tokens, cookies, keys and card numbers.
+    fields: ["password", "token", "ssn"],
+    patterns: [/^x-.*-secret$/i],
+    // "contains" (the default) matches on word boundaries: "userPassword"
+    // and "x-api-key" match, "shippingAddress" and "authorId" do not.
+    matchMode: "contains",
+    replacement: "[REDACTED]",
+  },
+});
+
+obs.logger.info("login", {
+  username: "ada",
+  password: "hunter2", // → "[REDACTED]"
+  headers: [{ authorization: "…" }], // arrays are traversed too
+});
+```
+
+Traversal handles the shapes secrets actually arrive in: arrays, nested
+objects, and cyclic graphs (a request object in a log context becomes
+`[CIRCULAR]` rather than a stack overflow). Class instances — `Error`, `Date`,
+`Map` — are left intact instead of being flattened to `{}`.
+
+`redactObject`, `redactValue` and `createStructureRedactor` are exported for
+use outside the logger.
+
+## Metrics
+
+Counters, gauges and histograms, keyed by name **and** labels.
+
+```typescript
+obs.metrics.counter("jobs.processed", { queue: "email" }).increment();
+obs.metrics.gauge("queue.depth", { queue: "email" }).setValue(17);
+
+const latency = obs.metrics.histogram("http.duration", { route: "/checkout" });
+latency.record(87);
+
+const value = latency.getValue();
+value.p95; // interpolated from the bucket boundaries
+value.mean;
+```
+
+Histograms keep cumulative buckets, so `p50`/`p90`/`p95`/`p99` are real
+answers rather than something you have to reconstruct from count and sum.
+Pass your own boundaries when the unit is not milliseconds.
+
+Values that cannot be aggregated — `NaN`, `Infinity`, a negative counter
+increment — throw a `MetricValueError` rather than being silently dropped.
+
+**Cardinality.** The registry caps the number of distinct series (default
+10,000). A label carrying a user ID is the usual way to blow past that, and
+the cap turns an unbounded memory leak into a reported error. Lower it — or
+set the histogram boundaries used registry-wide — through `metrics`:
+
+```typescript
+const obs = createObservability({
+  serviceName: "api",
+  metrics: { maxSeries: 2_000 },
+  onError: (error, source) => report(error, source), // cardinality is reported here
+});
+```
+
+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.
+
+Metrics are exported by a `PeriodicMetricReader`, which the facade starts for
+you when a `metricExporter` is configured. `metricExportIntervalMs: 0`
+disables the periodic export while still collecting a final snapshot on
+`flush()` and `shutdown()`:
+
+```typescript
+const obs = createObservability({
+  serviceName: "api",
+  metricExporter: myExporter,
+  metricExportIntervalMs: 30_000,
+});
+```
+
+## Tracing
+
+```typescript
+const span = obs.tracer.startSpan("db.query", { kind: SpanKind.CLIENT });
+try {
+  span.setAttribute("db.statement", sql);
+  return await run(sql);
+} catch (error) {
+  span.recordError(error as Error);
+  throw error;
+} finally {
+  span.end();
+}
+```
+
+Spans are capped: 128 attributes, 128 events, 4096-character values by
+default, with the overflow counted in `droppedAttributes` / `droppedEvents`.
+Durations use a monotonic clock, so a clock adjustment cannot produce a
+negative one. `setStatus(status, message)` keeps the message — it is exported
+alongside the status.
+
+Stack traces recorded by `recordError` reach the backend unredacted; set
+`captureStackTraces: false` to omit them.
+
+### Sampling
+
+```typescript
+import {
+  createAlwaysOnSampler,
+  createParentBasedSampler,
+  createProbabilitySampler,
+} from "@zudojs/observability";
+
+createObservability({
+  serviceName: "api",
+  sampler: createParentBasedSampler({ root: createProbabilitySampler(0.05) }),
+});
+```
+
+The decision is stamped into `SpanContext.traceFlags` and inherited by every
+child, which is what keeps a sampled trace whole across services.
+
+## Context propagation
+
+```typescript
+import { createPropagationContext } from "@zudojs/observability";
+
+await obs.propagation.run(createPropagationContext({ requestId }), async () => {
+  obs.logger.info("handling"); // carries traceId, spanId
+  await handle();
+});
+
+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.
+
+## Exporters
+
+Console exporters ship for development. They serialize defensively — a
+circular attribute or a BigInt cannot make an exporter throw inside the
+logging path — and emit one line per record by default, which is what log
+shippers parse.
+
+```typescript
+import {
+  createConsoleSpanExporter,
+  createBatchSpanProcessor,
+  createSimpleSpanProcessor,
+} from "@zudojs/observability";
+
+createObservability({
+  serviceName: "api",
+  processors: [
+    createBatchSpanProcessor({
+      exporter: createConsoleSpanExporter({ pretty: true }),
+      batchSize: 512,
+      maxQueueSize: 2048,
+      onError: (error, source) => console.error(source, error),
+    }),
+  ],
+});
+```
+
+Both the span and log processors have a hard queue cap: past it, records are
+dropped and counted rather than growing the process until it dies. Export
+failures go to `onError` instead of vanishing.
+
+Exporters for OpenTelemetry, Prometheus or Datadog belong in separate
+packages; implement `SpanExporter`, `LogExporter` or `MetricExporter`.
+
+## Scopes
+
+`resource()` creates a view that differs only in its resource attributes,
+sharing the parent's logger, registry, processors and exporters:
+
+```typescript
+const podScoped = obs.resource({ "k8s.pod": process.env.POD_NAME });
+```
+
+Shut down the root; a scope does not own the pipeline. `flush()` works from
+either, because the buffers it drains are the shared ones.
+
+## Disabling telemetry
+
+```typescript
+import { createNoopObservability } from "@zudojs/observability";
+
+const obs = enabled ? createObservability(config) : createNoopObservability();
 ```
 
-## Features
+## Errors
 
-- Distributed tracing with span management
-- Metrics registry (counters, gauges, histograms)
-- Context propagation
-- Log correlation with trace IDs
-- Exporters (OTLP, Prometheus, etc.)
+`ObservabilityError` and its subclasses — `ExporterError`,
+`ObservabilityConfigError`, `MetricValueError` — cover the cases where this
+package throws. Transport failures never throw; they are reported through
+`onError`.
 
 ## Use Cases
 

package/dist/errors/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @zudojs/observability — Errors
+ */
+export { ObservabilityError, ExporterError, ObservabilityConfigError, MetricValueError, isObservabilityError, } from "./observabilityError.core.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.js

@@ -0,0 +1,5 @@
+/**
+ * @zudojs/observability — Errors
+ */
+export { ObservabilityError, ExporterError, ObservabilityConfigError, MetricValueError, isObservabilityError, } from "./observabilityError.core.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,32 @@
+/**
+ * @zudojs/observability — Errors
+ *
+ * Telemetry must never be the reason an application fails, so this package
+ * throws only for programmer errors — a malformed configuration, a metric
+ * 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;
+    });
+}
+/** An exporter failed to deliver telemetry. */
+export declare class ExporterError extends ObservabilityError {
+    constructor(exporterName: string, cause?: unknown);
+}
+/** A configuration value is unusable. */
+export declare class ObservabilityConfigError extends ObservabilityError {
+    constructor(message: string, metadata?: Readonly<Record<string, unknown>>);
+}
+/** A metric was given a value it cannot aggregate. */
+export declare class MetricValueError extends ObservabilityError {
+    constructor(metricName: string, value: number, reason: string);
+}
+/** Determines whether an unknown value is an observability error. */
+export declare function isObservabilityError(value: unknown): value is ObservabilityError;
+//# sourceMappingURL=observabilityError.core.d.ts.map

package/dist/errors/observabilityError.core.js

@@ -0,0 +1,56 @@
+/**
+ * @zudojs/observability — Errors
+ *
+ * Telemetry must never be the reason an application fails, so this package
+ * throws only for programmer errors — a malformed configuration, a metric
+ * 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";
+    }
+}
+/** An exporter failed to deliver telemetry. */
+export class ExporterError extends ObservabilityError {
+    constructor(exporterName, cause) {
+        super(`Exporter "${exporterName}" failed to export telemetry`, {
+            metadata: { exporterName },
+            cause,
+        });
+        this.name = "ExporterError";
+    }
+}
+/** A configuration value is unusable. */
+export class ObservabilityConfigError extends ObservabilityError {
+    constructor(message, metadata) {
+        super(message, { code: ErrorCode.VALIDATION_FAILED, metadata });
+        this.name = "ObservabilityConfigError";
+    }
+}
+/** A metric was given a value it cannot aggregate. */
+export class MetricValueError extends ObservabilityError {
+    constructor(metricName, value, reason) {
+        super(`Metric "${metricName}" rejected value ${value}: ${reason}`, {
+            code: ErrorCode.VALIDATION_FAILED,
+            metadata: { metricName, value, reason },
+        });
+        this.name = "MetricValueError";
+    }
+}
+/** Determines whether an unknown value is an observability error. */
+export function isObservabilityError(value) {
+    return value instanceof ObservabilityError;
+}
+//# sourceMappingURL=observabilityError.core.js.map

package/dist/exporter/exporter.console.d.ts

@@ -2,12 +2,50 @@
  * @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 type { LogExporter, LogRecord, MetricExporter, MetricSnapshot, ReadableSpan, SpanExporter } from "../types.js";
+/** Shape of the console methods the exporters use. */
+export interface ConsoleLike {
+    log(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+/** Options shared by the console exporters. */
+export interface ConsoleExporterOptions {
+    /**
+     * Indent the JSON. Default: `false` — one line per record is what log
+     * shippers parse, and pretty-printing a span is expensive under load.
+     */
+    readonly pretty?: boolean;
+    /** Where to write. Defaults to the global console. */
+    readonly console?: ConsoleLike;
+}
+/**
+ * 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 declare function safeStringify(value: unknown, pretty?: boolean): string;
 /**
  * Exports completed spans to the console.
  */
 export declare class ConsoleSpanExporter implements SpanExporter {
+    private readonly pretty;
+    private readonly out;
+    constructor(options?: ConsoleExporterOptions);
     export(spans: readonly ReadableSpan[]): Promise<void>;
     shutdown(): Promise<void>;
 }
@@ -15,6 +53,9 @@ export declare class ConsoleSpanExporter implements SpanExporter {
  * Exports log records to the console.
  */
 export declare class ConsoleLogExporter implements LogExporter {
+    private readonly pretty;
+    private readonly out;
+    constructor(options?: ConsoleExporterOptions);
     export(records: readonly LogRecord[]): Promise<void>;
     shutdown(): Promise<void>;
 }
@@ -22,13 +63,20 @@ export declare class ConsoleLogExporter implements LogExporter {
  * Exports metric snapshots to the console.
  */
 export declare class ConsoleMetricExporter implements MetricExporter {
+    private readonly pretty;
+    private readonly out;
+    constructor(options?: ConsoleExporterOptions);
     export(snapshots: readonly MetricSnapshot[]): Promise<void>;
     shutdown(): Promise<void>;
 }
+/** A log exporter that discards everything. */
+export declare const noopLogExporter: LogExporter;
+/** A metric exporter that discards everything. */
+export declare const noopMetricExporter: MetricExporter;
 /** Creates a console span exporter. */
-export declare function createConsoleSpanExporter(): ConsoleSpanExporter;
+export declare function createConsoleSpanExporter(options?: ConsoleExporterOptions): ConsoleSpanExporter;
 /** Creates a console log exporter. */
-export declare function createConsoleLogExporter(): ConsoleLogExporter;
+export declare function createConsoleLogExporter(options?: ConsoleExporterOptions): ConsoleLogExporter;
 /** Creates a console metric exporter. */
-export declare function createConsoleMetricExporter(): ConsoleMetricExporter;
+export declare function createConsoleMetricExporter(options?: ConsoleExporterOptions): ConsoleMetricExporter;
 //# sourceMappingURL=exporter.console.d.ts.map

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