@objectstack/observability 5.0.0

package/dist/index.d.ts

@@ -0,0 +1,375 @@
+import { Logger } from '@objectstack/spec/contracts';
+export { Logger } from '@objectstack/spec/contracts';
+
+/**
+ * Observability contracts for ObjectStack.
+ *
+ * Three orthogonal concerns live here:
+ *
+ *   - **MetricsRegistry** — counters / histograms / gauges, Prometheus-style names.
+ *   - **ErrorReporter** — APM-style exception capture (Sentry / Datadog / Rollbar).
+ *   - **Logger** — structured log records (re-exported from `@objectstack/spec`).
+ *
+ * Implementations of these contracts live in this same package
+ * (see `metrics-exporters.ts`, `error-exporters.ts`, `loggers.ts`). The
+ * runtime, services, and host applications only depend on the contracts
+ * so any backend can be wired at deployment time.
+ */
+/**
+ * Metrics registry contract.
+ *
+ * Hosts plug in whatever metrics backend they want (Prometheus via
+ * `prom-client`, OTel via `@opentelemetry/api-metrics`, Cloudflare
+ * Workers Analytics Engine, StatsD, CloudWatch, …) without the
+ * framework taking a hard dep on any of them.
+ *
+ * Naming follows Prometheus conventions:
+ *
+ *   - snake_case names
+ *   - unit suffix (`_ms`, `_seconds`, `_bytes`, `_total` for counters)
+ *
+ * Labels are arbitrary string maps; backends should map them to their
+ * native label/tag concept. **Keep cardinality low** — never label by
+ * raw url path, user id, or tenant id without bucketing.
+ *
+ * All methods are fire-and-forget; implementations MUST NOT throw on
+ * the hot path. Use `NoopMetricsRegistry` when metrics are disabled.
+ */
+interface MetricsRegistry {
+    /** Monotonic counter. `value` defaults to 1. */
+    counter(name: string, labels?: Record<string, string>, value?: number): void;
+    /** Histogram / timing in arbitrary units (typically ms). */
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+    /** Point-in-time gauge. */
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+}
+/** Recorded metric sample (used by InMemoryMetricsRegistry and OTLP exporter). */
+interface MetricSample {
+    name: string;
+    kind: 'counter' | 'histogram' | 'gauge';
+    value: number;
+    labels: Record<string, string>;
+    /** Wall-clock timestamp (ms epoch). */
+    at: number;
+}
+/**
+ * Error reporter contract.
+ *
+ * Production deployments wire this to Sentry, Datadog APM, Rollbar,
+ * etc. The runtime calls `captureException` when a route handler
+ * results in a 5xx response so the host's APM gets the stack trace
+ * without each plugin/route needing to import the vendor SDK.
+ *
+ * Implementations MUST NOT throw — error reporting failures should be
+ * swallowed so the original error reaches the client unmolested.
+ *
+ * 4xx responses are intentionally NOT captured here. Client errors
+ * flood APM systems with noise. Use metrics counters
+ * (`http_requests_total{status="4xx"}`) for them, not error reporting.
+ */
+interface ErrorReporter {
+    /**
+     * Capture a thrown error with optional context. Context typically
+     * includes `requestId`, `method`, `route`, `userId`, `orgId`.
+     *
+     * The reporter is responsible for redacting sensitive fields from
+     * `context` (the runtime does not know what is sensitive in the
+     * caller's deployment).
+     */
+    captureException(error: unknown, context?: Record<string, unknown>): void;
+}
+/** Recorded error (used by InMemoryErrorReporter). */
+interface CapturedError {
+    error: unknown;
+    context: Record<string, unknown>;
+    at: number;
+}
+
+/**
+ * Semantic conventions — canonical metric names emitted by the
+ * framework. Listed here so hosts can wire alerts/dashboards against
+ * a stable namespace and so call sites don't sprinkle string
+ * literals through the code base.
+ *
+ * Naming follows Prometheus conventions:
+ *
+ *   - snake_case identifiers.
+ *   - `_total` suffix for monotonic counters.
+ *   - `_ms`, `_seconds`, `_bytes` suffixes for histograms / gauges
+ *     with units.
+ *
+ * Groups roughly mirror the framework subsystems that emit them.
+ * Cloud-specific metrics (DO restarts, Workers Analytics Engine
+ * writes, …) do NOT belong here — they are deployment-specific and
+ * stay in the deployment repo.
+ */
+declare const SEMCONV: {
+    /** Counter, labels: `method`, `route`, `status`. */
+    readonly httpRequestsTotal: "http_requests_total";
+    /** Histogram (ms), labels: `method`, `route`. */
+    readonly httpRequestDurationMs: "http_request_duration_ms";
+    /**
+     * Counter, labels: `method`, `route`. Incremented when an
+     * in-flight handler throws after the response is sent.
+     */
+    readonly httpRequestErrorsTotal: "http_request_errors_total";
+    /** Counter, labels: `adapter` (`local`|`s3`|…), `op` (`get`|`put`|`delete`|`head`), `result` (`ok`|`error`). */
+    readonly storageOperationsTotal: "storage_operations_total";
+    /** Histogram (ms), labels: `adapter`, `op`. */
+    readonly storageOperationDurationMs: "storage_operation_duration_ms";
+    /** Counter, labels: `adapter`, `op`, `errorClass`. */
+    readonly storageErrorsTotal: "storage_errors_total";
+    /** Counter, labels: `adapter` (`memory`|`redis`), `result` (`hit`|`miss`). */
+    readonly cacheLookupsTotal: "cache_lookups_total";
+    /** Counter, labels: `adapter`, `op` (`set`|`delete`|`clear`). */
+    readonly cacheWritesTotal: "cache_writes_total";
+    /** Counter, labels: `adapter`, `op`, `errorClass`. */
+    readonly cacheErrorsTotal: "cache_errors_total";
+    /** Counter, labels: `result` (`ok`|`miss`|`error`). */
+    readonly registryLookupsTotal: "registry_lookups_total";
+    /** Histogram (ms). */
+    readonly registryLookupDurationMs: "registry_lookup_duration_ms";
+    /** Counter, labels: `source` (`r2`|`http`|`local`), `result` (`hit`|`miss`|`error`). */
+    readonly registrySourceFetchesTotal: "registry_source_fetches_total";
+};
+/**
+ * Backwards-compat alias. `RUNTIME_METRICS` was the original (HTTP-only)
+ * constant name shipped from `@objectstack/runtime`; we keep it here so
+ * existing code reading `RUNTIME_METRICS.httpRequestsTotal` continues
+ * to work after the constants moved into this package.
+ */
+declare const RUNTIME_METRICS: {
+    readonly httpRequestsTotal: "http_requests_total";
+    readonly httpRequestDurationMs: "http_request_duration_ms";
+    readonly httpRequestErrorsTotal: "http_request_errors_total";
+};
+
+/**
+ * No-op metrics registry — the default. Discards every observation.
+ * Production deployments should swap this for a real registry; tests
+ * can use {@link InMemoryMetricsRegistry} to assert emissions.
+ */
+declare class NoopMetricsRegistry implements MetricsRegistry {
+    counter(): void;
+    histogram(): void;
+    gauge(): void;
+}
+/**
+ * In-memory registry used for tests and local inspection. Stores
+ * every observation in insertion order; query via the helpers below
+ * or read {@link samples} directly.
+ *
+ * Not intended for production — unbounded growth.
+ */
+declare class InMemoryMetricsRegistry implements MetricsRegistry {
+    readonly samples: MetricSample[];
+    counter(name: string, labels?: Record<string, string>, value?: number): void;
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+    /** Sum of counter increments matching `name` and optionally a label subset. */
+    totalCounter(name: string, labelMatch?: Record<string, string>): number;
+    /** Raw histogram observations matching `name` and optionally a label subset. */
+    histogramValues(name: string, labelMatch?: Record<string, string>): number[];
+    /** Last gauge value matching `name` and optionally a label subset, or undefined. */
+    lastGauge(name: string, labelMatch?: Record<string, string>): number | undefined;
+    /** Clear all recorded samples. */
+    reset(): void;
+}
+/**
+ * Console metrics registry — prints one line per observation. Useful
+ * during local development to confirm that instrumentation is firing.
+ *
+ * Not intended for production: writing every observation to stdout
+ * defeats Prometheus / OTLP pipelines and dominates request latency.
+ */
+declare class ConsoleMetricsRegistry implements MetricsRegistry {
+    private readonly opts;
+    constructor(opts?: {
+        sink?: (line: string) => void;
+        prefix?: string;
+    });
+    counter(name: string, labels?: Record<string, string>, value?: number): void;
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+    private emit;
+}
+/**
+ * Configuration for {@link OtlpHttpMetricsRegistry}.
+ */
+interface OtlpHttpExporterOptions {
+    /**
+     * OTLP/HTTP metrics endpoint, e.g. `http://otel-collector:4318/v1/metrics`.
+     * The path is appended automatically if missing.
+     */
+    endpoint: string;
+    /** Optional headers (Authorization, x-tenant, …). */
+    headers?: Record<string, string>;
+    /**
+     * Resource attributes — `service.name`, `service.namespace`,
+     * `deployment.environment`, etc. Merged into the OTLP `resource`
+     * block on every export.
+     */
+    resource?: Record<string, string>;
+    /**
+     * Custom fetch implementation. Defaults to the global `fetch`.
+     * Allows Workers / undici / node-fetch substitution and test
+     * doubles.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Called when an export attempt fails. Default: silently swallow
+     * (per the contract that metric emission must not throw / log
+     * loudly on the hot path).
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * Maximum number of samples buffered before {@link OtlpHttpMetricsRegistry.flush}
+     * is called automatically. Defaults to 1024.
+     */
+    maxBufferSize?: number;
+}
+/**
+ * OTLP/HTTP metrics exporter.
+ *
+ * Buffers samples in memory and serialises them to the OpenTelemetry
+ * Protocol JSON encoding when {@link flush} is called (manually or
+ * automatically once the buffer hits the configured size).
+ *
+ * Intentionally does **not** start an interval timer in the constructor:
+ * (a) it makes the exporter usable on Cloudflare Workers where
+ * `setInterval` is restricted, and (b) it keeps unit tests deterministic.
+ * Long-running hosts should call `flush()` on a schedule
+ * (e.g. `setInterval(() => reg.flush(), 10_000)` on Node, or
+ * `ctx.waitUntil(reg.flush())` from a Workers fetch handler).
+ *
+ * Only counters, histograms, and gauges are emitted — no support for
+ * exemplars or aggregation temporality switches (the Collector handles
+ * those on the upstream side).
+ */
+declare class OtlpHttpMetricsRegistry implements MetricsRegistry {
+    private buffer;
+    private readonly endpoint;
+    private readonly headers;
+    private readonly resource;
+    private readonly maxBufferSize;
+    private readonly fetchImpl;
+    private readonly onError;
+    constructor(options: OtlpHttpExporterOptions);
+    counter(name: string, labels?: Record<string, string>, value?: number): void;
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+    private record;
+    /** Snapshot the current buffer (for tests). */
+    peek(): readonly MetricSample[];
+    /**
+     * Send the buffered samples to the OTLP endpoint and clear the
+     * buffer. Safe to call concurrently — each invocation takes a
+     * snapshot before clearing.
+     */
+    flush(): Promise<void>;
+}
+
+/** No-op reporter — the default. */
+declare class NoopErrorReporter implements ErrorReporter {
+    captureException(): void;
+}
+/** In-memory reporter for tests. */
+declare class InMemoryErrorReporter implements ErrorReporter {
+    readonly captured: CapturedError[];
+    captureException(error: unknown, context?: Record<string, unknown>): void;
+    reset(): void;
+}
+/**
+ * Console error reporter — writes a structured JSON line to stderr per
+ * captured exception. Convenient default for local development and for
+ * any deployment that ships stderr to a log aggregator (e.g. Loki,
+ * fluent-bit) but does not have a dedicated APM.
+ *
+ * Stack traces are included when the captured value is an `Error`.
+ */
+declare class ConsoleErrorReporter implements ErrorReporter {
+    private readonly opts;
+    constructor(opts?: {
+        sink?: (line: string) => void;
+    });
+    captureException(error: unknown, context?: Record<string, unknown>): void;
+}
+
+/** Recognised log levels in increasing severity order. */
+declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error", "fatal"];
+type LogLevel = (typeof LOG_LEVELS)[number];
+/** No-op logger — discards every message. */
+declare class NoopLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+    fatal(): void;
+    child(): Logger;
+}
+/**
+ * Console logger — pretty-printed messages for local development.
+ *
+ * Not suitable for production where structured JSON is required;
+ * use {@link JsonLogger} there instead.
+ */
+declare class ConsoleLogger implements Logger {
+    private readonly opts;
+    constructor(opts?: {
+        level?: LogLevel;
+        context?: Record<string, unknown>;
+        sink?: {
+            log: (s: string) => void;
+            error: (s: string) => void;
+        };
+    });
+    private get threshold();
+    private get sink();
+    private get context();
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, error?: Error, meta?: Record<string, unknown>): void;
+    fatal(message: string, error?: Error, meta?: Record<string, unknown>): void;
+    child(context: Record<string, unknown>): Logger;
+    private emit;
+}
+/**
+ * JSON logger — one JSON object per line on stdout (errors on stderr).
+ *
+ * Matches the shape that Loki / fluent-bit / Cloudflare Logpush ingest
+ * by default. Every record contains `ts`, `level`, `msg`, and any
+ * accumulated child-context plus per-call `meta`.
+ *
+ * Use this in production. Use {@link ConsoleLogger} during development
+ * for human-friendly output.
+ */
+declare class JsonLogger implements Logger {
+    private readonly opts;
+    constructor(opts?: {
+        level?: LogLevel;
+        context?: Record<string, unknown>;
+        sink?: {
+            log: (s: string) => void;
+            error: (s: string) => void;
+        };
+        /** Optional fields injected into every record (`service`, `env`, …). */
+        base?: Record<string, unknown>;
+        /** Wall clock for tests. */
+        now?: () => Date;
+    });
+    private get threshold();
+    private get sink();
+    private get context();
+    private get base();
+    private get now();
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, error?: Error, meta?: Record<string, unknown>): void;
+    fatal(message: string, error?: Error, meta?: Record<string, unknown>): void;
+    child(context: Record<string, unknown>): Logger;
+    private emit;
+}
+
+export { type CapturedError, ConsoleErrorReporter, ConsoleLogger, ConsoleMetricsRegistry, type ErrorReporter, InMemoryErrorReporter, InMemoryMetricsRegistry, JsonLogger, LOG_LEVELS, type LogLevel, type MetricSample, type MetricsRegistry, NoopErrorReporter, NoopLogger, NoopMetricsRegistry, type OtlpHttpExporterOptions, OtlpHttpMetricsRegistry, RUNTIME_METRICS, SEMCONV };