@zudojs/observability 0.1.0 → 1.0.0

package/dist/metrics/metrics.reader.js

@@ -0,0 +1,81 @@
+/**
+ * @zudojs/observability — Metric Reader
+ *
+ * Metrics are pull-based in-process: the registry holds live numbers and
+ * nothing moves them anywhere. This reader is the missing half — it snapshots
+ * the registry on an interval and hands the snapshots to an exporter, so a
+ * configured `metricExporter` actually receives data.
+ */
+const DEFAULT_INTERVAL_MS = 60_000;
+/** Snapshots a registry on an interval and exports the result. */
+export class PeriodicMetricReader {
+    registry;
+    exporter;
+    intervalMs;
+    onError;
+    timer;
+    started = false;
+    shuttingDown = false;
+    inFlight;
+    constructor(options) {
+        this.registry = options.registry;
+        this.exporter = options.exporter;
+        this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+        this.onError = options.onError;
+    }
+    /** Begins periodic export. Calling it twice is a no-op. */
+    start() {
+        if (this.started || this.shuttingDown || this.intervalMs <= 0)
+            return;
+        this.started = true;
+        this.timer = setInterval(() => {
+            void this.collect();
+        }, this.intervalMs);
+        if (typeof this.timer === "object" && "unref" in this.timer) {
+            this.timer.unref();
+        }
+    }
+    /** Exports one snapshot immediately. */
+    async collect() {
+        if (this.inFlight) {
+            await this.inFlight;
+            return;
+        }
+        const run = (async () => {
+            const snapshots = this.registry.getAll();
+            if (snapshots.length === 0)
+                return;
+            try {
+                await this.exporter.export(snapshots);
+            }
+            catch (error) {
+                this.onError?.(error, "MetricExporter.export");
+            }
+        })();
+        this.inFlight = run;
+        try {
+            await run;
+        }
+        finally {
+            if (this.inFlight === run)
+                this.inFlight = undefined;
+        }
+    }
+    /** Exports a final snapshot and stops. Safe to call more than once. */
+    async shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        await this.collect();
+        await this.exporter.shutdown();
+    }
+}
+/** Creates a periodic metric reader. */
+export function createPeriodicMetricReader(options) {
+    return new PeriodicMetricReader(options);
+}
+//# sourceMappingURL=metrics.reader.js.map

package/dist/metrics/metrics.registry.d.ts

@@ -4,20 +4,71 @@
  * Central registry for all metrics. Creates and caches metrics by name+labels.
  */
 import type { Counter, Gauge, Histogram, MetricsRegistry, MetricSnapshot } from "../types.js";
+/**
+ * Builds the cache key for one series.
+ *
+ * Label keys and values are JSON-encoded, so `{ a: "b,c=d" }` and
+ * `{ a: "b", c: "d" }` cannot collapse onto the same key the way a bare
+ * `k=v` join lets them.
+ */
+export declare function metricKey(type: string, name: string, labels?: Record<string, string>): string;
+/** Options for {@link DefaultMetricsRegistry}. */
+export interface MetricsRegistryOptions {
+    /**
+     * Maximum number of distinct series held at once. Default: 10,000.
+     *
+     * A label carrying a user ID or a path with IDs in it turns an unbounded
+     * registry into a memory leak, so the cap is on by default and creating a
+     * series past it reports the offending metric instead of growing silently.
+     */
+    readonly maxSeries?: number;
+    /** Bucket boundaries for histograms created by this registry. */
+    readonly histogramBoundaries?: readonly number[];
+    /** Called when the series cap is hit, once per rejected series. */
+    readonly onCardinalityLimit?: (name: string, size: number) => void;
+}
 /**
  * In-memory metrics registry. Creates, caches, and manages metrics.
  */
 export declare class DefaultMetricsRegistry implements MetricsRegistry {
     private readonly metrics;
+    /**
+     * The type each metric name was first registered as.
+     *
+     * The cache key includes the type, so the map alone can never surface a
+     * differently-typed entry — the conflict check that reads it was dead code,
+     * and `counter("x")` followed by `gauge("x")` produced two same-named series
+     * of different types in one document. An OTLP or Prometheus backend rejects
+     * that, so the whole scrape is lost rather than one metric.
+     */
+    private readonly typeByName;
+    private readonly maxSeries;
+    private readonly histogramBoundaries?;
+    private readonly onCardinalityLimit?;
+    /** Series rejected by the cap, reused so callers still get a usable object. */
+    private readonly overflow;
+    /**
+     * Cap on the detached-series cache. Bounded well below `maxSeries` so the
+     * documented ceiling is not quietly doubled by the overflow path.
+     */
+    private readonly maxOverflow;
+    constructor(options?: MetricsRegistryOptions);
+    private create;
+    private obtain;
     counter(name: string, labels?: Record<string, string>): Counter;
     gauge(name: string, labels?: Record<string, string>): Gauge;
     histogram(name: string, labels?: Record<string, string>): Histogram;
-    getCounter(name: string): Counter | undefined;
-    getGauge(name: string): Gauge | undefined;
-    getHistogram(name: string): Histogram | undefined;
+    private lookup;
+    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;
+    getSeries(name: string): readonly MetricSnapshot[];
+    private snapshot;
     getAll(): MetricSnapshot[];
+    size(): number;
     reset(): void;
+    clear(): void;
 }
 /** Creates a metrics registry. */
-export declare function createMetricsRegistry(): DefaultMetricsRegistry;
+export declare function createMetricsRegistry(options?: MetricsRegistryOptions): DefaultMetricsRegistry;
 //# sourceMappingURL=metrics.registry.d.ts.map

package/dist/metrics/metrics.registry.js

@@ -6,88 +6,175 @@
 import { DefaultCounter } from "./counter/counter.core.js";
 import { DefaultGauge } from "./gauge/gauge.core.js";
 import { DefaultHistogram } from "./histogram/histogram.core.js";
-function metricKey(type, name, labels) {
-    const labelStr = labels
+import { ObservabilityConfigError } from "../errors/index.js";
+/**
+ * Builds the cache key for one series.
+ *
+ * Label keys and values are JSON-encoded, so `{ a: "b,c=d" }` and
+ * `{ a: "b", c: "d" }` cannot collapse onto the same key the way a bare
+ * `k=v` join lets them.
+ */
+export function metricKey(type, name, labels) {
+    const entries = labels
         ? Object.entries(labels)
-            .sort(([a], [b]) => a.localeCompare(b))
-            .map(([k, v]) => `${k}=${v}`)
-            .join(",")
-        : "";
-    return `${type}:${name}:${labelStr}`;
+            .filter(([, value]) => value !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        : [];
+    return `${type}:${name}:${JSON.stringify(entries)}`;
 }
+const DEFAULT_MAX_SERIES = 10_000;
+/** Upper bound on the detached series kept for callers past the cap. */
+const MAX_OVERFLOW_SERIES = 1_024;
 /**
  * In-memory metrics registry. Creates, caches, and manages metrics.
  */
 export class DefaultMetricsRegistry {
     metrics = new Map();
+    /**
+     * The type each metric name was first registered as.
+     *
+     * The cache key includes the type, so the map alone can never surface a
+     * differently-typed entry — the conflict check that reads it was dead code,
+     * and `counter("x")` followed by `gauge("x")` produced two same-named series
+     * of different types in one document. An OTLP or Prometheus backend rejects
+     * that, so the whole scrape is lost rather than one metric.
+     */
+    typeByName = new Map();
+    maxSeries;
+    histogramBoundaries;
+    onCardinalityLimit;
+    /** Series rejected by the cap, reused so callers still get a usable object. */
+    overflow = new Map();
+    /**
+     * Cap on the detached-series cache. Bounded well below `maxSeries` so the
+     * documented ceiling is not quietly doubled by the overflow path.
+     */
+    maxOverflow;
+    constructor(options) {
+        this.maxSeries = options?.maxSeries ?? DEFAULT_MAX_SERIES;
+        this.maxOverflow = Math.max(1, Math.min(this.maxSeries, MAX_OVERFLOW_SERIES));
+        this.histogramBoundaries = options?.histogramBoundaries;
+        this.onCardinalityLimit = options?.onCardinalityLimit;
+    }
+    create(type, name, labels) {
+        if (type === "counter") {
+            return { type, metric: new DefaultCounter(name, labels) };
+        }
+        if (type === "gauge") {
+            return { type, metric: new DefaultGauge(name, labels) };
+        }
+        return {
+            type,
+            metric: new DefaultHistogram(name, labels, this.histogramBoundaries),
+        };
+    }
+    obtain(type, name, labels) {
+        const registeredAs = this.typeByName.get(name);
+        if (registeredAs !== undefined && registeredAs !== type) {
+            throw new ObservabilityConfigError(`Metric "${name}" is already registered as a ${registeredAs}`, { name, registeredAs, requestedAs: type });
+        }
+        const key = metricKey(type, name, labels);
+        const existing = this.metrics.get(key);
+        if (existing)
+            return existing;
+        if (this.metrics.size >= this.maxSeries) {
+            // Past the cap, hand back a detached series so instrumented code keeps
+            // working, but never let the registry itself grow.
+            const cached = this.overflow.get(key);
+            if (cached)
+                return cached;
+            this.onCardinalityLimit?.(name, this.metrics.size);
+            const detached = this.create(type, name, labels);
+            if (this.overflow.size < this.maxOverflow)
+                this.overflow.set(key, detached);
+            return detached;
+        }
+        const entry = this.create(type, name, labels);
+        this.metrics.set(key, entry);
+        this.typeByName.set(name, type);
+        return entry;
+    }
     counter(name, labels) {
-        const key = metricKey("counter", name, labels);
-        let entry = this.metrics.get(key);
-        if (!entry || entry.type !== "counter") {
-            entry = { type: "counter", metric: new DefaultCounter(name, labels) };
-            this.metrics.set(key, entry);
+        const entry = this.obtain("counter", name, labels);
+        // `obtain` rejects a type conflict before returning, so this narrowing
+        // always succeeds; the throw is a guard, not a cast.
+        if (entry.type !== "counter") {
+            throw new ObservabilityConfigError(`Metric "${name}" is already registered as a ${entry.type}`, { name, registeredAs: entry.type, requestedAs: "counter" });
         }
         return entry.metric;
     }
     gauge(name, labels) {
-        const key = metricKey("gauge", name, labels);
-        let entry = this.metrics.get(key);
-        if (!entry || entry.type !== "gauge") {
-            entry = { type: "gauge", metric: new DefaultGauge(name, labels) };
-            this.metrics.set(key, entry);
+        const entry = this.obtain("gauge", name, labels);
+        // `obtain` rejects a type conflict before returning, so this narrowing
+        // always succeeds; the throw is a guard, not a cast.
+        if (entry.type !== "gauge") {
+            throw new ObservabilityConfigError(`Metric "${name}" is already registered as a ${entry.type}`, { name, registeredAs: entry.type, requestedAs: "gauge" });
         }
         return entry.metric;
     }
     histogram(name, labels) {
-        const key = metricKey("histogram", name, labels);
-        let entry = this.metrics.get(key);
-        if (!entry || entry.type !== "histogram") {
-            entry = { type: "histogram", metric: new DefaultHistogram(name, labels) };
-            this.metrics.set(key, entry);
+        const entry = this.obtain("histogram", name, labels);
+        // `obtain` rejects a type conflict before returning, so this narrowing
+        // always succeeds; the throw is a guard, not a cast.
+        if (entry.type !== "histogram") {
+            throw new ObservabilityConfigError(`Metric "${name}" is already registered as a ${entry.type}`, { name, registeredAs: entry.type, requestedAs: "histogram" });
         }
         return entry.metric;
     }
-    getCounter(name) {
-        for (const entry of this.metrics.values()) {
-            if (entry.type === "counter" && entry.metric.name === name)
-                return entry.metric;
-        }
-        return undefined;
+    lookup(type, name, labels) {
+        return this.metrics.get(metricKey(type, name, labels));
     }
-    getGauge(name) {
-        for (const entry of this.metrics.values()) {
-            if (entry.type === "gauge" && entry.metric.name === name)
-                return entry.metric;
-        }
-        return undefined;
+    getCounter(name, labels) {
+        const entry = this.lookup("counter", name, labels);
+        return entry?.type === "counter" ? entry.metric : undefined;
     }
-    getHistogram(name) {
-        for (const entry of this.metrics.values()) {
-            if (entry.type === "histogram" && entry.metric.name === name)
-                return entry.metric;
-        }
-        return undefined;
+    getGauge(name, labels) {
+        const entry = this.lookup("gauge", name, labels);
+        return entry?.type === "gauge" ? entry.metric : undefined;
     }
-    getAll() {
+    getHistogram(name, labels) {
+        const entry = this.lookup("histogram", name, labels);
+        return entry?.type === "histogram" ? entry.metric : undefined;
+    }
+    getSeries(name) {
+        const timestamp = new Date();
         const snapshots = [];
         for (const entry of this.metrics.values()) {
-            snapshots.push({
-                name: entry.metric.name,
-                type: entry.type,
-                value: entry.metric.getValue(),
-                labels: entry.metric.labels,
-            });
+            if (entry.metric.name === name) {
+                snapshots.push(this.snapshot(entry, timestamp));
+            }
         }
         return snapshots;
     }
+    snapshot(entry, timestamp) {
+        return {
+            name: entry.metric.name,
+            type: entry.type,
+            value: entry.metric.getValue(),
+            labels: entry.metric.labels ? { ...entry.metric.labels } : undefined,
+            timestamp,
+        };
+    }
+    getAll() {
+        const timestamp = new Date();
+        return [...this.metrics.values()].map((entry) => this.snapshot(entry, timestamp));
+    }
+    size() {
+        return this.metrics.size;
+    }
     reset() {
         for (const entry of this.metrics.values()) {
             entry.metric.reset();
         }
     }
+    clear() {
+        this.metrics.clear();
+        this.overflow.clear();
+        this.typeByName.clear();
+    }
 }
 /** Creates a metrics registry. */
-export function createMetricsRegistry() {
-    return new DefaultMetricsRegistry();
+export function createMetricsRegistry(options) {
+    return new DefaultMetricsRegistry(options);
 }
 //# sourceMappingURL=metrics.registry.js.map

package/dist/noop/index.d.ts

@@ -3,5 +3,5 @@
  *
  * No-op implementations that discard all telemetry.
  */
-export { NoopObservability, createNoopObservability, noopLogger, noopCounter, noopGauge, noopHistogram, noopMetricsRegistry, noopSpan, noopTracer, noopPropagationManager, } from "./noopObservability.core.js";
+export { NoopObservability, createNoopObservability, noopLogger, noopCounter, noopGauge, noopHistogram, noopMetricsRegistry, noopSpan, noopTracer, noopPropagationManager, INVALID_PROPAGATION_CONTEXT, } from "./noopObservability.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/noop/index.js

@@ -3,5 +3,5 @@
  *
  * No-op implementations that discard all telemetry.
  */
-export { NoopObservability, createNoopObservability, noopLogger, noopCounter, noopGauge, noopHistogram, noopMetricsRegistry, noopSpan, noopTracer, noopPropagationManager, } from "./noopObservability.core.js";
+export { NoopObservability, createNoopObservability, noopLogger, noopCounter, noopGauge, noopHistogram, noopMetricsRegistry, noopSpan, noopTracer, noopPropagationManager, INVALID_PROPAGATION_CONTEXT, } from "./noopObservability.core.js";
 //# sourceMappingURL=index.js.map

package/dist/noop/noopObservability.core.d.ts

@@ -4,12 +4,21 @@
  * No-op implementations that discard all telemetry.
  * Allows instrumentation code to remain simple without null checks.
  */
-import type { Counter, Gauge, Histogram, Logger, MetricsRegistry, Observability, PropagationManager, Span, Tracer } from "../types.js";
+import type { Counter, Gauge, Histogram, Logger, MetricsRegistry, Observability, PropagationContext, PropagationManager, Span, Tracer } from "../types.js";
 declare const noopLogger: Logger;
 declare const noopCounter: Counter;
 declare const noopGauge: Gauge;
 declare const noopHistogram: Histogram;
 declare const noopMetricsRegistry: MetricsRegistry;
+/**
+ * A span that records nothing.
+ *
+ * `startTime` is a getter rather than a captured value: as a module-level
+ * constant it would report the moment the process loaded, for every span,
+ * forever. The context carries the all-zero IDs the W3C spec reserves for
+ * "invalid", so a noop span that reaches an exporter is recognisable rather
+ * than looking like a real trace.
+ */
 declare const noopSpan: Span;
 declare const noopTracer: Tracer;
 declare const noopPropagationManager: PropagationManager;
@@ -22,10 +31,13 @@ export declare class NoopObservability implements Observability {
     readonly metrics: MetricsRegistry;
     readonly tracer: Tracer;
     readonly propagation: PropagationManager;
-    resource(): Observability;
+    resource(_attributes: Record<string, unknown>): Observability;
+    flush(): Promise<void>;
     shutdown(): Promise<void>;
 }
 /** Creates a noop observability instance. */
 export declare function createNoopObservability(): NoopObservability;
+/** A propagation context with the reserved invalid IDs. */
+export declare const INVALID_PROPAGATION_CONTEXT: PropagationContext;
 export { noopLogger, noopCounter, noopGauge, noopHistogram, noopMetricsRegistry, noopSpan, noopTracer, noopPropagationManager, };
 //# sourceMappingURL=noopObservability.core.d.ts.map

package/dist/noop/noopObservability.core.js

@@ -4,7 +4,8 @@
  * No-op implementations that discard all telemetry.
  * Allows instrumentation code to remain simple without null checks.
  */
-import { LogLevel } from "../types.js";
+import { LogLevel, TraceFlags } from "../types.js";
+import { createPropagationContext } from "../propagation/index.js";
 /* ─── Noop Logger ─────────────────────────────────────────────────────── */
 const noopLogger = {
     name: "noop",
@@ -17,6 +18,7 @@ const noopLogger = {
     fatal: () => { },
     child: () => noopLogger,
     isLevelEnabled: () => false,
+    setLevel: () => { },
     flush: async () => { },
 };
 /* ─── Noop Counter ────────────────────────────────────────────────────── */
@@ -36,10 +38,23 @@ const noopGauge = {
     reset: () => { },
 };
 /* ─── Noop Histogram ──────────────────────────────────────────────────── */
+const EMPTY_HISTOGRAM = {
+    count: 0,
+    sum: 0,
+    min: 0,
+    max: 0,
+    mean: 0,
+    buckets: [],
+    p50: 0,
+    p90: 0,
+    p95: 0,
+    p99: 0,
+};
 const noopHistogram = {
     name: "noop",
     record: () => { },
-    getValue: () => ({ count: 0, sum: 0, min: 0, max: 0 }),
+    getValue: () => EMPTY_HISTOGRAM,
+    percentile: () => 0,
     reset: () => { },
 };
 /* ─── Noop Metrics Registry ───────────────────────────────────────────── */
@@ -50,14 +65,32 @@ const noopMetricsRegistry = {
     getCounter: () => undefined,
     getGauge: () => undefined,
     getHistogram: () => undefined,
+    getSeries: () => [],
     getAll: () => [],
+    size: () => 0,
     reset: () => { },
+    clear: () => { },
 };
 /* ─── Noop Span ───────────────────────────────────────────────────────── */
+/**
+ * A span that records nothing.
+ *
+ * `startTime` is a getter rather than a captured value: as a module-level
+ * constant it would report the moment the process loaded, for every span,
+ * forever. The context carries the all-zero IDs the W3C spec reserves for
+ * "invalid", so a noop span that reaches an exporter is recognisable rather
+ * than looking like a real trace.
+ */
 const noopSpan = {
     name: "noop",
-    context: { traceId: "", spanId: "" },
-    startTime: new Date(),
+    context: {
+        traceId: "0".repeat(32),
+        spanId: "0".repeat(16),
+        traceFlags: TraceFlags.NONE,
+    },
+    get startTime() {
+        return new Date();
+    },
     setAttribute: () => { },
     addEvent: () => { },
     setStatus: () => { },
@@ -71,14 +104,11 @@ const noopTracer = {
     startSpan: () => noopSpan,
 };
 /* ─── Noop Propagation Manager ────────────────────────────────────────── */
-const noopContext = {
-    traceId: "",
-    spanId: "",
-};
 const noopPropagationManager = {
-    current: () => noopContext,
+    current: () => undefined,
     run: async (_ctx, fn) => fn(),
-    derive: () => noopContext,
+    runSync: (_ctx, fn) => fn(),
+    derive: (overrides) => createPropagationContext(overrides),
 };
 /* ─── Noop Observability ──────────────────────────────────────────────── */
 /**
@@ -90,14 +120,21 @@ export class NoopObservability {
     metrics = noopMetricsRegistry;
     tracer = noopTracer;
     propagation = noopPropagationManager;
-    resource() {
+    resource(_attributes) {
         return this;
     }
+    async flush() { }
     async shutdown() { }
 }
 /** Creates a noop observability instance. */
 export function createNoopObservability() {
     return new NoopObservability();
 }
+/** A propagation context with the reserved invalid IDs. */
+export const INVALID_PROPAGATION_CONTEXT = Object.freeze({
+    traceId: "0".repeat(32),
+    spanId: "0".repeat(16),
+    traceFlags: TraceFlags.NONE,
+});
 export { noopLogger, noopCounter, noopGauge, noopHistogram, noopMetricsRegistry, noopSpan, noopTracer, noopPropagationManager, };
 //# sourceMappingURL=noopObservability.core.js.map

package/dist/observability/observability.core.d.ts

@@ -5,7 +5,27 @@
  * propagation. Other Zudojs packages depend on this abstraction rather
  * than on specific telemetry implementations.
  */
-import type { Logger, MetricsRegistry, Observability, ObservabilityConfig, PropagationManager, Tracer } from "../types.js";
+import type { Logger, MetricsRegistry, Observability, ObservabilityConfig, PropagationManager, SpanProcessor, Tracer } from "../types.js";
+import { StructuredLogger } from "../logger/index.js";
+import { DefaultMetricsRegistry, PeriodicMetricReader } from "../metrics/index.js";
+import { AsyncPropagationManager } from "../propagation/index.js";
+import { BatchLogProcessor } from "../processor/index.js";
+/**
+ * Everything a facade owns and must tear down, shared by an instance and the
+ * scopes it creates through {@link DefaultObservability.resource}.
+ */
+interface TelemetryPipeline {
+    readonly logger: StructuredLogger;
+    readonly metrics: DefaultMetricsRegistry;
+    readonly propagation: AsyncPropagationManager;
+    readonly processors: readonly SpanProcessor[];
+    readonly logProcessor?: BatchLogProcessor;
+    readonly metricReader: PeriodicMetricReader;
+    readonly config: ObservabilityConfig;
+    readonly sampler: ObservabilityConfig["sampler"];
+    /** Redacts span attributes, when `config.redaction` is set. */
+    readonly redactAttribute?: (key: string, value: unknown) => unknown;
+}
 /**
  * Default observability implementation.
  *
@@ -17,12 +37,46 @@ export declare class DefaultObservability implements Observability {
     readonly metrics: MetricsRegistry;
     readonly tracer: Tracer;
     readonly propagation: PropagationManager;
+    private readonly pipeline;
     private readonly resourceAttributes;
-    private readonly shutdownHooks;
-    constructor(config: ObservabilityConfig);
+    /** Scopes share the parent's pipeline, so only the root tears it down. */
+    private readonly ownsPipeline;
+    private shutdownPromise?;
+    constructor(config: ObservabilityConfig, scope?: {
+        readonly pipeline: TelemetryPipeline;
+        readonly resourceAttributes: Record<string, unknown>;
+    });
+    /**
+     * Creates a scope that differs only in its resource attributes.
+     *
+     * The logger, registry, processors and exporters are shared with the parent:
+     * building a second pipeline here silently dropped every configured
+     * exporter and log level, and left an orphan flush timer nobody shut down.
+     */
     resource(attributes: Record<string, unknown>): Observability;
+    /**
+     * Drains every buffer without shutting anything down.
+     *
+     * A scope shares its parent's pipeline, so draining from one is both safe
+     * and what the caller asked for. Returning early because the scope does not
+     * *own* the pipeline made `obs.resource({...}).flush()` a silent no-op —
+     * the buffered records it was meant to push were still sitting in the queue
+     * when the caller went on to exit.
+     */
+    flush(): Promise<void>;
+    private drain;
+    private reportFailures;
+    /**
+     * Shuts the pipeline down. Idempotent, and one failing step never skips the
+     * rest — a half-torn-down telemetry stack is worse than a noisy one.
+     *
+     * A scope created by {@link DefaultObservability.resource} does not own the
+     * pipeline and shutting it down is a no-op; shut down the root instead.
+     */
     shutdown(): Promise<void>;
+    private performShutdown;
 }
 /** Creates an observability instance. */
 export declare function createObservability(config: ObservabilityConfig): DefaultObservability;
+export {};
 //# sourceMappingURL=observability.core.d.ts.map