@zudojs/observability 0.1.0 → 1.0.0

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

@@ -1,9 +1,13 @@
 /**
  * @zudojs/observability — Tracer
  *
- * Creates spans and notifies processors on start/end.
+ * Creates spans, applies the sampling decision, and notifies processors on
+ * start and end.
  */
-import { DefaultSpan, createSpan } from "../span/index.js";
+import { TraceFlags } from "../../types.js";
+import { DefaultSpan } from "../span/span.core.js";
+import { createChildSpanContext, createSpanContext, } from "../span/spanContext.type.js";
+import { AlwaysOnSampler } from "../../sampling/index.js";
 /**
  * Default tracer that creates spans and notifies processors on start/end.
  */
@@ -11,47 +15,99 @@ export class DefaultTracer {
     processors;
     exporter;
     resource;
+    sampler;
+    limits;
+    captureStackTraces;
+    redactAttribute;
+    onError;
     constructor(options) {
         this.processors = [...(options?.processors ?? [])];
         this.exporter = options?.exporter;
         this.resource = { ...(options?.resource ?? {}) };
+        this.sampler = options?.sampler ?? new AlwaysOnSampler();
+        this.limits = options?.limits;
+        this.captureStackTraces = options?.captureStackTraces ?? true;
+        this.redactAttribute = options?.redactAttribute;
+        this.onError = options?.onError;
     }
     startSpan(name, options) {
-        const tracer = this;
-        const span = createSpan(name, {
+        // Build the context first so the sampler can key on the real trace ID,
+        // then stamp the decision into traceFlags so children inherit it.
+        const base = options?.parent
+            ? createChildSpanContext(options.parent)
+            : createSpanContext();
+        const decision = this.sampler.shouldSample(options?.parent, base.traceId);
+        const sampled = decision.decision === "RECORD_AND_SAMPLE";
+        const recording = decision.decision !== "DO_NOT_RECORD";
+        const context = {
+            ...base,
+            traceFlags: sampled ? TraceFlags.SAMPLED : TraceFlags.NONE,
+        };
+        const span = new DefaultSpan(name, context, {
             ...options,
             resource: this.resource,
+            limits: this.limits,
+            captureStackTraces: this.captureStackTraces,
+            redactAttribute: this.redactAttribute,
+            recording,
+            // Only a sampled span reaches the processors; a RECORD_ONLY span is
+            // readable in-process but is not exported.
+            onEnd: sampled ? (readable) => this.notifyEnd(readable) : undefined,
         });
-        for (const processor of this.processors) {
-            processor.onStart(span);
+        if (decision.attributes) {
+            for (const [key, value] of Object.entries(decision.attributes)) {
+                span.setAttribute(key, value);
+            }
         }
-        return new Proxy(span, {
-            get(target, prop) {
-                if (prop === "end") {
-                    return () => {
-                        target.end();
-                        for (const processor of tracer.processors) {
-                            processor.onEnd(target.toReadableSpan());
-                        }
-                    };
+        if (sampled) {
+            for (const processor of this.processors) {
+                try {
+                    processor.onStart(span);
                 }
-                return Reflect.get(target, prop);
-            },
-        });
+                catch (error) {
+                    this.onError?.(error, "SpanProcessor.onStart");
+                }
+            }
+        }
+        return span;
+    }
+    notifyEnd(readable) {
+        for (const processor of this.processors) {
+            try {
+                processor.onEnd(readable);
+            }
+            catch (error) {
+                this.onError?.(error, "SpanProcessor.onEnd");
+            }
+        }
     }
-    /** Exports a completed span directly. */
+    /** Exports a completed span directly, bypassing the processors. */
     async exportSpan(span) {
         if (this.exporter) {
             await this.exporter.export([span]);
         }
     }
-    /** Shuts down all processors and the exporter. */
-    async shutdown() {
-        for (const processor of this.processors) {
-            await processor.shutdown();
+    /** Drains every processor without shutting anything down. */
+    async forceFlush() {
+        const results = await Promise.allSettled(this.processors.map((processor) => processor.forceFlush?.()));
+        for (const result of results) {
+            if (result.status === "rejected") {
+                this.onError?.(result.reason, "SpanProcessor.forceFlush");
+            }
         }
-        if (this.exporter) {
-            await this.exporter.shutdown();
+    }
+    /**
+     * Shuts down every processor.
+     *
+     * The exporter is not shut down here: the owner that supplied it shuts it
+     * down, and doing it in both places closed the same connection twice.
+     */
+    async shutdown() {
+        const results = await Promise.allSettled(this.processors.map((processor) => processor.shutdown()));
+        for (const result of results) {
+            if (result.status === "rejected") {
+                this.onError?.(result.reason, "SpanProcessor.shutdown");
+            }
         }
     }
 }

package/dist/types/config.types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Configuration types for the observability package.
+ */
+import type { LogLevel, Logger, LogExporter } from "./logging.types.js";
+import type { MetricsRegistry, MetricExporter } from "./metrics.types.js";
+import type { MetricsRegistryOptions } from "../metrics/metrics.registry.js";
+import type { Tracer, SpanExporter, SpanProcessor, SpanLimits, Sampler } from "./tracing.types.js";
+/** Distributed tracing context carried through execution. */
+export interface PropagationContext {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly requestId?: string;
+    readonly correlationId?: string;
+    readonly userId?: string;
+    readonly service?: string;
+    /** @see import("./tracing.types.js").TraceFlags */
+    readonly traceFlags?: number;
+    readonly baggage?: Record<string, string>;
+}
+/** Options for creating a propagation context. */
+export interface PropagationContextOptions {
+    readonly traceId?: string;
+    readonly spanId?: string;
+    readonly parentSpanId?: string;
+    readonly requestId?: string;
+    readonly correlationId?: string;
+    readonly userId?: string;
+    readonly service?: string;
+    readonly traceFlags?: number;
+    readonly baggage?: Record<string, string>;
+}
+/** Manages propagation contexts. */
+export interface PropagationManager {
+    /**
+     * The active context, or `undefined` outside a {@link PropagationManager.run}
+     * scope. Callers that want a context regardless should create one
+     * explicitly, so that "no context" stays distinguishable from a real one.
+     */
+    current(): PropagationContext | undefined;
+    /** Runs a function with a new propagation context. */
+    run<T>(context: PropagationContext, fn: () => T | Promise<T>): Promise<T>;
+    /** Runs a function synchronously with a new propagation context. */
+    runSync<T>(context: PropagationContext, fn: () => T): T;
+    /** Creates a new context derived from the current one. */
+    derive(overrides?: PropagationContextOptions): PropagationContext;
+}
+/** How a field name is matched against the sensitive-field list. */
+export type RedactionMatchMode = "exact" | "contains";
+/** Configuration for redacting sensitive fields from logs and traces. */
+export interface RedactionConfig {
+    /**
+     * Field names to redact (case-insensitive). Defaults to a built-in list
+     * covering passwords, tokens, cookies, keys and card numbers.
+     */
+    readonly fields?: readonly string[];
+    /**
+     * Additional patterns tested against the field name. Useful for
+     * conventions a name list cannot express, such as `/^x-.*-token$/i`.
+     */
+    readonly patterns?: readonly RegExp[];
+    /**
+     * `"contains"` (the default) matches on word boundaries: a field is
+     * sensitive when any run of its words spells a listed term, so
+     * `userPassword`, `x-api-key` and `accessToken` are all caught while
+     * `shippingAddress` and `authorId` — which a raw substring test redacts
+     * because they contain `pin` and `auth` — are not. `"exact"` matches only
+     * whole names.
+     */
+    readonly matchMode?: RedactionMatchMode;
+    /** Custom redaction function, consulted before the field list. */
+    readonly customRedactor?: (key: string, value: unknown) => unknown;
+    /** Replacement text. Defaults to `"[REDACTED]"`. */
+    readonly replacement?: string;
+    /** How deep to walk nested structures. Default: 8. */
+    readonly maxDepth?: number;
+}
+/** Central observability facade. */
+export interface Observability {
+    readonly logger: Logger;
+    readonly metrics: MetricsRegistry;
+    readonly tracer: Tracer;
+    readonly propagation: PropagationManager;
+    /** Creates a scoped observability instance with resource attributes. */
+    resource(attributes: Record<string, unknown>): Observability;
+    /** Drains every buffer without shutting anything down. */
+    flush(): Promise<void>;
+    /** Shuts down all exporters and processors. Safe to call more than once. */
+    shutdown(): Promise<void>;
+}
+/** Configuration for the observability system. */
+export interface ObservabilityConfig {
+    readonly serviceName: string;
+    readonly serviceVersion?: string;
+    readonly environment?: string;
+    readonly logLevel?: LogLevel;
+    readonly logExporter?: LogExporter;
+    readonly spanExporter?: SpanExporter;
+    readonly metricExporter?: MetricExporter;
+    readonly sampler?: Sampler;
+    readonly processors?: readonly SpanProcessor[];
+    /**
+     * Redacts sensitive fields from log contexts *and* from span attributes and
+     * span event attributes. Omit it and neither is redacted.
+     */
+    readonly redaction?: RedactionConfig;
+    /**
+     * Metrics registry tuning: the series cap that bounds cardinality, and the
+     * histogram bucket boundaries. Without this the defaults were unreachable
+     * from the facade, so an application could not lower the 10,000-series cap
+     * that is its only protection against a label carrying a user ID.
+     */
+    readonly metrics?: MetricsRegistryOptions;
+    readonly resource?: Record<string, unknown>;
+    /** Caps on what a single span may accumulate. */
+    readonly spanLimits?: SpanLimits;
+    /**
+     * Fall back to the console exporters when no exporter is supplied.
+     * Defaults to `true`, which prints logs and spans to stdout — convenient in
+     * development and rarely wanted in production, so set it to `false` (or
+     * pass real exporters) when deploying.
+     */
+    readonly useConsoleExporters?: boolean;
+    /** How often metrics are exported, in ms. Default: 60,000. `0` disables it. */
+    readonly metricExportIntervalMs?: number;
+    /** How often buffered log records are flushed, in ms. Default: 1,000. */
+    readonly logFlushIntervalMs?: number;
+    /** How many log records are buffered before an eager flush. Default: 256. */
+    readonly logBatchSize?: number;
+    /**
+     * Record `exception.stacktrace` on spans. Stack traces reach the telemetry
+     * backend unredacted, so this is opt-out. Default: `true`.
+     */
+    readonly captureStackTraces?: boolean;
+    /** Reports a telemetry failure that would otherwise be swallowed. */
+    readonly onError?: (error: unknown, source: string) => void;
+}
+//# sourceMappingURL=config.types.d.ts.map

package/dist/types/config.types.js

@@ -0,0 +1,5 @@
+/**
+ * Configuration types for the observability package.
+ */
+export {};
+//# sourceMappingURL=config.types.js.map

package/dist/types/logging.types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Logging types for the observability package.
+ */
+/**
+ * Numeric log level hierarchy. Higher = more severe.
+ *
+ * A record is emitted when its level is at or above the logger's threshold,
+ * so a threshold of {@link LogLevel.OFF} silences everything.
+ */
+export declare enum LogLevel {
+    TRACE = 0,
+    DEBUG = 1,
+    INFO = 2,
+    WARN = 3,
+    ERROR = 4,
+    FATAL = 5,
+    OFF = 6
+}
+/** Human-readable log level name. */
+export type LogLevelName = "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "off";
+/** A serialized view of a thrown value. */
+export interface LogRecordError {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly cause?: unknown;
+}
+/** A structured log record produced by a logger. */
+export interface LogRecord {
+    readonly level: LogLevel;
+    readonly levelName: LogLevelName;
+    readonly message: string;
+    readonly timestamp: Date;
+    readonly loggerName: string;
+    readonly context?: Record<string, unknown>;
+    readonly error?: LogRecordError;
+    /** Trace this record was emitted under, when a propagation context is active. */
+    readonly traceId?: string;
+    /** Span this record was emitted under, when a propagation context is active. */
+    readonly spanId?: string;
+}
+/** Structured logger interface. */
+export interface Logger {
+    readonly name: string;
+    /** Current threshold. Changes when {@link Logger.setLevel} is called. */
+    readonly level: LogLevel;
+    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;
+    /** Creates a child logger with persistent context. */
+    child(name: string, context?: Record<string, unknown>): Logger;
+    /** Checks if a level would be logged. */
+    isLevelEnabled(level: LogLevel): boolean;
+    /**
+     * Change the threshold at runtime. Child loggers created before the change
+     * keep their own threshold.
+     */
+    setLevel(level: LogLevel): void;
+    /** Flushes any buffered log records. */
+    flush(): Promise<void>;
+}
+/** Options for creating a logger. */
+export interface LoggerOptions {
+    readonly name: string;
+    readonly level?: LogLevel;
+    readonly context?: Record<string, unknown>;
+    readonly transport?: LogTransport;
+    /**
+     * Stamps `traceId` and `spanId` onto every record from the ambient
+     * propagation context. Defaults to `true`.
+     */
+    readonly correlate?: boolean;
+    /**
+     * Redacts the merged context and the error before the record is written.
+     * Applied by the logger, so every transport sees redacted records.
+     */
+    readonly redact?: (context: Record<string, unknown>) => Record<string, unknown>;
+}
+/** A log transport writes records to a destination. */
+export interface LogTransport {
+    readonly name: string;
+    write(record: LogRecord): void | Promise<void>;
+    /** Drains anything buffered. Optional: a direct transport has nothing to do. */
+    flush?(): Promise<void>;
+}
+/** Exports log records to a backend. */
+export interface LogExporter {
+    export(records: readonly LogRecord[]): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=logging.types.d.ts.map

package/dist/types/logging.types.js

@@ -0,0 +1,20 @@
+/**
+ * Logging types for the observability package.
+ */
+/**
+ * Numeric log level hierarchy. Higher = more severe.
+ *
+ * A record is emitted when its level is at or above the logger's threshold,
+ * so a threshold of {@link LogLevel.OFF} silences everything.
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["TRACE"] = 0] = "TRACE";
+    LogLevel[LogLevel["DEBUG"] = 1] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 2] = "INFO";
+    LogLevel[LogLevel["WARN"] = 3] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 4] = "ERROR";
+    LogLevel[LogLevel["FATAL"] = 5] = "FATAL";
+    LogLevel[LogLevel["OFF"] = 6] = "OFF";
+})(LogLevel || (LogLevel = {}));
+//# sourceMappingURL=logging.types.js.map

package/dist/types/metrics.types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Metrics types for the observability package.
+ */
+/** A monotonically increasing counter. */
+export interface Counter {
+    readonly name: string;
+    readonly labels?: Record<string, string>;
+    /**
+     * Adds to the counter. Rejects negative, NaN and infinite values by
+     * throwing — a counter that silently ignored them would report a number
+     * nobody can reconcile with the code that produced it.
+     */
+    increment(value?: number): void;
+    getValue(): number;
+    reset(): void;
+}
+/** A value that can go up and down. */
+export interface Gauge {
+    readonly name: string;
+    readonly labels?: Record<string, string>;
+    setValue(value: number): void;
+    increment(value?: number): void;
+    decrement(value?: number): void;
+    getValue(): number;
+    reset(): void;
+}
+/** The distribution a histogram has observed. */
+export interface HistogramValue {
+    readonly count: number;
+    readonly sum: number;
+    readonly min: number;
+    readonly max: number;
+    /** Mean of the observed values, or 0 when nothing has been recorded. */
+    readonly mean: number;
+    /** Cumulative bucket counts: every value `<= le` observed so far. */
+    readonly buckets: readonly {
+        readonly le: number;
+        readonly count: number;
+    }[];
+    /** Median, interpolated from the bucket boundaries. */
+    readonly p50: number;
+    readonly p90: number;
+    readonly p95: number;
+    readonly p99: number;
+}
+/** A distribution of observed values (latencies, sizes, etc.). */
+export interface Histogram {
+    readonly name: string;
+    readonly labels?: Record<string, string>;
+    /** Records one observation. Rejects NaN and infinite values by throwing. */
+    record(value: number): void;
+    getValue(): HistogramValue;
+    /** Estimates a quantile from the bucket boundaries. `q` is in [0, 1]. */
+    percentile(q: number): number;
+    reset(): void;
+}
+/** Registry for all metrics. */
+export interface MetricsRegistry {
+    counter(name: string, labels?: Record<string, string>): Counter;
+    gauge(name: string, labels?: Record<string, string>): Gauge;
+    histogram(name: string, labels?: Record<string, string>): Histogram;
+    /**
+     * Looks up one series. Omitting `labels` matches the unlabelled series;
+     * it does not mean "any labels", because returning an arbitrary one of
+     * several series is never what a caller wants.
+     */
+    getCounter(name: string, labels?: Record<string, string>): Counter | undefined;
+    getGauge(name: string, labels?: Record<string, string>): Gauge | undefined;
+    getHistogram(name: string, labels?: Record<string, string>): Histogram | undefined;
+    /** Every series registered under `name`, across all label sets. */
+    getSeries(name: string): readonly MetricSnapshot[];
+    getAll(): MetricSnapshot[];
+    /** Number of series currently held. */
+    size(): number;
+    reset(): void;
+    /** Drops every series. Unlike {@link MetricsRegistry.reset}, forgets them. */
+    clear(): void;
+}
+/** A point-in-time snapshot of a metric. */
+export interface MetricSnapshot {
+    readonly name: string;
+    readonly type: "counter" | "gauge" | "histogram";
+    readonly value: number | HistogramValue;
+    readonly labels?: Record<string, string>;
+    /** When the snapshot was taken. */
+    readonly timestamp: Date;
+}
+/** Exports metric snapshots to a backend. */
+export interface MetricExporter {
+    export(snapshots: readonly MetricSnapshot[]): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=metrics.types.d.ts.map

package/dist/types/metrics.types.js

@@ -0,0 +1,5 @@
+/**
+ * Metrics types for the observability package.
+ */
+export {};
+//# sourceMappingURL=metrics.types.js.map

package/dist/types/tracing.types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Tracing types for the observability package.
+ */
+/** Status of a span. */
+export declare enum SpanStatus {
+    UNSET = "UNSET",
+    OK = "OK",
+    ERROR = "ERROR"
+}
+/**
+ * W3C trace flags. Bit 0 carries the sampling decision, which is what a
+ * downstream service reads to keep a trace whole.
+ */
+export declare const TraceFlags: {
+    readonly NONE: 0;
+    readonly SAMPLED: 1;
+};
+/** A span event (timestamped annotation). */
+export interface SpanEvent {
+    readonly name: string;
+    readonly timestamp: Date;
+    readonly attributes?: Record<string, unknown>;
+}
+/** Context identifying a specific span within a trace. */
+export interface SpanContext {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    /** @see TraceFlags */
+    readonly traceFlags?: number;
+}
+/** A single unit of work within a distributed trace. */
+export interface Span {
+    readonly name: string;
+    readonly context: SpanContext;
+    readonly startTime: Date;
+    setAttribute(key: string, value: unknown): void;
+    addEvent(name: string, attributes?: Record<string, unknown>): void;
+    setStatus(status: SpanStatus, message?: string): void;
+    recordError(error: Error): void;
+    end(): void;
+    getDuration(): number;
+    isRecording(): boolean;
+}
+/** Creates new spans. */
+export interface Tracer {
+    startSpan(name: string, options?: SpanOptions): Span;
+}
+/** Options for starting a span. */
+export interface SpanOptions {
+    readonly parent?: SpanContext;
+    readonly attributes?: Record<string, unknown>;
+    readonly kind?: SpanKind;
+}
+/** Semantic kind of a span. */
+export declare enum SpanKind {
+    INTERNAL = "INTERNAL",
+    SERVER = "SERVER",
+    CLIENT = "CLIENT",
+    PRODUCER = "PRODUCER",
+    CONSUMER = "CONSUMER"
+}
+/** Caps on what a single span may accumulate before export. */
+export interface SpanLimits {
+    /** Maximum attributes retained. Default: 128. */
+    readonly maxAttributes?: number;
+    /** Maximum events retained. Default: 128. */
+    readonly maxEvents?: number;
+    /** Maximum attributes retained per event. Default: 128. */
+    readonly maxAttributesPerEvent?: number;
+    /** Strings longer than this are truncated. Default: 4096. */
+    readonly maxAttributeValueLength?: number;
+}
+/** Decision on whether a span should be recorded. */
+export interface SamplingResult {
+    readonly decision: "RECORD_AND_SAMPLE" | "RECORD_ONLY" | "DO_NOT_RECORD";
+    readonly attributes?: Record<string, unknown>;
+}
+/** Determines which traces to sample. */
+export interface Sampler {
+    shouldSample(parentContext?: SpanContext, traceId?: string): SamplingResult;
+}
+/** A span that has been completed and is ready for export. */
+export interface ReadableSpan {
+    readonly name: string;
+    readonly context: SpanContext;
+    readonly kind: SpanKind;
+    readonly startTime: Date;
+    readonly endTime: Date;
+    readonly duration: number;
+    readonly status: SpanStatus;
+    /** The message passed alongside the status, when one was given. */
+    readonly statusMessage?: string;
+    readonly attributes: Record<string, unknown>;
+    readonly events: readonly SpanEvent[];
+    readonly resource: Record<string, unknown>;
+    /** Attributes discarded because the span hit its limit. */
+    readonly droppedAttributes: number;
+    /** Events discarded because the span hit its limit. */
+    readonly droppedEvents: number;
+}
+/** Exports completed spans to a backend. */
+export interface SpanExporter {
+    export(spans: readonly ReadableSpan[]): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/** Processes spans before export (batching, filtering, enrichment). */
+export interface SpanProcessor {
+    onStart(span: Span): void;
+    onEnd(span: ReadableSpan): void;
+    /** Drains anything buffered without shutting the processor down. */
+    forceFlush?(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=tracing.types.d.ts.map

package/dist/types/tracing.types.js

@@ -0,0 +1,28 @@
+/**
+ * Tracing types for the observability package.
+ */
+/** Status of a span. */
+export var SpanStatus;
+(function (SpanStatus) {
+    SpanStatus["UNSET"] = "UNSET";
+    SpanStatus["OK"] = "OK";
+    SpanStatus["ERROR"] = "ERROR";
+})(SpanStatus || (SpanStatus = {}));
+/**
+ * W3C trace flags. Bit 0 carries the sampling decision, which is what a
+ * downstream service reads to keep a trace whole.
+ */
+export const TraceFlags = {
+    NONE: 0,
+    SAMPLED: 1,
+};
+/** Semantic kind of a span. */
+export var SpanKind;
+(function (SpanKind) {
+    SpanKind["INTERNAL"] = "INTERNAL";
+    SpanKind["SERVER"] = "SERVER";
+    SpanKind["CLIENT"] = "CLIENT";
+    SpanKind["PRODUCER"] = "PRODUCER";
+    SpanKind["CONSUMER"] = "CONSUMER";
+})(SpanKind || (SpanKind = {}));
+//# sourceMappingURL=tracing.types.js.map