@open-mercato/telemetry 0.7.1-develop.7182.1.789943f937 → 0.7.1-develop.7185.1.0f280ef1f1

package/AGENTS.md

@@ -29,6 +29,24 @@ off by default. Spec:
 - Keep metric labels low-cardinality. Tenant, organization, and user IDs belong
   on span attributes, never metric labels.
 - Apply redaction at the provider boundary as well as at facade call sites.
+- Report every recorded error: a `catch` that does anything other than rethrow
+  (persists a row, sets a `failed` status, dead-letters an item, returns a
+  fallback) MUST also reach `reportError` — directly, or through a chokepoint that
+  does (`integrationLogService.write` at `level: 'error'`, the queue failure
+  paths). `logger.error` alone does NOT satisfy this: no span exception, no
+  `om.errors` sample, no fingerprint. Full policy:
+  `apps/docs/docs/framework/runtime/error-reporting.mdx`.
+- Pass `code` on every `reportError` call: a stable, enumerated `module.reason`
+  token, never an interpolated string. It is a metric label and the fingerprint
+  backends group on — ids go in `attributes`. The funnel narrows it through
+  `groupableCode` from `@open-mercato/shared/lib/telemetry/error-code` and DROPS
+  anything off-shape, because metric labels skip redaction; a chokepoint taking a
+  `code` from outside the framework (an adapter's `data.errorCode`, a module's
+  `integrationLogService.write({ code })`) narrows it with its OWN fallback first,
+  so the error still lands in a group rather than none.
+- Put the CAUSE in the reported message. A constant message with the reason only
+  in `payload` reports an error nobody can act on, because the payload stays in
+  the database.
 
 ## Ask First
 
@@ -43,6 +61,14 @@ off by default. Spec:
 
 - Never emit PII, credentials, record content, SQL parameters, request bodies,
   or arbitrary thrown-object properties.
+  The integration-log tee reports a row's message, `code` and ids only —
+  `integration_logs.payload` never leaves the database.
+- Never add sampling, throttling or suppression to `reportError`. Volume belongs
+  to the collector and the backend, which drop where the drop is visible; a
+  facade-level limiter is the only one that loses an error at the source.
+- Never call a provider-supplied hook unguarded from the facade. `reportError`
+  runs inside `catch` blocks that still have to rethrow or return a 500, so a
+  third-party sink that throws must degrade to a warning, not escape.
 - Never trust `traceparent` or `x-original-traceparent` at an inbound/global
   boundary unless `TELEMETRY_TRUST_INBOUND_TRACE=true`.
 - Never store provider, shared-logger extension, or runtime bridge state only in

package/README.md

@@ -128,7 +128,7 @@ bridge, so the package is not loaded on the disabled path.
 | `withSpan(name, fn, opts?)` | Run `fn` in a provider-owned span. `opts.root` starts a new trace; `opts.links` attaches causal links (see [Long-lived jobs](#long-lived-jobs-root-spans)) |
 | `currentSpan()` / `setAttributes(attrs)` | Active span access |
 | `counter` / `histogram` / `gauge` | Metric helpers |
-| `reportError(err, ctx?)` | Span exception + shared error log + `om.errors` |
+| `reportError(err, ctx?)` | Span exception + shared error log + `om.errors{module, error.code}` + the provider's own error sink. Pass `ctx.code` — see [Error reporting](#error-reporting) |
 | `captureTraceContext()` / `continueTrace(...)` | Dedicated cross-boundary propagation |
 | `initTelemetry()` / `shutdownTelemetry()` | Opt-in bootstrap and flush |
 | `registerProvider(provider)` | Register a custom provider for an enabled backend name |
@@ -138,6 +138,74 @@ bridge, so the package is not loaded on the disabled path.
 `@open-mercato/telemetry/nextjs-config` separately exports only
 `telemetryServerExternalPackages` for build configuration.
 
+### Error reporting
+
+`reportError` is the error funnel, and the policy around it is one rule:
+**recording an error is not reporting it.** A `catch` that persists a row, sets a
+`failed` status or dead-letters an item MUST also report — `logger.error` alone
+gives you a log record with no span exception, no `om.errors` sample and no
+fingerprint.
+
+```ts
+reportError(error, {
+  module: 'data_sync',
+  code: 'data_sync.item_failed',   // stable, enumerated `module.reason`
+  attributes: { runId, integrationId },
+})
+```
+
+`code` is a metric label and the key backends group on, so it MUST NOT be
+interpolated (`` `failed for ${id}` `` breaks grouping and metric cardinality —
+ids go in `attributes`). Every reported error is emitted: this facade adds no
+sampling or throttling, because the collector and the backend already own volume
+and drop it where an operator can see and adjust the drop.
+
+The full policy, the framework chokepoints that report for you, and the
+verification recipe live in
+`apps/docs/docs/framework/runtime/error-reporting.mdx`.
+
+#### A provider with its own error sink (Sentry-shaped backends)
+
+`TelemetryProvider.reportError?()` is optional and called **in addition to** the
+span/log/metric path, so implementing it can never make signal disappear — the
+provider owns its own de-duplication. Nothing vendor-specific ships upstream;
+plug it in from your app's bootstrap:
+
+```ts
+import { registerProvider, initTelemetry } from '@open-mercato/telemetry'
+import type { TelemetryProvider } from '@open-mercato/telemetry'
+
+const sentryProvider: TelemetryProvider = {
+  ...tracingDelegate,            // reuse an OTLP/console provider for spans, or no-op them
+  name: 'sentry',                // must equal TELEMETRY_BACKEND
+  supports: ['errors', 'logs'],
+  reportError(error, { module, code, attributes }) {
+    Sentry.captureException(new Error(error.message), {
+      fingerprint: code ? [code] : undefined,
+      tags: { module, code },
+      extra: attributes,
+    })
+  },
+}
+
+registerProvider(sentryProvider)
+await initTelemetry()
+```
+
+`error` arrives serialized and PII-redacted (name, message, stack) and
+`attributes` already redacted — never reach for the original thrown value.
+
+**The hook MUST NOT throw.** `reportError` is called from `catch` blocks that
+still have work to do after it — rethrowing the original error, returning a 500
+with its correlation header — so a hook that throws would replace the caller's
+error with yours. The facade wraps the call and degrades a throwing hook to a
+warning, but do not rely on that: swallow your SDK's failures inside the
+implementation, where you can decide what a dropped report means.
+
+`code` reaches your hook as `context.code`. It is deliberately **not** repeated in
+`attributes`, so putting it in both `tags` and `extra`, as the snippet above does
+with `tags`, is your choice rather than an accident of the payload.
+
 ### Long-lived jobs: root spans
 
 Trace context propagates from the request that triggered a job through the queue

package/dist/facade/report-error.js

@@ -1,24 +1,56 @@
 import { createLogger } from "@open-mercato/shared/lib/logger";
+import { groupableCode } from "@open-mercato/shared/lib/telemetry/error-code";
 import { currentSpan } from "./tracer.js";
 import { serializeError } from "./serialize.js";
 import { counter } from "./meter.js";
 import { redactAttributes } from "./redact.js";
+import { getActiveProvider } from "../provider/registry.js";
 const logger = createLogger("telemetry");
+const CODE_ATTRIBUTE = "error.code";
+let reporting = false;
 function reportError(error, ctx) {
-  const span = currentSpan();
-  if (span) {
-    span.recordException(error);
-    span.setStatus("error");
+  if (reporting) return;
+  reporting = true;
+  try {
+    const code = groupableCode(ctx?.code);
+    const span = currentSpan();
+    if (span) {
+      span.recordException(error);
+      span.setStatus("error");
+      if (code) span.setAttribute(CODE_ATTRIBUTE, code);
+    }
+    const serialized = serializeError(error);
+    const attributes = { ...ctx?.attributes ?? {} };
+    if (ctx?.module) attributes.module = ctx.module;
+    if (code) attributes[CODE_ATTRIBUTE] = code;
+    const safeAttributes = redactAttributes(attributes);
+    const safeError = new Error(serialized.message);
+    safeError.name = serialized.name;
+    safeError.stack = serialized.stack;
+    logger.error("Application error reported", { ...safeAttributes, err: safeError });
+    counter("om.errors", 1, errorLabels(ctx?.module, code));
+    reportToProvider(serialized, ctx?.module, code, safeAttributes);
+  } finally {
+    reporting = false;
   }
-  const serialized = serializeError(error);
-  const attributes = { ...ctx?.attributes ?? {} };
-  if (ctx?.module) attributes.module = ctx.module;
-  const safeAttributes = redactAttributes(attributes);
-  const safeError = new Error(serialized.message);
-  safeError.name = serialized.name;
-  safeError.stack = serialized.stack;
-  logger.error("Application error reported", { ...safeAttributes, err: safeError });
-  counter("om.errors", 1, ctx?.module ? { module: ctx.module } : void 0);
+}
+function reportToProvider(serialized, module, code, safeAttributes) {
+  try {
+    const provider = getActiveProvider();
+    if (!provider.reportError) return;
+    const providerAttributes = { ...safeAttributes };
+    delete providerAttributes[CODE_ATTRIBUTE];
+    provider.reportError(serialized, { module, code, attributes: providerAttributes });
+  } catch (sinkError) {
+    logger.warn("Telemetry provider error sink failed", { err: sinkError });
+  }
+}
+function errorLabels(module, code) {
+  if (!module && !code) return void 0;
+  const labels = {};
+  if (module) labels.module = module;
+  if (code) labels[CODE_ATTRIBUTE] = code;
+  return labels;
 }
 export {
   reportError

package/dist/facade/report-error.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/facade/report-error.ts"],
-  "sourcesContent": ["import type { Attributes } from '../types'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { currentSpan } from './tracer'\nimport { serializeError } from './serialize'\nimport { counter } from './meter'\nimport { redactAttributes } from './redact'\n\nconst logger = createLogger('telemetry')\n\nexport type ReportErrorContext = {\n  /** Owning module, e.g. 'orders'. Used as the only metric label. */\n  module?: string\n  /** Low-cardinality, NO-PII attributes (ids ok, never names/content). */\n  attributes?: Attributes\n}\n\n/**\n * The error funnel. Additive \u2014 existing `console.error` calls stay valid; this\n * is the path that reaches the active backend. It:\n *   1. records the exception on the active span (errors-as-span-events),\n *   2. emits a structured error log (stack only \u2014 no PII payloads),\n *   3. increments the `om.errors` counter, labeled by `module` only.\n */\nexport function reportError(error: unknown, ctx?: ReportErrorContext): void {\n  const span = currentSpan()\n  if (span) {\n    span.recordException(error)\n    span.setStatus('error')\n  }\n\n  const serialized = serializeError(error)\n  const attributes: Attributes = { ...(ctx?.attributes ?? {}) }\n  if (ctx?.module) attributes.module = ctx.module\n  const safeAttributes = redactAttributes(attributes)\n\n  const safeError = new Error(serialized.message)\n  safeError.name = serialized.name\n  safeError.stack = serialized.stack\n  logger.error('Application error reported', { ...safeAttributes, err: safeError })\n  counter('om.errors', 1, ctx?.module ? { module: ctx.module } : undefined)\n}\n"],
-  "mappings": "AACA,SAAS,oBAAoB;AAC7B,SAAS,mBAAmB;AAC5B,SAAS,sBAAsB;AAC/B,SAAS,eAAe;AACxB,SAAS,wBAAwB;AAEjC,MAAM,SAAS,aAAa,WAAW;AAgBhC,SAAS,YAAY,OAAgB,KAAgC;AAC1E,QAAM,OAAO,YAAY;AACzB,MAAI,MAAM;AACR,SAAK,gBAAgB,KAAK;AAC1B,SAAK,UAAU,OAAO;AAAA,EACxB;AAEA,QAAM,aAAa,eAAe,KAAK;AACvC,QAAM,aAAyB,EAAE,GAAI,KAAK,cAAc,CAAC,EAAG;AAC5D,MAAI,KAAK,OAAQ,YAAW,SAAS,IAAI;AACzC,QAAM,iBAAiB,iBAAiB,UAAU;AAElD,QAAM,YAAY,IAAI,MAAM,WAAW,OAAO;AAC9C,YAAU,OAAO,WAAW;AAC5B,YAAU,QAAQ,WAAW;AAC7B,SAAO,MAAM,8BAA8B,EAAE,GAAG,gBAAgB,KAAK,UAAU,CAAC;AAChF,UAAQ,aAAa,GAAG,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,MAAS;AAC1E;",
+  "sourcesContent": ["import type { Attributes, LogRecord } from '../types'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { groupableCode } from '@open-mercato/shared/lib/telemetry/error-code'\nimport { currentSpan } from './tracer'\nimport { serializeError } from './serialize'\nimport { counter } from './meter'\nimport { redactAttributes } from './redact'\nimport { getActiveProvider } from '../provider/registry'\n\nconst logger = createLogger('telemetry')\n\n/**\n * The single attribute name the code is published under, on all three built-in\n * surfaces. One spelling, so a query written against the span also works against\n * the log record and the metric.\n */\nconst CODE_ATTRIBUTE = 'error.code'\n\nexport type ReportErrorContext = {\n  /** Owning module, e.g. 'orders'. Used as a metric label. */\n  module?: string\n  /**\n   * Stable, enumerated fingerprint for this failure reason, as `module.reason`\n   * (`data_sync.item_failed`, `queue.job_failed`). NEVER an interpolated string:\n   * it is a metric label, and it is what the backend groups on. A value that is\n   * not that shape is dropped here rather than published \u2014 see `groupableCode`.\n   *\n   * Grouping is why this exists. Sentry fingerprints on the stack trace and New\n   * Relic on the error class, so a funnel that synthesizes one error type at one\n   * line \u2014 the integration-log tee \u2014 collapses every caller into a single issue\n   * without a discriminator, and SigNoz has no error grouping of its own at all.\n   */\n  code?: string\n  /** Low-cardinality, NO-PII attributes (ids ok, never names/content). */\n  attributes?: Attributes\n}\n\n/**\n * Re-entrancy guard, not a rate limit. A plain module-level flag, which is\n * sufficient only because `reportError` runs synchronously end to end: a nested\n * call can therefore come from nothing but the reporting path itself \u2014 a provider\n * whose error sink reports its own failures, a log bridge that reports. One flag\n * turns that recursion into a no-op while keeping the original report intact. Add\n * an `await` anywhere in this funnel and the flag has to become async-context\n * scoped, or concurrent reports will suppress each other.\n *\n * Volume is deliberately NOT policed here: the backend (quotas, spike\n * protection), the collector (filter/sample processors) and the SDK's batch\n * processors already bound it, and each of them drops where the drop is visible\n * and adjustable. A fourth limiter in this function would be the only one that\n * loses an error irrecoverably at the source.\n */\nlet reporting = false\n\n/**\n * The error funnel. Additive \u2014 existing `console.error` calls stay valid; this\n * is the path that reaches the active backend. It:\n *   1. records the exception on the active span (errors-as-span-events),\n *   2. emits a structured error log (stack only \u2014 no PII payloads),\n *   3. increments the `om.errors` counter, labeled by `module` and `error.code`,\n *   4. hands the serialized error to the provider's own error sink when it has\n *      one (issue-tracker-shaped backends), in ADDITION to the three above so no\n *      path can lose signal.\n *\n * Every reported error is emitted; there is no sampling or suppression here.\n */\nexport function reportError(error: unknown, ctx?: ReportErrorContext): void {\n  if (reporting) return\n  reporting = true\n  try {\n    // Narrowed once, here, rather than at each caller: the property being\n    // protected \u2014 a metric label is bounded and never redacted \u2014 belongs to this\n    // funnel, and `code` reaches it from adapters and third-party modules. A\n    // caller with a malformed code reports exactly as one with no code at all.\n    const code = groupableCode(ctx?.code)\n    const span = currentSpan()\n    if (span) {\n      span.recordException(error)\n      span.setStatus('error')\n      // Span-level, because `recordException` takes no attributes. With several\n      // reports on one span the last code wins; the per-error code always\n      // survives on the log record and the metric.\n      if (code) span.setAttribute(CODE_ATTRIBUTE, code)\n    }\n\n    const serialized = serializeError(error)\n    const attributes: Attributes = { ...(ctx?.attributes ?? {}) }\n    if (ctx?.module) attributes.module = ctx.module\n    if (code) attributes[CODE_ATTRIBUTE] = code\n    const safeAttributes = redactAttributes(attributes)\n\n    const safeError = new Error(serialized.message)\n    safeError.name = serialized.name\n    safeError.stack = serialized.stack\n    logger.error('Application error reported', { ...safeAttributes, err: safeError })\n    counter('om.errors', 1, errorLabels(ctx?.module, code))\n\n    reportToProvider(serialized, ctx?.module, code, safeAttributes)\n  } finally {\n    reporting = false\n  }\n}\n\n/**\n * Hand the error to the provider's own sink, when it has one.\n *\n * Guarded, and that is the whole point of the function: `reportError` is called\n * from `catch` blocks that still have work to do after it \u2014 the API dispatcher\n * records a duration metric, emits its lifecycle event and rethrows the original\n * error; the CRUD factory returns a 500 carrying its `x-request-id`. This hook is\n * implemented by third parties, so one that throws would take all of that with it\n * and replace the caller's error with the telemetry provider's. The interface\n * documents the hook as non-throwing; this is what makes that a property of the\n * funnel rather than a request to its implementors.\n */\nfunction reportToProvider(\n  serialized: NonNullable<LogRecord['error']>,\n  module: string | undefined,\n  code: string | undefined,\n  safeAttributes: Attributes,\n): void {\n  try {\n    const provider = getActiveProvider()\n    if (!provider.reportError) return\n    // `code` travels in the context. Repeating it in the attributes would land it\n    // in a provider's tags AND its extra data for anyone following the README recipe.\n    const providerAttributes: Attributes = { ...safeAttributes }\n    delete providerAttributes[CODE_ATTRIBUTE]\n    provider.reportError(serialized, { module, code, attributes: providerAttributes })\n  } catch (sinkError) {\n    logger.warn('Telemetry provider error sink failed', { err: sinkError as Error })\n  }\n}\n\nfunction errorLabels(module?: string, code?: string): Attributes | undefined {\n  if (!module && !code) return undefined\n  const labels: Attributes = {}\n  if (module) labels.module = module\n  if (code) labels[CODE_ATTRIBUTE] = code\n  return labels\n}\n"],
+  "mappings": "AACA,SAAS,oBAAoB;AAC7B,SAAS,qBAAqB;AAC9B,SAAS,mBAAmB;AAC5B,SAAS,sBAAsB;AAC/B,SAAS,eAAe;AACxB,SAAS,wBAAwB;AACjC,SAAS,yBAAyB;AAElC,MAAM,SAAS,aAAa,WAAW;AAOvC,MAAM,iBAAiB;AAoCvB,IAAI,YAAY;AAcT,SAAS,YAAY,OAAgB,KAAgC;AAC1E,MAAI,UAAW;AACf,cAAY;AACZ,MAAI;AAKF,UAAM,OAAO,cAAc,KAAK,IAAI;AACpC,UAAM,OAAO,YAAY;AACzB,QAAI,MAAM;AACR,WAAK,gBAAgB,KAAK;AAC1B,WAAK,UAAU,OAAO;AAItB,UAAI,KAAM,MAAK,aAAa,gBAAgB,IAAI;AAAA,IAClD;AAEA,UAAM,aAAa,eAAe,KAAK;AACvC,UAAM,aAAyB,EAAE,GAAI,KAAK,cAAc,CAAC,EAAG;AAC5D,QAAI,KAAK,OAAQ,YAAW,SAAS,IAAI;AACzC,QAAI,KAAM,YAAW,cAAc,IAAI;AACvC,UAAM,iBAAiB,iBAAiB,UAAU;AAElD,UAAM,YAAY,IAAI,MAAM,WAAW,OAAO;AAC9C,cAAU,OAAO,WAAW;AAC5B,cAAU,QAAQ,WAAW;AAC7B,WAAO,MAAM,8BAA8B,EAAE,GAAG,gBAAgB,KAAK,UAAU,CAAC;AAChF,YAAQ,aAAa,GAAG,YAAY,KAAK,QAAQ,IAAI,CAAC;AAEtD,qBAAiB,YAAY,KAAK,QAAQ,MAAM,cAAc;AAAA,EAChE,UAAE;AACA,gBAAY;AAAA,EACd;AACF;AAcA,SAAS,iBACP,YACA,QACA,MACA,gBACM;AACN,MAAI;AACF,UAAM,WAAW,kBAAkB;AACnC,QAAI,CAAC,SAAS,YAAa;AAG3B,UAAM,qBAAiC,EAAE,GAAG,eAAe;AAC3D,WAAO,mBAAmB,cAAc;AACxC,aAAS,YAAY,YAAY,EAAE,QAAQ,MAAM,YAAY,mBAAmB,CAAC;AAAA,EACnF,SAAS,WAAW;AAClB,WAAO,KAAK,wCAAwC,EAAE,KAAK,UAAmB,CAAC;AAAA,EACjF;AACF;AAEA,SAAS,YAAY,QAAiB,MAAuC;AAC3E,MAAI,CAAC,UAAU,CAAC,KAAM,QAAO;AAC7B,QAAM,SAAqB,CAAC;AAC5B,MAAI,OAAQ,QAAO,SAAS;AAC5B,MAAI,KAAM,QAAO,cAAc,IAAI;AACnC,SAAO;AACT;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/telemetry",
-  "version": "0.7.1-develop.7182.1.789943f937",
+  "version": "0.7.1-develop.7185.1.0f280ef1f1",
   "description": "Vendor-neutral spans, metrics, and error reporting backed by a pluggable OTLP provider. Off by default; the telemetry runtime is loaded only when explicitly enabled.",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,7 @@
     }
   },
   "dependencies": {
-    "@open-mercato/shared": "0.7.1-develop.7182.1.789943f937"
+    "@open-mercato/shared": "0.7.1-develop.7185.1.0f280ef1f1"
   },
   "optionalDependencies": {
     "@opentelemetry/api": "^1.9.1",

package/src/__tests__/report-error.test.ts

@@ -0,0 +1,242 @@
+import { reportError } from '../index'
+import {
+  resetLoggerExtension,
+  resetLoggerRegistry,
+} from '@open-mercato/shared/lib/logger'
+import { resetTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { initTelemetry, resetTelemetryInit } from '../init'
+import { registerProvider, resetActiveProvider } from '../provider/registry'
+import { resetTelemetryEnvCache } from '../env'
+import { runSpan } from '../provider/run-span'
+import type { Attributes, LogRecord, MetricPoint, Span, SpanOptions, TelemetryProvider, TraceCarrier } from '../types'
+
+type ReportedError = {
+  error: NonNullable<LogRecord['error']>
+  context: { module?: string; code?: string; attributes?: Attributes }
+}
+
+class RecordingSpan implements Span {
+  attributes: Record<string, unknown> = {}
+  exceptions: unknown[] = []
+  status: 'ok' | 'error' = 'ok'
+  setAttribute(key: string, value: string | number | boolean): void {
+    this.attributes[key] = value
+  }
+  setAttributes(attributes: Record<string, string | number | boolean | undefined>): void {
+    Object.assign(this.attributes, attributes)
+  }
+  recordException(error: unknown): void {
+    this.exceptions.push(error)
+  }
+  setStatus(status: 'ok' | 'error'): void {
+    this.status = status
+  }
+  end(): void {}
+}
+
+/**
+ * `withErrorSink` opts the provider into the optional `reportError` hook, so one
+ * harness covers both a provider that implements it and a provider that predates
+ * it (the third-party compatibility case the contract exists to protect).
+ */
+function recordingProvider(options?: { withErrorSink?: boolean; onReportError?: () => void }) {
+  const span = new RecordingSpan()
+  const logs: LogRecord[] = []
+  const metrics: MetricPoint[] = []
+  const reported: ReportedError[] = []
+  const provider: TelemetryProvider = {
+    name: 'console',
+    supports: ['traces', 'metrics', 'logs', 'errors'],
+    async start() {},
+    async shutdown() {},
+    runInSpan<T>(_name: string, _options: SpanOptions, fn: (s: Span) => T): T {
+      return runSpan(span, fn)
+    },
+    activeSpan: () => span,
+    activeTraceContext: () => undefined,
+    inject: () => {},
+    runInRemoteSpan<T>(_carrier: TraceCarrier, _name: string, _options: SpanOptions, fn: (s: Span) => T): T {
+      return runSpan(span, fn)
+    },
+    emitLog: (record) => logs.push(record),
+    recordMetric: (point) => metrics.push(point),
+    ...(options?.withErrorSink
+      ? {
+        reportError: (error: NonNullable<LogRecord['error']>, context: ReportedError['context']) => {
+          reported.push({ error, context })
+          options.onReportError?.()
+        },
+      }
+      : {}),
+  }
+  return { provider, span, logs, metrics, reported }
+}
+
+async function activate(provider: TelemetryProvider): Promise<void> {
+  process.env.TELEMETRY_BACKEND = 'console'
+  registerProvider(provider)
+  await initTelemetry()
+}
+
+function errorLogs(logs: LogRecord[]): LogRecord[] {
+  return logs.filter((record) => record.level === 'error')
+}
+
+describe('reportError policy', () => {
+  beforeEach(() => {
+    resetActiveProvider()
+    resetTelemetryInit()
+    resetTelemetryEnvCache()
+    resetLoggerExtension()
+    resetLoggerRegistry()
+    resetTelemetryRuntime()
+    delete process.env.TELEMETRY_BACKEND
+  })
+
+  afterEach(() => {
+    delete process.env.TELEMETRY_BACKEND
+  })
+
+  it('stamps the code on the span, the log record and the metric label', async () => {
+    const { provider, span, logs, metrics } = recordingProvider()
+    await activate(provider)
+
+    reportError(new Error('item rejected'), {
+      module: 'data_sync',
+      code: 'data_sync.item_failed',
+      attributes: { runId: 'run-1' },
+    })
+
+    expect(span.attributes['error.code']).toBe('data_sync.item_failed')
+    expect(span.status).toBe('error')
+    const record = errorLogs(logs)[0]
+    expect(record?.attributes?.['error.code']).toBe('data_sync.item_failed')
+    expect(record?.attributes?.runId).toBe('run-1')
+    expect(metrics.find((metric) => metric.name === 'om.errors')?.labels).toEqual({
+      module: 'data_sync',
+      'error.code': 'data_sync.item_failed',
+    })
+  })
+
+  it('leaves callers that pass no code exactly as they were', async () => {
+    const { provider, span, logs, metrics } = recordingProvider()
+    await activate(provider)
+
+    reportError(new Error('boom'), { module: 'crud' })
+
+    expect(metrics.find((metric) => metric.name === 'om.errors')?.labels).toEqual({ module: 'crud' })
+    expect(errorLogs(logs)[0]?.attributes?.['error.code']).toBeUndefined()
+    expect(span.attributes['error.code']).toBeUndefined()
+    expect(span.exceptions).toHaveLength(1)
+  })
+
+  it('drops a code that is not a groupable fingerprint rather than publishing it', async () => {
+    const { provider, span, logs, metrics, reported } = recordingProvider({ withErrorSink: true })
+    await activate(provider)
+
+    // A metric label is unbounded cardinality and skips redaction, so the funnel
+    // narrows the code once here rather than trusting every caller to.
+    reportError(new Error('upstream rejected the item'), {
+      module: 'integrations',
+      code: 'http_404_https://erp.example.com/api/customers/jan.kowalski@example.com',
+    })
+
+    expect(metrics.find((metric) => metric.name === 'om.errors')?.labels).toEqual({ module: 'integrations' })
+    expect(errorLogs(logs)[0]?.attributes?.['error.code']).toBeUndefined()
+    expect(span.attributes['error.code']).toBeUndefined()
+    expect(reported[0]?.context.code).toBeUndefined()
+    // Dropping the fingerprint never drops the error itself.
+    expect(span.exceptions).toHaveLength(1)
+    expect(errorLogs(logs)).toHaveLength(1)
+    expect(reported).toHaveLength(1)
+  })
+
+  it('reports every occurrence — no sampling, no suppression', async () => {
+    const { provider, logs, metrics, reported } = recordingProvider({ withErrorSink: true })
+    await activate(provider)
+
+    for (let index = 0; index < 115; index += 1) {
+      reportError(new Error('same failure'), { module: 'data_sync', code: 'data_sync.item_failed' })
+    }
+
+    expect(errorLogs(logs)).toHaveLength(115)
+    expect(reported).toHaveLength(115)
+    expect(metrics.filter((metric) => metric.name === 'om.errors')).toHaveLength(115)
+  })
+
+  it('hands the provider a serialized, redacted error in addition to span, log and metric', async () => {
+    const { provider, span, logs, metrics, reported } = recordingProvider({ withErrorSink: true })
+    await activate(provider)
+
+    reportError(new Error('no user for jan.kowalski@example.com'), {
+      module: 'integrations',
+      code: 'integrations.log_error',
+      attributes: { authorization: 'Bearer sk_live_abc', integrationId: 'sync_akeneo' },
+    })
+
+    expect(reported).toHaveLength(1)
+    expect(reported[0]?.error.name).toBe('Error')
+    expect(reported[0]?.error.message).toBe('no user for [redacted-email]')
+    expect(reported[0]?.context.code).toBe('integrations.log_error')
+    expect(reported[0]?.context.module).toBe('integrations')
+    expect(reported[0]?.context.attributes?.authorization).toBe('[redacted]')
+    expect(reported[0]?.context.attributes?.integrationId).toBe('sync_akeneo')
+    // Carried once, in the context — a provider author following the README recipe
+    // should not find it in `extra` as well as `tags`.
+    expect(reported[0]?.context.attributes?.['error.code']).toBeUndefined()
+    // The hook is additive: the built-in path still fires, so a provider that
+    // implements it cannot make signal disappear.
+    expect(span.exceptions).toHaveLength(1)
+    expect(errorLogs(logs)).toHaveLength(1)
+    expect(metrics.some((metric) => metric.name === 'om.errors')).toBe(true)
+  })
+
+  it('does not recurse when the reporting path itself reports', async () => {
+    let nested = 0
+    const { provider, logs, reported } = recordingProvider({
+      withErrorSink: true,
+      onReportError: () => {
+        nested += 1
+        if (nested > 5) return
+        reportError(new Error('failure inside the error sink'), { module: 'telemetry' })
+      },
+    })
+    await activate(provider)
+
+    reportError(new Error('original failure'), { module: 'data_sync', code: 'data_sync.item_failed' })
+
+    expect(reported).toHaveLength(1)
+    expect(reported[0]?.error.message).toBe('original failure')
+    expect(errorLogs(logs)).toHaveLength(1)
+  })
+
+  it('survives a provider whose error sink throws, without losing any built-in signal', async () => {
+    const { provider, span, logs, metrics } = recordingProvider({
+      withErrorSink: true,
+      onReportError: () => {
+        throw new Error('sentry transport is down')
+      },
+    })
+    await activate(provider)
+
+    // `reportError` is called from catch blocks that still have work to do after
+    // it — rethrowing the caller's error, returning a 500 with its correlation
+    // header. A third-party hook must never be able to take that with it.
+    expect(() =>
+      reportError(new Error('item rejected'), { module: 'data_sync', code: 'data_sync.item_failed' }),
+    ).not.toThrow()
+
+    expect(span.exceptions).toHaveLength(1)
+    expect(span.attributes['error.code']).toBe('data_sync.item_failed')
+    expect(errorLogs(logs)).toHaveLength(1)
+    expect(metrics.filter((metric) => metric.name === 'om.errors')).toHaveLength(1)
+  })
+
+  it('is unaffected by a provider without the optional error sink', async () => {
+    const { provider, logs } = recordingProvider()
+    await activate(provider)
+
+    expect(() => reportError(new Error('boom'), { module: 'queue', code: 'queue.job_failed' })).not.toThrow()
+    expect(errorLogs(logs)).toHaveLength(1)
+  })
+})

package/src/facade/report-error.ts

@@ -1,41 +1,141 @@
-import type { Attributes } from '../types'
+import type { Attributes, LogRecord } from '../types'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { groupableCode } from '@open-mercato/shared/lib/telemetry/error-code'
 import { currentSpan } from './tracer'
 import { serializeError } from './serialize'
 import { counter } from './meter'
 import { redactAttributes } from './redact'
+import { getActiveProvider } from '../provider/registry'
 
 const logger = createLogger('telemetry')
 
+/**
+ * The single attribute name the code is published under, on all three built-in
+ * surfaces. One spelling, so a query written against the span also works against
+ * the log record and the metric.
+ */
+const CODE_ATTRIBUTE = 'error.code'
+
 export type ReportErrorContext = {
-  /** Owning module, e.g. 'orders'. Used as the only metric label. */
+  /** Owning module, e.g. 'orders'. Used as a metric label. */
   module?: string
+  /**
+   * Stable, enumerated fingerprint for this failure reason, as `module.reason`
+   * (`data_sync.item_failed`, `queue.job_failed`). NEVER an interpolated string:
+   * it is a metric label, and it is what the backend groups on. A value that is
+   * not that shape is dropped here rather than published — see `groupableCode`.
+   *
+   * Grouping is why this exists. Sentry fingerprints on the stack trace and New
+   * Relic on the error class, so a funnel that synthesizes one error type at one
+   * line — the integration-log tee — collapses every caller into a single issue
+   * without a discriminator, and SigNoz has no error grouping of its own at all.
+   */
+  code?: string
   /** Low-cardinality, NO-PII attributes (ids ok, never names/content). */
   attributes?: Attributes
 }
 
+/**
+ * Re-entrancy guard, not a rate limit. A plain module-level flag, which is
+ * sufficient only because `reportError` runs synchronously end to end: a nested
+ * call can therefore come from nothing but the reporting path itself — a provider
+ * whose error sink reports its own failures, a log bridge that reports. One flag
+ * turns that recursion into a no-op while keeping the original report intact. Add
+ * an `await` anywhere in this funnel and the flag has to become async-context
+ * scoped, or concurrent reports will suppress each other.
+ *
+ * Volume is deliberately NOT policed here: the backend (quotas, spike
+ * protection), the collector (filter/sample processors) and the SDK's batch
+ * processors already bound it, and each of them drops where the drop is visible
+ * and adjustable. A fourth limiter in this function would be the only one that
+ * loses an error irrecoverably at the source.
+ */
+let reporting = false
+
 /**
  * The error funnel. Additive — existing `console.error` calls stay valid; this
  * is the path that reaches the active backend. It:
  *   1. records the exception on the active span (errors-as-span-events),
  *   2. emits a structured error log (stack only — no PII payloads),
- *   3. increments the `om.errors` counter, labeled by `module` only.
+ *   3. increments the `om.errors` counter, labeled by `module` and `error.code`,
+ *   4. hands the serialized error to the provider's own error sink when it has
+ *      one (issue-tracker-shaped backends), in ADDITION to the three above so no
+ *      path can lose signal.
+ *
+ * Every reported error is emitted; there is no sampling or suppression here.
  */
 export function reportError(error: unknown, ctx?: ReportErrorContext): void {
-  const span = currentSpan()
-  if (span) {
-    span.recordException(error)
-    span.setStatus('error')
+  if (reporting) return
+  reporting = true
+  try {
+    // Narrowed once, here, rather than at each caller: the property being
+    // protected — a metric label is bounded and never redacted — belongs to this
+    // funnel, and `code` reaches it from adapters and third-party modules. A
+    // caller with a malformed code reports exactly as one with no code at all.
+    const code = groupableCode(ctx?.code)
+    const span = currentSpan()
+    if (span) {
+      span.recordException(error)
+      span.setStatus('error')
+      // Span-level, because `recordException` takes no attributes. With several
+      // reports on one span the last code wins; the per-error code always
+      // survives on the log record and the metric.
+      if (code) span.setAttribute(CODE_ATTRIBUTE, code)
+    }
+
+    const serialized = serializeError(error)
+    const attributes: Attributes = { ...(ctx?.attributes ?? {}) }
+    if (ctx?.module) attributes.module = ctx.module
+    if (code) attributes[CODE_ATTRIBUTE] = code
+    const safeAttributes = redactAttributes(attributes)
+
+    const safeError = new Error(serialized.message)
+    safeError.name = serialized.name
+    safeError.stack = serialized.stack
+    logger.error('Application error reported', { ...safeAttributes, err: safeError })
+    counter('om.errors', 1, errorLabels(ctx?.module, code))
+
+    reportToProvider(serialized, ctx?.module, code, safeAttributes)
+  } finally {
+    reporting = false
   }
+}
 
-  const serialized = serializeError(error)
-  const attributes: Attributes = { ...(ctx?.attributes ?? {}) }
-  if (ctx?.module) attributes.module = ctx.module
-  const safeAttributes = redactAttributes(attributes)
+/**
+ * Hand the error to the provider's own sink, when it has one.
+ *
+ * Guarded, and that is the whole point of the function: `reportError` is called
+ * from `catch` blocks that still have work to do after it — the API dispatcher
+ * records a duration metric, emits its lifecycle event and rethrows the original
+ * error; the CRUD factory returns a 500 carrying its `x-request-id`. This hook is
+ * implemented by third parties, so one that throws would take all of that with it
+ * and replace the caller's error with the telemetry provider's. The interface
+ * documents the hook as non-throwing; this is what makes that a property of the
+ * funnel rather than a request to its implementors.
+ */
+function reportToProvider(
+  serialized: NonNullable<LogRecord['error']>,
+  module: string | undefined,
+  code: string | undefined,
+  safeAttributes: Attributes,
+): void {
+  try {
+    const provider = getActiveProvider()
+    if (!provider.reportError) return
+    // `code` travels in the context. Repeating it in the attributes would land it
+    // in a provider's tags AND its extra data for anyone following the README recipe.
+    const providerAttributes: Attributes = { ...safeAttributes }
+    delete providerAttributes[CODE_ATTRIBUTE]
+    provider.reportError(serialized, { module, code, attributes: providerAttributes })
+  } catch (sinkError) {
+    logger.warn('Telemetry provider error sink failed', { err: sinkError as Error })
+  }
+}
 
-  const safeError = new Error(serialized.message)
-  safeError.name = serialized.name
-  safeError.stack = serialized.stack
-  logger.error('Application error reported', { ...safeAttributes, err: safeError })
-  counter('om.errors', 1, ctx?.module ? { module: ctx.module } : undefined)
+function errorLabels(module?: string, code?: string): Attributes | undefined {
+  if (!module && !code) return undefined
+  const labels: Attributes = {}
+  if (module) labels.module = module
+  if (code) labels[CODE_ATTRIBUTE] = code
+  return labels
 }

package/src/types.ts

@@ -124,6 +124,31 @@ export interface TelemetryProvider {
   emitLog(record: LogRecord): void
   /** Record a metric observation (no-op if `metrics` unsupported). */
   recordMetric(point: MetricPoint): void
+  /**
+   * Receive a reported error as a first-class error, for backends that model
+   * errors as issues rather than as a span event plus a log record (Sentry and
+   * friends). The facade calls it in ADDITION to the span/log/metric path, never
+   * instead of it, so a provider that implements this cannot cause signal to be
+   * lost — it owns its own de-duplication.
+   *
+   * OPTIONAL, and MUST stay optional: third parties implement this interface, and
+   * a required method would break every existing provider. Facade callers invoke
+   * it as `provider.reportError?.(…)`.
+   *
+   * `error` arrives already serialized and PII-redacted (name/message/stack only)
+   * and `attributes` already redacted, so an implementation must not reach for
+   * the original thrown value.
+   *
+   * MUST NOT throw. The facade calls this from `catch` blocks that still have
+   * work to do — rethrowing the original error, returning a 500 with its
+   * correlation header — so it wraps this call and degrades a throwing hook to a
+   * warning. Do the same inside your implementation: a backend SDK that raises on
+   * a full buffer should be swallowed here, not escalated.
+   */
+  reportError?(
+    error: NonNullable<LogRecord['error']>,
+    context: { module?: string; code?: string; attributes?: Attributes },
+  ): void
 }
 
 /**