@ultimat3/core 2.0.0 → 4.0.0

package/src/intl-cache.ts

@@ -0,0 +1,43 @@
+// One bounded cache, on one canonical key, for every `Intl` formatter the framework builds.
+// A locale and a zone both arrive from a request header, so an unbounded `Map` keyed on the
+// caller's spelling is memory the client chooses — 31 MB and 55.1 MB, measured `As of 2026-08` and
+// written up in the README. The bound and the canonical key are two halves of ONE rule.
+
+/**
+ * Above the full canonical IANA set (445 zones as of tzdata 2025) so a correct app never evicts,
+ * and small enough that the worst case is a few megabytes rather than a leak. A miss costs one
+ * `Intl` construction, never a wrong answer — which is what makes a bound safe here at all.
+ */
+export const MAX_CACHED_FORMATTERS = 512;
+
+/** FIFO — a `Map` iterates in insertion order, so the first key inserted is the first evicted. */
+export function cachedFormatter<T>(cache: Map<string, T>, key: string, build: () => T): T {
+  // Membership decides, never truthiness: `T` is the caller's, so a stored `undefined` is a hit.
+  // The cast is sound because `has` just proved the key is present, which `get`'s signature cannot.
+  if (cache.has(key)) return cache.get(key) as T;
+  const formatter = build();
+  if (cache.size >= MAX_CACHED_FORMATTERS) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined) cache.delete(oldest);
+  }
+  cache.set(key, formatter);
+  return formatter;
+}
+
+/**
+ * The canonical BCP 47 spelling, or `undefined` when the tag is not structurally valid at all
+ * (`en_US`, `''`, `not a locale`). Well-formed but unknown to ICU (`zz`) is a locale — `Intl`
+ * falls back for it, and refusing here would be stricter than the formatters this feeds.
+ *
+ * Deliberately **not** memoised: this is string work, and a `Map` keyed on a header value is the
+ * unbounded cache the bound above exists to prevent.
+ */
+export function canonicalLocale(locale: string): string | undefined {
+  try {
+    // `getCanonicalLocales` runs the same IsStructurallyValidLanguageTag check that
+    // `supportedLocalesOf` throws on, and unlike it, hands back the canonical spelling.
+    return Intl.getCanonicalLocales(locale)[0];
+  } catch {
+    return undefined;
+  }
+}

package/src/lifecycle.ts

@@ -6,7 +6,7 @@ import { type Clock, systemClock } from './clock';
 import { UltimateError } from './errors';
 import { settleWithin } from './lifecycle-deadline';
 import { lifecycleDrained } from './lifecycle-errors';
-import { type Logger, logger as rootLogger } from './logger';
+import { type LogFields, type Logger, logger as rootLogger } from './logger';
 
 export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
 
@@ -165,6 +165,33 @@ export function readinessCheckCount(): number {
   return readiness.size;
 }
 
+/**
+ * Every line this file emits, and the only way it emits one. `log` is an injection seam
+ * (`configureLifecycle({ logger })`), so an app's `Logger` decides whether a log call can throw —
+ * and a throw here does not lose a line, it replaces the event. Inside `drain()` it rejected
+ * `drainPromise`: `state` never reached 'stopped', the memo re-rejected for every later caller,
+ * and on Bun the unhandled rejection ended the process the drain was trying to end cleanly.
+ * Inside `readinessChecks()` it replaced the probe's answer with a throw.
+ *
+ * A lifecycle that cannot report is still a lifecycle: the line falls back to core's own
+ * `rootLogger`, which is total by construction (`logger.ts`), and failing that is dropped.
+ */
+function report(level: 'info' | 'warn' | 'error', message: string, fields: LogFields): void {
+  try {
+    log[level](message, fields);
+    return;
+  } catch {
+    // Fall through — the injected sink is gone, and the fallback below is the last one there is.
+  }
+  if (log === rootLogger) return;
+  try {
+    rootLogger[level](message, fields);
+  } catch {
+    // Both sinks are gone. Dropping the line is the only remaining option that still ends the
+    // process, which is the outcome every caller of this file depends on.
+  }
+}
+
 /** Every check, run now, by name. A check that throws is `failing` — never an unhandled error. */
 export function readinessChecks(): Readonly<Record<string, ReadinessStatus>> {
   const results: Record<string, ReadinessStatus> = {};
@@ -173,7 +200,7 @@ export function readinessChecks(): Readonly<Record<string, ReadinessStatus>> {
       results[name] = check() ? 'ok' : 'failing';
     } catch (thrown) {
       results[name] = 'failing';
-      log.warn('readiness check threw', { check: name, error: thrown });
+      report('warn', 'readiness check threw', { check: name, error: thrown });
     }
   }
   return results;
@@ -278,7 +305,7 @@ async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<v
   for (const registration of registrations.filter((entry) => entry.phase === phase)) {
     const outcome = await settleWithin(() => registration.hook(reason), remainingBudget(reason));
     if (outcome.kind === 'failed') {
-      log.error('shutdown hook failed', {
+      report('error', 'shutdown hook failed', {
         hook: registration.name,
         phase,
         error: outcome.error,
@@ -290,7 +317,7 @@ async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<v
       // SIGKILL this process — the every-deploy duplicate that draining exists to prevent — so
       // the drain moves on and the hook is left running with nobody reading it. The cost of that
       // choice is real and named in the cause: a write it had in flight may be half done.
-      log.warn('X_SHUTDOWN_TIMEOUT', {
+      report('warn', 'X_SHUTDOWN_TIMEOUT', {
         code: 'X_SHUTDOWN_TIMEOUT',
         cause: `the "${registration.name}" shutdown hook (phase: ${phase}) was still running at the ${deadlineMs}ms drain deadline and has been ABANDONED — the process exits without it, so anything it had in flight may be incomplete`,
         fix: `raise the budget past the work this hook does — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute job — and set terminationGracePeriodSeconds to at least as many seconds, or make the "${registration.name}" hook return once it has stopped accepting work rather than once it has finished`,
@@ -308,25 +335,34 @@ export function drain(signal = 'manual'): Promise<void> {
   const reason: ShutdownReason = { signal, deadlineAt: systemClock.monotonic() + deadlineMs };
 
   drainPromise = (async () => {
-    log.info('draining', { signal, deadlineMs, inflight });
-    await runPhase('accept', reason);
-
-    // Real monotonic, like `deadlineAt` itself: `waitForIdle` sleeps on a real `setTimeout`, and a
-    // budget read off an injected clock is a number that timer will never honour.
-    const remaining = Math.max(0, reason.deadlineAt - systemClock.monotonic());
-    const idle = await waitForIdle(remaining);
-    if (!idle) {
-      log.warn('X_SHUTDOWN_TIMEOUT', {
-        code: 'X_SHUTDOWN_TIMEOUT',
-        cause: `${inflight} in-flight operations still running after ${deadlineMs}ms`,
-        fix: 'raise the budget past the slowest handler — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute one — and set terminationGracePeriodSeconds to at least as many seconds, or shorten the handler',
-      });
+    try {
+      report('info', 'draining', { signal, deadlineMs, inflight });
+      await runPhase('accept', reason);
+
+      // Real monotonic, like `deadlineAt` itself: `waitForIdle` sleeps on a real `setTimeout`, and
+      // a budget read off an injected clock is a number that timer will never honour.
+      const remaining = Math.max(0, reason.deadlineAt - systemClock.monotonic());
+      const idle = await waitForIdle(remaining);
+      if (!idle) {
+        report('warn', 'X_SHUTDOWN_TIMEOUT', {
+          code: 'X_SHUTDOWN_TIMEOUT',
+          cause: `${inflight} in-flight operations still running after ${deadlineMs}ms`,
+          fix: 'raise the budget past the slowest handler — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute one — and set terminationGracePeriodSeconds to at least as many seconds, or shorten the handler',
+        });
+      }
+
+      await runPhase('inflight', reason);
+      await runPhase('close', reason);
+    } catch (thrown) {
+      // Nothing above should reach here — every hook is caught by `settleWithin` and every line
+      // goes through `report`. If something does, the drain still ENDS: a rejected `drainPromise`
+      // is a memo that re-rejects for every later caller and an unhandled rejection that kills the
+      // process mid-drain, which is strictly worse than a drain that finished badly and said so.
+      report('error', 'drain failed', { signal, error: thrown });
+    } finally {
+      state = 'stopped';
     }
-
-    await runPhase('inflight', reason);
-    await runPhase('close', reason);
-    state = 'stopped';
-    log.info('stopped', { signal });
+    report('info', 'stopped', { signal });
   })();
 
   return drainPromise;
@@ -345,9 +381,14 @@ export function installSignalHandlers(options?: SignalHandlerOptions): () => voi
 
   for (const signal of signals) {
     const handler = (): void => {
-      void drain(signal).then(() => {
+      // Attached on BOTH settle paths, for the reason `settleWithin` gives: an unhandled rejection
+      // ends the process before the drain does, and the exit is what the kubelet is waiting for.
+      // `drain()` cannot reject today — that is the `try/finally` above, not luck — and this is
+      // the one line that keeps it true when someone changes the body.
+      const done = (): void => {
         if (options?.exit === true) process.exit(0);
-      });
+      };
+      void drain(signal).then(done, done);
     };
     handlers.set(signal, handler);
     process.on(signal, handler);

package/src/logger.ts

@@ -10,6 +10,9 @@ import { isSecret, REDACTED } from './secret';
 // it without importing the logger, and two constants spelled the same is one rename from a leak.
 export { REDACTED } from './secret';
 
+/** What a `Date` this file cannot render says instead — the line survives, the value is named. */
+const INVALID_DATE = 'an invalid Date';
+
 export const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'silent'] as const;
 
 export type LogLevel = (typeof LOG_LEVELS)[number];
@@ -133,7 +136,7 @@ function serialise(value: unknown, depth: number): unknown {
   // `toISOString()` THROWS on an invalid Date, and an invalid Date is exactly the value worth
   // logging when a schedule went wrong.
   if (value instanceof Date) {
-    return Number.isNaN(value.getTime()) ? 'an invalid Date' : value.toISOString();
+    return Number.isNaN(value.getTime()) ? INVALID_DATE : value.toISOString();
   }
   if (isUltimateError(value)) return value.toJSON();
   if (value instanceof Error) return { name: value.name, message: value.message };
@@ -198,6 +201,22 @@ function renderLine(
   }
 }
 
+/**
+ * The one value in a line that is not the caller's, and it was the one read left unguarded:
+ * `toISOString()` raises `RangeError` on an invalid `Date`, and a `Clock` is injected — a frozen
+ * clock set from a bad string, or a clock whose `now()` throws, took the whole line with it. The
+ * same marker `serialise` gives an invalid `Date` in a FIELD, so one vocabulary covers both.
+ */
+function timestamp(clock: Clock): string {
+  try {
+    const at = clock.now();
+    if (at instanceof Date && !Number.isNaN(at.getTime())) return at.toISOString();
+  } catch {
+    // A clock that fights being read is exactly the moment a line is worth keeping.
+  }
+  return INVALID_DATE;
+}
+
 function envLevel(): LogLevel {
   const raw = process.env['LOG_LEVEL'];
   return raw !== undefined && (LOG_LEVELS as readonly string[]).includes(raw)
@@ -215,7 +234,7 @@ export function createLogger(options?: LoggerOptions): Logger {
   function emit(lineLevel: LogLevel, message: string, fields?: LogFields): void {
     if (LEVEL_WEIGHT[lineLevel] < threshold) return;
     const line = {
-      ts: clock.now().toISOString(),
+      ts: timestamp(clock),
       level: lineLevel,
       msg: message,
       ...redactFields(bound),

package/src/metrics-types.ts

@@ -0,0 +1,102 @@
+// Single responsibility: the OpenTelemetry-shaped metric DATA MODEL — what a point, a
+// descriptor, a collection and an instrument's options are. No registry and no state: `metrics.ts`
+// owns those, and a reader (`metrics-text.ts`, an exporter) needs the shapes without them.
+
+import type { SpanResource } from './telemetry';
+
+export type MetricKind = 'counter' | 'gauge' | 'histogram';
+
+/**
+ * Narrower than a span attribute on purpose: metric attributes become time-series labels, every
+ * distinct combination is a stored series, and an array label has no meaning in any exposition
+ * format. Keep the cardinality low — a user id here is an outage, and `maxSeries` is the ceiling
+ * that makes "keep it low" a mechanism instead of this sentence.
+ */
+export type MetricAttributeValue = string | number | boolean;
+
+export interface MetricAttributes {
+  readonly [key: string]: MetricAttributeValue;
+}
+
+export interface MetricDescriptor {
+  readonly name: string;
+  readonly kind: MetricKind;
+  /** UCUM, as OTel spells it: `1`, `s`, `By`, `{request}`. */
+  readonly unit: string;
+  readonly description: string;
+}
+
+export interface MetricPoint {
+  readonly attributes: MetricAttributes;
+  /** Counter: cumulative sum since process start. Gauge: last value. Histogram: sum. */
+  readonly value: number;
+}
+
+export interface HistogramPoint extends MetricPoint {
+  readonly count: number;
+  readonly min: number;
+  readonly max: number;
+  /** Explicit upper bounds; `buckets` is one longer, the last being the `+Inf` overflow. */
+  readonly bounds: readonly number[];
+  readonly buckets: readonly number[];
+}
+
+export interface ReadableMetric {
+  readonly descriptor: MetricDescriptor;
+  readonly points: readonly MetricPoint[];
+}
+
+export interface MetricCollection {
+  /** Epoch milliseconds, from the configured clock. */
+  readonly at: number;
+  readonly resource: SpanResource;
+  readonly metrics: readonly ReadableMetric[];
+}
+
+/** The driver seam. OTLP, Prometheus remote-write or a vendor SDK all arrive as one of these. */
+export interface MetricExporter {
+  export(collection: MetricCollection): void;
+}
+
+export interface Counter {
+  add(value?: number, attributes?: MetricAttributes): void;
+}
+
+export interface Gauge {
+  /** Set the current value. */
+  record(value: number, attributes?: MetricAttributes): void;
+  /** Move the current value — `+1` on connect, `-1` on disconnect. */
+  add(delta: number, attributes?: MetricAttributes): void;
+}
+
+export interface Histogram {
+  record(value: number, attributes?: MetricAttributes): void;
+}
+
+export interface InstrumentOptions {
+  readonly unit?: string | undefined;
+  readonly description?: string | undefined;
+  /**
+   * Distinct label sets this instrument may store. Past it every new set folds into one overflow
+   * series. Defaults to `DEFAULT_MAX_SERIES`; the first declaration of a name wins.
+   */
+  readonly maxSeries?: number | undefined;
+}
+
+export interface GaugeOptions extends InstrumentOptions {
+  /**
+   * Async instrument: read at collection time instead of being pushed. Never stale.
+   * Stated twice for one name with two different callbacks is `X_METRIC_NAME_INVALID`, not a
+   * silent win for the first — see `assertSameDeclaration`.
+   */
+  readonly observe?: (() => number) | undefined;
+}
+
+export interface HistogramOptions extends InstrumentOptions {
+  /**
+   * Explicit bucket boundaries, ascending. Defaults to the OTel latency-in-seconds set.
+   * Stated twice for one name with two different sets is `X_METRIC_NAME_INVALID`, not a silent
+   * win for the first — see `assertSameDeclaration`.
+   */
+  readonly bounds?: readonly number[] | undefined;
+}

package/src/metrics.ts

@@ -3,9 +3,44 @@
 // always on, a no-op exporter by default, and the wire format supplied by a driver, never here.
 
 import { type Clock, systemClock } from './clock';
+import { renderThrowable } from './error-render';
 import { type CodedErrorInit, UltimateError } from './errors';
 import { logger } from './logger';
-import { type SpanResource, serviceResource } from './telemetry';
+import type {
+  Counter,
+  Gauge,
+  GaugeOptions,
+  Histogram,
+  HistogramOptions,
+  InstrumentOptions,
+  MetricAttributes,
+  MetricCollection,
+  MetricDescriptor,
+  MetricExporter,
+  MetricKind,
+  MetricPoint,
+} from './metrics-types';
+import { serviceResource } from './telemetry';
+
+// The data model is a module of its own; the public surface is unchanged, so nothing that imports
+// a metric type from here has to learn a second path.
+export type {
+  Counter,
+  Gauge,
+  GaugeOptions,
+  Histogram,
+  HistogramOptions,
+  HistogramPoint,
+  InstrumentOptions,
+  MetricAttributes,
+  MetricAttributeValue,
+  MetricCollection,
+  MetricDescriptor,
+  MetricExporter,
+  MetricKind,
+  MetricPoint,
+  ReadableMetric,
+} from './metrics-types';
 
 export class MetricNameInvalidError extends UltimateError {
   static readonly code = 'X_METRIC_NAME_INVALID';
@@ -31,95 +66,6 @@ export class MetricCardinalityError extends UltimateError {
   }
 }
 
-export type MetricKind = 'counter' | 'gauge' | 'histogram';
-
-/**
- * Narrower than a span attribute on purpose: metric attributes become time-series labels, every
- * distinct combination is a stored series, and an array label has no meaning in any exposition
- * format. Keep the cardinality low — a user id here is an outage, and `maxSeries` is the ceiling
- * that makes "keep it low" a mechanism instead of this sentence.
- */
-export type MetricAttributeValue = string | number | boolean;
-
-export interface MetricAttributes {
-  readonly [key: string]: MetricAttributeValue;
-}
-
-export interface MetricDescriptor {
-  readonly name: string;
-  readonly kind: MetricKind;
-  /** UCUM, as OTel spells it: `1`, `s`, `By`, `{request}`. */
-  readonly unit: string;
-  readonly description: string;
-}
-
-export interface MetricPoint {
-  readonly attributes: MetricAttributes;
-  /** Counter: cumulative sum since process start. Gauge: last value. Histogram: sum. */
-  readonly value: number;
-}
-
-export interface HistogramPoint extends MetricPoint {
-  readonly count: number;
-  readonly min: number;
-  readonly max: number;
-  /** Explicit upper bounds; `buckets` is one longer, the last being the `+Inf` overflow. */
-  readonly bounds: readonly number[];
-  readonly buckets: readonly number[];
-}
-
-export interface ReadableMetric {
-  readonly descriptor: MetricDescriptor;
-  readonly points: readonly MetricPoint[];
-}
-
-export interface MetricCollection {
-  /** Epoch milliseconds, from the configured clock. */
-  readonly at: number;
-  readonly resource: SpanResource;
-  readonly metrics: readonly ReadableMetric[];
-}
-
-/** The driver seam. OTLP, Prometheus remote-write or a vendor SDK all arrive as one of these. */
-export interface MetricExporter {
-  export(collection: MetricCollection): void;
-}
-
-export interface Counter {
-  add(value?: number, attributes?: MetricAttributes): void;
-}
-
-export interface Gauge {
-  /** Set the current value. */
-  record(value: number, attributes?: MetricAttributes): void;
-  /** Move the current value — `+1` on connect, `-1` on disconnect. */
-  add(delta: number, attributes?: MetricAttributes): void;
-}
-
-export interface Histogram {
-  record(value: number, attributes?: MetricAttributes): void;
-}
-
-export interface InstrumentOptions {
-  readonly unit?: string | undefined;
-  readonly description?: string | undefined;
-  /**
-   * Distinct label sets this instrument may store. Past it every new set folds into one overflow
-   * series. Defaults to `DEFAULT_MAX_SERIES`; the first declaration of a name wins.
-   */
-  readonly maxSeries?: number | undefined;
-}
-
-export interface GaugeOptions extends InstrumentOptions {
-  /** Async instrument: read at collection time instead of being pushed. Never stale. */
-  readonly observe?: (() => number) | undefined;
-}
-
-export interface HistogramOptions extends InstrumentOptions {
-  /** Explicit bucket boundaries, ascending. Defaults to the OTel latency-in-seconds set. */
-  readonly bounds?: readonly number[] | undefined;
-}
-
 /**
  * The per-instrument series ceiling. 2000 is roomy for a bounded label set — every route pattern
  * times every status class times every method — and small enough that the process notices an
@@ -196,6 +142,8 @@ interface Instrument {
   readonly maxSeries: number;
   /** Reported once. A cardinality blow-up is one bug, not one log line per call. */
   overflowed: boolean;
+  /** Reported once, for the same reason: a scrape every 15s must not become a log every 15s. */
+  observeFailed: boolean;
 }
 
 const instruments = new Map<string, Instrument>();
@@ -222,6 +170,7 @@ export function resetMetrics(): void {
   for (const instrument of instruments.values()) {
     instrument.series.clear();
     instrument.overflowed = false;
+    instrument.observeFailed = false;
   }
 }
 
@@ -263,6 +212,7 @@ function declare(name: string, kind: MetricKind, options: GaugeOptions & Histogr
         meta: { name, declared: existing.descriptor.kind, requested: kind },
       });
     }
+    assertSameDeclaration(name, existing, options);
     return existing;
   }
   const maxSeries = options.maxSeries ?? DEFAULT_MAX_SERIES;
@@ -285,11 +235,45 @@ function declare(name: string, kind: MetricKind, options: GaugeOptions & Histogr
     observe: options.observe,
     maxSeries,
     overflowed: false,
+    observeFailed: false,
   };
   instruments.set(name, instrument);
   return instrument;
 }
 
+/**
+ * A second declaration that STATES a different shape is refused. The first declaration wins, so a
+ * second `histogram(name, { bounds })` recorded into buckets another module chose and a second
+ * `gauge(name, { observe })` was collected through the first module's observer — silently, in both
+ * cases, which is the whole failure. An OMITTED option is not a conflict: `gauge(name)` is how a
+ * module takes a handle on an instrument someone else declared, and `maxSeries` keeps its shipped
+ * first-declaration-wins rule because it decides a ceiling rather than what gets recorded.
+ */
+function assertSameDeclaration(
+  name: string,
+  existing: Instrument,
+  options: GaugeOptions & HistogramOptions,
+): void {
+  const { bounds, observe } = options;
+  if (bounds !== undefined && !sameBounds(existing.bounds, bounds)) {
+    throw new MetricNameInvalidError({
+      cause: `"${name}" is already declared with bounds [${existing.bounds.join(', ')}] and is redeclared with [${bounds.join(', ')}]; the first declaration wins, so the second set would never be used`,
+      fix: `declare "${name}" once and export the handle — import it where you record — or give the second instrument its own name`,
+      meta: { name, declared: existing.bounds.join(','), requested: bounds.join(',') },
+    });
+  }
+  if (observe !== undefined && observe !== existing.observe) {
+    throw new MetricNameInvalidError({
+      cause: `"${name}" is already declared with an observe() callback and is redeclared with a different one; the first declaration wins, so the second callback would never be read`,
+      fix: `declare "${name}" once and export the handle — import it where you read — or give the second gauge its own name`,
+      meta: { name },
+    });
+  }
+}
+
+const sameBounds = (left: readonly number[], right: readonly number[]): boolean =>
+  left.length === right.length && left.every((bound, index) => bound === right[index]);
+
 /**
  * Reported through the logger rather than thrown: the call site is `orderCounter.add(1, …)` deep
  * inside a request, and killing that request would turn a metrics bug into a user-visible outage
@@ -308,6 +292,26 @@ function reportOverflow(instrument: Instrument): void {
   logger.error(error.format(), { code: error.code, metric: name });
 }
 
+/**
+ * Reported through the logger for `reportOverflow`'s reason and once for the same one — a scrape
+ * runs on a timer, so a permanently broken observer would otherwise write a log line every
+ * interval forever. A recurrence after the first is therefore silent by design; the missing series
+ * is the signal that outlives the line.
+ */
+function reportObserveFailure(instrument: Instrument, thrown: unknown): void {
+  if (instrument.observeFailed) return;
+  instrument.observeFailed = true;
+  const { name, kind } = instrument.descriptor;
+  const error = new MetricValueInvalidError({
+    // `renderThrowable`, never `${thrown}`: the value is whatever the app's callback threw, and a
+    // `.message` read on it is the one that throws where there is nothing left to answer with.
+    cause: `the observe() callback of ${name} did not produce a value: ${renderThrowable(thrown)}; this instrument contributes no point until it does`,
+    fix: `make the observe() callback of ${name} total — return a finite number when the resource it reads is gone, e.g. ${kind}('${name}', { observe: () => pool?.size ?? 0 })`,
+    meta: { metric: name },
+  });
+  logger.error(error.format(), { code: error.code, metric: name });
+}
+
 function createSeries(instrument: Instrument, key: string, attributes: MetricAttributes): Series {
   const created: Series = {
     attributes,
@@ -391,8 +395,19 @@ export function histogram(name: string, options?: HistogramOptions): Histogram {
 }
 
 function pointsOf(instrument: Instrument): readonly MetricPoint[] {
-  if (instrument.observe !== undefined) {
-    return [{ attributes: {}, value: instrument.observe() }];
+  const observe = instrument.observe;
+  if (observe !== undefined) {
+    try {
+      return [{ attributes: {}, value: finite(instrument.descriptor.name, observe()) }];
+    } catch (thrown) {
+      // The callback is the app's, run at SCRAPE time with no call site to blame: `() => pool.size`
+      // after a drain throws, and an unguarded read here took every other instrument down with it
+      // — /metrics 500s, `http_requests_total` goes invisible, and `startMetricExport`'s timer
+      // callback raises where nothing can catch it. One hostile observer costs its own point only,
+      // the same degradation `readinessChecks()` and the logger's per-key walk already make.
+      reportObserveFailure(instrument, thrown);
+      return [];
+    }
   }
   return [...instrument.series.values()].map((series) =>
     instrument.descriptor.kind === 'histogram'

package/src/otlp-metric-exporter.ts

@@ -1,6 +1,8 @@
 // Single responsibility: a `MetricExporter` that POSTs OTLP/HTTP JSON to a collector. No batching
 // — `collectMetrics()` already produces one whole snapshot per tick, so a tick is a request.
 
+import { renderThrowable } from './error-render';
+import { logger } from './logger';
 import type {
   HistogramPoint,
   MetricCollection,
@@ -124,10 +126,31 @@ export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): Otl
   return {
     export(collection: MetricCollection): void {
       startedAtMs ??= collection.at;
-      const body = JSON.stringify(otlpMetricsRequest(collection, startedAtMs));
+      let body: string;
+      try {
+        // `export` is called from a timer, not awaited by anyone, so this throw had nowhere to go
+        // but into the metric loop that called it: `MetricAttributeValue` is a compile-time claim,
+        // and an attribute the app spelled as an object or a bigint reaches `otlpAttributes` as a
+        // TypeError. Dropped with a line, the same degradation `postOtlp` already applies to a
+        // collector that is down — telemetry is best-effort and must never end the process.
+        body = JSON.stringify(otlpMetricsRequest(collection, startedAtMs));
+      } catch (failure) {
+        logger.warn('otlp metric snapshot dropped', {
+          url,
+          metrics: collection.metrics.length,
+          error: renderThrowable(failure),
+        });
+        return;
+      }
       // Chained, so a slow collector cannot make two snapshots arrive out of order and turn a
-      // cumulative counter into an apparent reset.
-      inflight = inflight.then(() => postOtlp({ url, headers, body, timeoutMs, fetch: send }));
+      // cumulative counter into an apparent reset. Chained on a SETTLED shadow, for the reason
+      // `otlp-span-exporter.ts` spells out: a chain that carries a rejection forward stops calling
+      // `postOtlp` for the life of the process, in silence.
+      const settled = inflight.then(
+        () => undefined,
+        () => undefined,
+      );
+      inflight = settled.then(() => postOtlp({ url, headers, body, timeoutMs, fetch: send }));
     },
     flush(): Promise<void> {
       return inflight;