@zudojs/observability 0.1.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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,274 @@ 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, instances of your own classes (a DTO carrying a `password` field is
+redacted and keeps its prototype), and cyclic graphs (a request object in a log
+context becomes `[CIRCULAR]` rather than a stack overflow). Built-ins —
+`Error`, `Date`, `Map`, `Set`, typed arrays, `URL` — 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