@untangle-code/observability 0.0.0-stage → 0.1.0

package/dist/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@untangle-code/observability",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Untangle observability: typed errors, structured logging, redaction, correlation ids, metrics and profiling. No I/O ports beyond stderr/process.",
+  "license": "AGPL-3.0-only",
+  "homepage": "https://github.com/lboel/untangle",
+  "bugs": {
+    "url": "https://github.com/lboel/untangle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lboel/untangle.git",
+    "directory": "packages/observability"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^22.13.0 || >=24.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/test-helpers.*",
+    "!dist/**/test-support.*",
+    "!dist/**/test-support/**",
+    "!dist/**/testing/**",
+    "!dist/**/__tests__/**",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/test-helpers.ts",
+    "!src/**/test-support.ts",
+    "!src/**/test-support/**",
+    "!src/**/testing/**",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "THIRD_PARTY_LICENSES.md"
+  ],
+  "dependencies": {
+    "@untangle-code/domain": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.7",
+    "typescript": "5.9.3",
+    "vitest": "3.2.7"
+  },
+  "scripts": {
+    "build": "node ../../scripts/tsc-build.mjs tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
 }

package/src/correlation.ts

@@ -0,0 +1,44 @@
+/**
+ * Correlation ids (architecture.md §24.1).
+ *
+ * Ids are drawn exclusively from the injected `Clock`/`Random` ports so that
+ * request contexts are reproducible in tests — never `Date.now()` or
+ * `Math.random()` (BUILD_PLAN global determinism rule).
+ *
+ * `request_id` is the only id created here. `job_id` and `generation_id`
+ * are owned by the subsystems that create the underlying job/generation
+ * (job-engine, index pipeline) — they mint them the same way, via
+ * `Random.uuid()`, once those packages exist; minting them here would just
+ * move the decision of *when* a job/generation begins out of its owner.
+ * `workspace_id`/`repo_id`/`ref_id` are never random — they are the
+ * content-derived identities `@untangle-code/domain` already builds
+ * (`buildWorkspaceId` et al.) and are attached to a request context by the
+ * caller, not generated by observability.
+ */
+import type { Clock, Random } from "@untangle-code/domain";
+
+export interface RequestContextDeps {
+  clock: Clock;
+  random: Random;
+}
+
+export interface RequestContext {
+  /** Random per-operation id (architecture.md §24.1: `request_id`). */
+  requestId: string;
+  /** Epoch-ms creation time, via `Clock` — never `Date.now()`. */
+  createdAtEpochMs: number;
+  /** ISO-8601 creation time, via `Clock`. */
+  createdAtIso: string;
+}
+
+/**
+ * Creates a fresh request context. Deterministic given a deterministic
+ * `Clock`/`Random` (e.g. in tests): same fakes in, same ids out.
+ */
+export function createRequestContext(deps: RequestContextDeps): RequestContext {
+  return {
+    requestId: deps.random.uuid(),
+    createdAtEpochMs: deps.clock.nowEpochMs(),
+    createdAtIso: deps.clock.nowIso(),
+  };
+}

package/src/errors.ts

@@ -0,0 +1,133 @@
+/**
+ * Typed error helpers on top of `@untangle-code/domain`'s `UntangleError`
+ * (architecture.md §22.1, spec.md §25.1, portfolio.md §15).
+ *
+ * `UntangleError`, `ErrorCode`, `ERROR_CODES` and `isUntangleError` are
+ * already fully defined in domain (BUILD_PLAN §3 contract register) — this
+ * module does not redefine them, only adds:
+ *
+ * - one factory function per error class (`ERROR_FACTORIES`, plus a named
+ *   export per code for ergonomic call sites), and
+ * - `toErrorEnvelope()`, which turns *any* thrown value into the `error`
+ *   field shape of `ToolResponseEnvelopeV1` (spec.md §21.2), including
+ *   values that are not `UntangleError` at all (adapter throws, programmer
+ *   errors) so that MCP/CLI response building never has to branch on the
+ *   error's runtime type itself.
+ */
+import {
+  ERROR_CODES,
+  UntangleError,
+  isUntangleError,
+  type ErrorCode,
+  type ToolResponseEnvelopeV1,
+  type UntangleErrorOptions,
+} from "@untangle-code/domain";
+
+export {
+  ERROR_CODES,
+  CORE_ERROR_CODES,
+  PORTFOLIO_ERROR_CODES,
+  STORAGE_ERROR_CODES,
+  isErrorCode,
+  isUntangleError,
+  UntangleError,
+} from "@untangle-code/domain";
+export type { ErrorCode, UntangleErrorOptions } from "@untangle-code/domain";
+
+/** Envelope `error` field shape (spec.md §21.2), derived from domain's envelope type. */
+export type EnvelopeErrorV1 = NonNullable<ToolResponseEnvelopeV1<unknown>["error"]>;
+
+/** Code used for `toErrorEnvelope()` when the input is not an `UntangleError`. */
+export const UNKNOWN_ERROR_CODE = "UNKNOWN_ERROR";
+
+export type ErrorFactory = (message: string, options?: UntangleErrorOptions) => UntangleError;
+
+function factory(code: ErrorCode): ErrorFactory {
+  return (message: string, options?: UntangleErrorOptions): UntangleError =>
+    new UntangleError(code, message, options);
+}
+
+/**
+ * One factory per {@link ErrorCode} (spec.md §25.1 ∪ portfolio.md §15).
+ *
+ * Built from `ERROR_CODES` itself so this map can never drift out of sync
+ * with domain's code list — see `errors.test.ts` for the completeness check.
+ */
+export const ERROR_FACTORIES: Readonly<Record<ErrorCode, ErrorFactory>> = Object.freeze(
+  Object.fromEntries(ERROR_CODES.map((code) => [code, factory(code)])) as Record<
+    ErrorCode,
+    ErrorFactory
+  >,
+);
+
+// Named convenience exports — one per error class (spec.md §25.1).
+export const configInvalidError = ERROR_FACTORIES.CONFIG_INVALID;
+export const workspaceNotFoundError = ERROR_FACTORIES.WORKSPACE_NOT_FOUND;
+export const pathOutsideWorkspaceError = ERROR_FACTORIES.PATH_OUTSIDE_WORKSPACE;
+export const parserUnavailableError = ERROR_FACTORIES.PARSER_UNAVAILABLE;
+export const embeddingUnavailableError = ERROR_FACTORIES.EMBEDDING_UNAVAILABLE;
+export const embeddingDimensionMismatchError = ERROR_FACTORIES.EMBEDDING_DIMENSION_MISMATCH;
+export const qdrantUnavailableError = ERROR_FACTORIES.QDRANT_UNAVAILABLE;
+export const qdrantSchemaIncompatibleError = ERROR_FACTORIES.QDRANT_SCHEMA_INCOMPATIBLE;
+export const lanceDbUnavailableError = ERROR_FACTORIES.LANCEDB_UNAVAILABLE;
+export const lanceDbSchemaIncompatibleError = ERROR_FACTORIES.LANCEDB_SCHEMA_INCOMPATIBLE;
+export const indexIncompleteError = ERROR_FACTORIES.INDEX_INCOMPLETE;
+export const indexProfileMismatchError = ERROR_FACTORIES.INDEX_PROFILE_MISMATCH;
+export const lockHeldError = ERROR_FACTORIES.LOCK_HELD;
+export const jobCancelledError = ERROR_FACTORIES.JOB_CANCELLED;
+export const graphIncompleteError = ERROR_FACTORIES.GRAPH_INCOMPLETE;
+export const analysisIncompleteError = ERROR_FACTORIES.ANALYSIS_INCOMPLETE;
+export const pointTooLargeError = ERROR_FACTORIES.POINT_TOO_LARGE;
+export const pluginEngineIncompatibleError = ERROR_FACTORIES.PLUGIN_ENGINE_INCOMPATIBLE;
+
+// Named convenience exports — one per error class (portfolio.md §15).
+export const portfolioIncompleteError = ERROR_FACTORIES.PORTFOLIO_INCOMPLETE;
+export const portfolioGenerationMissingError = ERROR_FACTORIES.PORTFOLIO_GENERATION_MISSING;
+export const portfolioStaleError = ERROR_FACTORIES.PORTFOLIO_STALE;
+export const manifestParseFailedError = ERROR_FACTORIES.MANIFEST_PARSE_FAILED;
+export const technologyUnknownError = ERROR_FACTORIES.TECHNOLOGY_UNKNOWN;
+export const blueprintKindUnknownError = ERROR_FACTORIES.BLUEPRINT_KIND_UNKNOWN;
+export const blueprintEvidenceInsufficientError = ERROR_FACTORIES.BLUEPRINT_EVIDENCE_INSUFFICIENT;
+export const blueprintTargetNotEmptyError = ERROR_FACTORIES.BLUEPRINT_TARGET_NOT_EMPTY;
+export const blueprintTargetOutsideAllowedError = ERROR_FACTORIES.BLUEPRINT_TARGET_OUTSIDE_ALLOWED;
+export const blueprintWriteFailedError = ERROR_FACTORIES.BLUEPRINT_WRITE_FAILED;
+export const enrichmentDisabledError = ERROR_FACTORIES.ENRICHMENT_DISABLED;
+export const enrichmentUnavailableError = ERROR_FACTORIES.ENRICHMENT_UNAVAILABLE;
+
+/**
+ * Turns any thrown value into the `error` field of `ToolResponseEnvelopeV1`
+ * (spec.md §21.2).
+ *
+ * - An `UntangleError` round-trips through its own `toEnvelopeError()`.
+ * - A plain `Error` (adapter throw, programmer error) is mapped to
+ *   {@link UNKNOWN_ERROR_CODE} with `retryable: false` — never silently
+ *   promoted to a known {@link ErrorCode}, since "not found" and
+ *   "infrastructure failure" must never be conflated (spec.md §25.2).
+ * - Any other thrown value is stringified the same way.
+ */
+export function toErrorEnvelope(error: unknown): EnvelopeErrorV1 {
+  if (isUntangleError(error)) {
+    return error.toEnvelopeError();
+  }
+  if (error instanceof Error) {
+    return {
+      code: UNKNOWN_ERROR_CODE,
+      message: error.message,
+      retryable: false,
+      details: { name: error.name },
+    };
+  }
+  return {
+    code: UNKNOWN_ERROR_CODE,
+    message: typeof error === "string" ? error : safeStringify(error),
+    retryable: false,
+  };
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @untangle-code/observability — the only public export of this package.
+ *
+ * Errors (architecture.md §22.1), structured logging (§24.2), redaction
+ * (spec.md §24), correlation ids (§24.1), metrics (spec.md §23.3) and
+ * `--profile` collection (architecture.md §24.3). No I/O beyond
+ * `process.stderr`/`process.memoryUsage`; no network, no filesystem.
+ */
+
+// Errors — factories on top of domain's UntangleError, plus envelope mapping.
+export * from "./errors.js";
+
+// Redaction.
+export * from "./redact.js";
+
+// Correlation ids.
+export * from "./correlation.js";
+
+// Structured logger (LoggerPort implementation).
+export * from "./logger.js";
+
+// Metrics registry (spec.md §23.3).
+export * from "./metrics.js";
+
+// Profiling collector (architecture.md §24.3).
+export * from "./profiling.js";

package/src/logger.ts

@@ -0,0 +1,192 @@
+/**
+ * Structured logger (architecture.md §24.2) implementing domain's
+ * `LoggerPort`: JSON lines on stderr, level filtering, and a child logger
+ * with bound context.
+ *
+ * `LogEvent` (architecture.md §24.2, fixed in domain) only carries
+ * `requestId`/`jobId` as first-class correlation fields; `generationId`,
+ * `workspaceId`, `repoId` and `refId` (architecture.md §24.1's full
+ * correlation set) have no first-class slot in that shape. This module's
+ * decision (README "Entscheidungen"): those four travel inside `context`
+ * under their own keys, merged in the same way `context` itself is —
+ * closest (call-site) binding wins over an ancestor `child()`'s binding.
+ */
+import type { Clock, LogEvent, LoggerPort, LogLevel } from "@untangle-code/domain";
+
+import { redact } from "./redact.js";
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+};
+
+/** Bindings a child logger merges into every event it emits. */
+export interface LoggerBindings {
+  component?: string;
+  requestId?: string;
+  jobId?: string;
+  generationId?: string;
+  workspaceId?: string;
+  repoId?: string;
+  refId?: string;
+  context?: Record<string, unknown>;
+}
+
+/** `LoggerPort` plus per-level convenience methods that fill in `timestamp` via `Clock`. */
+export interface Logger extends LoggerPort {
+  error(event: string, context?: Record<string, unknown>): void;
+  warn(event: string, context?: Record<string, unknown>): void;
+  info(event: string, context?: Record<string, unknown>): void;
+  debug(event: string, context?: Record<string, unknown>): void;
+  trace(event: string, context?: Record<string, unknown>): void;
+  child(bindings: LoggerBindings): Logger;
+}
+
+export interface CreateLoggerOptions {
+  /** Time source for auto-timestamped convenience methods (`info()`, …). Never `Date.now()`. */
+  clock: Clock;
+  /** Minimum level emitted; events below it are dropped without touching `sink`. Default `"info"`. */
+  level?: LogLevel;
+  /** Where a finished JSON line is written. Default: one `process.stderr.write` call per event. */
+  sink?: (line: string) => void;
+  /**
+   * Opt-in escape hatch (spec.md §24): when `false` (default), source-text
+   * fields in `context` are suppressed rather than logged verbatim.
+   */
+  debugIncludeSourceText?: boolean;
+  /** Initial bound context, equivalent to calling `.child(bindings)` once up front. */
+  bindings?: LoggerBindings;
+}
+
+function defaultSink(line: string): void {
+  process.stderr.write(`${line}\n`);
+}
+
+function mergeBindings(base: LoggerBindings, next: LoggerBindings): LoggerBindings {
+  const merged: LoggerBindings = { ...base, ...next };
+  const context = { ...base.context, ...next.context };
+  if (Object.keys(context).length > 0) {
+    merged.context = context;
+  } else {
+    delete merged.context;
+  }
+  return merged;
+}
+
+/** Correlation keys promoted from {@link LoggerBindings} into `context` (see module doc). */
+function correlationContext(bindings: LoggerBindings): Record<string, unknown> {
+  const extra: Record<string, unknown> = {};
+  if (bindings.generationId !== undefined) extra["generationId"] = bindings.generationId;
+  if (bindings.workspaceId !== undefined) extra["workspaceId"] = bindings.workspaceId;
+  if (bindings.repoId !== undefined) extra["repoId"] = bindings.repoId;
+  if (bindings.refId !== undefined) extra["refId"] = bindings.refId;
+  return extra;
+}
+
+class JsonLinesLogger implements Logger {
+  private readonly clock: Clock;
+  private readonly minLevel: LogLevel;
+  private readonly sink: (line: string) => void;
+  private readonly includeSourceText: boolean;
+  private readonly bindings: LoggerBindings;
+
+  public constructor(
+    clock: Clock,
+    minLevel: LogLevel,
+    sink: (line: string) => void,
+    includeSourceText: boolean,
+    bindings: LoggerBindings,
+  ) {
+    this.clock = clock;
+    this.minLevel = minLevel;
+    this.sink = sink;
+    this.includeSourceText = includeSourceText;
+    this.bindings = bindings;
+  }
+
+  public log(event: LogEvent): void {
+    if (LEVEL_ORDER[event.level] < LEVEL_ORDER[this.minLevel]) {
+      return;
+    }
+    const component = event.component || this.bindings.component || "untangle";
+    const requestId = event.requestId ?? this.bindings.requestId;
+    const jobId = event.jobId ?? this.bindings.jobId;
+    const context = {
+      ...correlationContext(this.bindings),
+      ...this.bindings.context,
+      ...event.context,
+    };
+
+    const line: LogEvent = {
+      timestamp: event.timestamp,
+      level: event.level,
+      component,
+      event: event.event,
+      ...(requestId !== undefined ? { requestId } : {}),
+      ...(jobId !== undefined ? { jobId } : {}),
+      ...(Object.keys(context).length > 0
+        ? {
+            context: redact(context, { includeSourceText: this.includeSourceText }) as Record<
+              string,
+              unknown
+            >,
+          }
+        : {}),
+    };
+    this.sink(JSON.stringify(line));
+  }
+
+  public child(bindings: LoggerBindings): Logger {
+    return new JsonLinesLogger(
+      this.clock,
+      this.minLevel,
+      this.sink,
+      this.includeSourceText,
+      mergeBindings(this.bindings, bindings),
+    );
+  }
+
+  public error(event: string, context?: Record<string, unknown>): void {
+    this.emit("error", event, context);
+  }
+
+  public warn(event: string, context?: Record<string, unknown>): void {
+    this.emit("warn", event, context);
+  }
+
+  public info(event: string, context?: Record<string, unknown>): void {
+    this.emit("info", event, context);
+  }
+
+  public debug(event: string, context?: Record<string, unknown>): void {
+    this.emit("debug", event, context);
+  }
+
+  public trace(event: string, context?: Record<string, unknown>): void {
+    this.emit("trace", event, context);
+  }
+
+  private emit(level: LogLevel, event: string, context: Record<string, unknown> | undefined): void {
+    this.log({
+      timestamp: this.clock.nowIso(),
+      level,
+      component: this.bindings.component ?? "untangle",
+      event,
+      ...(context !== undefined ? { context } : {}),
+    });
+  }
+}
+
+/** Creates a structured, JSON-lines-on-stderr {@link Logger} (architecture.md §24.2). */
+export function createLogger(options: CreateLoggerOptions): Logger {
+  return new JsonLinesLogger(
+    options.clock,
+    options.level ?? "info",
+    options.sink ?? defaultSink,
+    options.debugIncludeSourceText ?? false,
+    options.bindings ?? {},
+  );
+}

package/src/metrics.ts

@@ -0,0 +1,157 @@
+/**
+ * Metrics registry (spec.md §23.3): exactly the internal counters the core
+ * engine SHOULD expose. No external exporter — `snapshot()` returns a plain
+ * object, which callers may print, log, or serve however they like.
+ *
+ * spec.md §23.3 calls all eleven names "Zähler" (counters), but three of
+ * them are not cumulative counts by nature:
+ * - `search_latency_ms` is a distribution of per-search durations, not a
+ *   single number — modeled as a histogram.
+ * - `resolved_import_ratio`/`resolved_call_ratio` are point-in-time ratios
+ *   (resolved / total at last computation), which a monotonic counter
+ *   cannot represent without lying about "cumulative" — modeled as gauges
+ *   the caller sets to the latest computed value.
+ *
+ * The other eight are genuinely cumulative and are modeled as counters.
+ * This is a WP-04-local decision (README "Entscheidungen") — the set of
+ * names is exactly spec.md §23.3's eleven, not open for extension by name.
+ */
+
+/** Cumulative counters (spec.md §23.3). */
+export const COUNTER_NAMES = [
+  "files_scanned",
+  "files_changed",
+  "chunks_created",
+  "embeddings_requested",
+  "embedding_cache_hits",
+  "qdrant_upsert_bytes",
+  "parse_failures",
+  "watcher_reconciliations",
+] as const;
+export type CounterName = (typeof COUNTER_NAMES)[number];
+
+/** Latency distributions (spec.md §23.3). */
+export const HISTOGRAM_NAMES = ["search_latency_ms"] as const;
+export type HistogramName = (typeof HISTOGRAM_NAMES)[number];
+
+/** Point-in-time ratios (spec.md §23.3). */
+export const RATIO_NAMES = ["resolved_import_ratio", "resolved_call_ratio"] as const;
+export type RatioName = (typeof RATIO_NAMES)[number];
+
+export interface HistogramSnapshot {
+  count: number;
+  sum: number;
+  min: number;
+  max: number;
+  avg: number;
+  p50: number;
+  p95: number;
+  p99: number;
+}
+
+export interface MetricsSnapshotV1 {
+  counters: Record<CounterName, number>;
+  histograms: Record<HistogramName, HistogramSnapshot>;
+  ratios: Record<RatioName, number | null>;
+}
+
+const EMPTY_HISTOGRAM: HistogramSnapshot = {
+  count: 0,
+  sum: 0,
+  min: 0,
+  max: 0,
+  avg: 0,
+  p50: 0,
+  p95: 0,
+  p99: 0,
+};
+
+/** Summarizes raw samples into a {@link HistogramSnapshot}. Pure, no state. */
+export function summarizeHistogram(samples: readonly number[]): HistogramSnapshot {
+  if (samples.length === 0) {
+    return EMPTY_HISTOGRAM;
+  }
+  const sorted = [...samples].sort((a, b) => a - b);
+  const sum = sorted.reduce((total, value) => total + value, 0);
+  return {
+    count: sorted.length,
+    sum,
+    min: sorted[0]!,
+    max: sorted[sorted.length - 1]!,
+    avg: sum / sorted.length,
+    p50: percentile(sorted, 0.5),
+    p95: percentile(sorted, 0.95),
+    p99: percentile(sorted, 0.99),
+  };
+}
+
+function percentile(sorted: readonly number[], fraction: number): number {
+  const index = Math.min(sorted.length - 1, Math.floor(fraction * sorted.length));
+  return sorted[index]!;
+}
+
+/** In-process registry for exactly the eleven counters of spec.md §23.3. */
+export class MetricsRegistry {
+  private readonly counters: Record<CounterName, number>;
+  private readonly samples: Record<HistogramName, number[]>;
+  private readonly ratios: Record<RatioName, number | null>;
+
+  public constructor() {
+    this.counters = fromNames(COUNTER_NAMES, () => 0);
+    this.samples = fromNames(HISTOGRAM_NAMES, () => [] as number[]);
+    this.ratios = fromNames(RATIO_NAMES, () => null);
+  }
+
+  /** Increments a counter by `delta` (default 1). `delta` must be finite and >= 0. */
+  public incrementCounter(name: CounterName, delta = 1): void {
+    if (!Number.isFinite(delta) || delta < 0) {
+      throw new RangeError(`counter delta must be a finite, non-negative number, got ${delta}`);
+    }
+    this.counters[name] += delta;
+  }
+
+  /** Records one observed latency (milliseconds) for a histogram. */
+  public observeHistogram(name: HistogramName, valueMs: number): void {
+    if (!Number.isFinite(valueMs) || valueMs < 0) {
+      throw new RangeError(`histogram value must be a finite, non-negative number, got ${valueMs}`);
+    }
+    this.samples[name].push(valueMs);
+  }
+
+  /** Sets the latest value of a ratio gauge. `null` clears it back to "unknown". */
+  public setRatio(name: RatioName, value: number | null): void {
+    if (value !== null && (!Number.isFinite(value) || value < 0 || value > 1)) {
+      throw new RangeError(`ratio must be null or within [0, 1], got ${value}`);
+    }
+    this.ratios[name] = value;
+  }
+
+  /** Point-in-time snapshot as a plain object — no external exporter. */
+  public snapshot(): MetricsSnapshotV1 {
+    return {
+      counters: { ...this.counters },
+      histograms: fromNames(HISTOGRAM_NAMES, (name) => summarizeHistogram(this.samples[name])),
+      ratios: { ...this.ratios },
+    };
+  }
+
+  /** Resets every counter, histogram and ratio back to its initial state. */
+  public reset(): void {
+    for (const name of COUNTER_NAMES) {
+      this.counters[name] = 0;
+    }
+    for (const name of HISTOGRAM_NAMES) {
+      this.samples[name] = [];
+    }
+    for (const name of RATIO_NAMES) {
+      this.ratios[name] = null;
+    }
+  }
+}
+
+function fromNames<Name extends string, Value>(
+  names: readonly Name[],
+  init: (name: Name) => Value,
+): Record<Name, Value> {
+  return Object.fromEntries(names.map((name) => [name, init(name)])) as Record<Name, Value>;
+}