@open-mercato/telemetry 0.6.7-develop.6834.1.e76f4b8cbc

package/src/__tests__/telemetry.test.ts

@@ -0,0 +1,172 @@
+import { withSpan, currentSpan, counter, reportError, captureTraceContext, continueTrace } from '../index'
+import {
+  createLogger,
+  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 { LogRecord, MetricPoint, Span, SpanOptions, TelemetryProvider, TraceCarrier } from '../types'
+
+class RecordingSpan implements Span {
+  attributes: Record<string, unknown> = {}
+  exceptions: unknown[] = []
+  status: 'ok' | 'error' = 'ok'
+  ended = false
+  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 {
+    this.ended = true
+  }
+}
+
+function recordingProvider() {
+  const span = new RecordingSpan()
+  const logs: LogRecord[] = []
+  const metrics: MetricPoint[] = []
+  const spanNames: string[] = []
+  const remoteCarriers: TraceCarrier[] = []
+  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 {
+      spanNames.push(name)
+      return runSpan(span, fn)
+    },
+    activeSpan: () => span,
+    activeTraceContext: () => ({ traceId: 'a'.repeat(32), spanId: 'b'.repeat(16) }),
+    inject: (carrier) => {
+      carrier.traceparent = 'test-traceparent'
+    },
+    runInRemoteSpan<T>(carrier: TraceCarrier, name: string, _options: SpanOptions, fn: (s: Span) => T): T {
+      remoteCarriers.push(carrier)
+      spanNames.push(name)
+      return runSpan(span, fn)
+    },
+    emitLog: (record) => logs.push(record),
+    recordMetric: (point) => metrics.push(point),
+  }
+  return { provider, span, logs, metrics, spanNames, remoteCarriers }
+}
+
+describe('telemetry facade', () => {
+  beforeEach(() => {
+    resetActiveProvider()
+    resetTelemetryInit()
+    resetTelemetryEnvCache()
+    resetLoggerExtension()
+    resetLoggerRegistry()
+    resetTelemetryRuntime()
+    delete process.env.TELEMETRY_BACKEND
+  })
+
+  it('is a safe no-op when telemetry is off (default)', () => {
+    expect(withSpan('work', () => 42)).toBe(42)
+    expect(currentSpan()).toBeUndefined()
+    expect(() => {
+      createLogger('test').info('hello')
+      counter('demo')
+      reportError(new Error('boom'))
+    }).not.toThrow()
+    // Propagation helpers are safe with no backend: empty carrier, fn still runs.
+    expect(captureTraceContext()).toEqual({})
+    expect(continueTrace({}, 'job', () => 5)).toBe(5)
+  })
+
+  it('runs the function and returns its value inside a span', () => {
+    const seen: Span[] = []
+    const result = withSpan('compute', (span) => {
+      seen.push(span)
+      return 7
+    })
+    expect(result).toBe(7)
+    expect(seen).toHaveLength(1)
+  })
+
+  it('awaits async work before the span ends', async () => {
+    const { provider, span } = recordingProvider()
+    process.env.TELEMETRY_BACKEND = 'console'
+    registerProvider(provider)
+    await initTelemetry()
+
+    let asyncWorkDone = false
+    const pending = withSpan('tutor.turn', async (s) => {
+      s.setAttributes({ subject: 'math' })
+      await new Promise((resolve) => setTimeout(resolve, 5))
+      asyncWorkDone = true
+    })
+    expect(span.ended).toBe(false)
+    await pending
+    expect(asyncWorkDone).toBe(true)
+    expect(span.ended).toBe(true)
+    expect(span.attributes.subject).toBe('math')
+  })
+
+  it('records a span, exception, error status, error log, and om.errors metric', async () => {
+    const { provider, span, logs, metrics, spanNames } = recordingProvider()
+    process.env.TELEMETRY_BACKEND = 'console'
+    registerProvider(provider)
+    await initTelemetry()
+
+    withSpan('work.unit', (s) => s.setAttributes({ subject: 'math' }))
+    reportError(new Error('kaboom'), { module: 'orders' })
+
+    expect(spanNames).toContain('work.unit')
+    expect(span.attributes.subject).toBe('math')
+    expect(span.exceptions).toHaveLength(1)
+    expect(span.status).toBe('error')
+    expect(metrics.find((m) => m.name === 'om.errors')?.labels).toEqual({ module: 'orders' })
+    expect(logs.some((l) => l.level === 'error' && l.error?.message === 'kaboom')).toBe(true)
+  })
+
+  it('propagates trace context: captureTraceContext injects, continueTrace consumes it', async () => {
+    const { provider, remoteCarriers, spanNames } = recordingProvider()
+    process.env.TELEMETRY_BACKEND = 'console'
+    registerProvider(provider)
+    await initTelemetry()
+
+    // Producer side (e.g. enqueue): capture the active context into a carrier.
+    const carrier = captureTraceContext()
+    expect(carrier.traceparent).toBe('test-traceparent')
+
+    // Consumer side (e.g. worker): continue the trace under the carrier's parent.
+    const result = await continueTrace(carrier, 'queue.orders-process', async () => 'done')
+    expect(result).toBe('done')
+    expect(spanNames).toContain('queue.orders-process')
+    expect(remoteCarriers[0]?.traceparent).toBe('test-traceparent')
+  })
+
+  it('redacts secret-keyed attributes in the reported error context before they ship', async () => {
+    const { provider, logs } = recordingProvider()
+    process.env.TELEMETRY_BACKEND = 'console'
+    registerProvider(provider)
+    await initTelemetry()
+
+    reportError(new Error('request failed'), {
+      module: 'integrations',
+      attributes: { authorization: 'Bearer sk_live_abc', 'http.route': '/api/sync', 'x-api-key': 'key_123' },
+    })
+
+    const record = logs.find((l) => l.level === 'error')
+    expect(record?.attributes?.authorization).toBe('[redacted]')
+    expect(record?.attributes?.['x-api-key']).toBe('[redacted]')
+    // low-cardinality, non-secret attributes are preserved
+    expect(record?.attributes?.['http.route']).toBe('/api/sync')
+    expect(record?.attributes?.module).toBe('integrations')
+  })
+})

package/src/env.ts

@@ -0,0 +1,71 @@
+import type { TelemetryBackendName } from './types'
+import { isTelemetryBackendEnabled } from '@open-mercato/shared/lib/telemetry/runtime'
+
+/** Backend names that resolve to the OTLP provider (vendor differs only by endpoint). */
+const OTLP_BACKENDS: readonly TelemetryBackendName[] = ['signoz', 'newrelic', 'otlp']
+export function isOtlpBackend(name: TelemetryBackendName): boolean {
+  return (OTLP_BACKENDS as readonly string[]).includes(name)
+}
+
+export type TelemetryEnv = {
+  /** Active backend. Unset/unknown → 'noop' (off). */
+  backend: TelemetryBackendName
+  /** True unless backend is 'noop'. */
+  enabled: boolean
+  /** 0.0–1.0 trace sampling ratio. */
+  samplingRatio: number
+  /**
+   * Continue the inbound HTTP trace (standard W3C extract) instead of rooting
+   * per request. Default false. Set true only when embedded behind a trusted
+   * upstream whose trace should continue.
+   */
+  trustInboundTrace: boolean
+  serviceName: string
+  /** OTLP endpoint (provider reads standard OTEL vars; surfaced here for diagnostics). */
+  otlpEndpoint?: string
+}
+
+function parseBackend(raw: string | undefined): TelemetryBackendName {
+  const v = (raw ?? '').trim().toLowerCase()
+  return isTelemetryBackendEnabled(v) ? (v as TelemetryBackendName) : 'noop'
+}
+
+function parseSampling(raw: string | undefined, isProd: boolean): number {
+  const n = Number.parseFloat((raw ?? '').trim())
+  if (Number.isFinite(n) && n >= 0 && n <= 1) return n
+  return isProd ? 0.1 : 1.0
+}
+
+/** Parse a boolean env flag; unset/unknown → `fallback`. */
+function parseBool(raw: string | undefined, fallback: boolean): boolean {
+  const v = (raw ?? '').trim().toLowerCase()
+  if (v === 'true' || v === '1') return true
+  if (v === 'false' || v === '0') return false
+  return fallback
+}
+
+let cached: TelemetryEnv | undefined
+
+export function readTelemetryEnv(): TelemetryEnv {
+  if (cached) return cached
+  const isProd = process.env.NODE_ENV === 'production'
+  const backend = parseBackend(process.env.TELEMETRY_BACKEND)
+  cached = {
+    backend,
+    enabled: backend !== 'noop',
+    samplingRatio: parseSampling(process.env.TELEMETRY_SAMPLING_RATIO, isProd),
+    trustInboundTrace: parseBool(process.env.TELEMETRY_TRUST_INBOUND_TRACE, false),
+    serviceName: process.env.OTEL_SERVICE_NAME?.trim() || 'open-mercato',
+    otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim() || undefined,
+  }
+  return cached
+}
+
+/**
+ * Reset the memoized env snapshot. Called by `initTelemetry()` so init always
+ * resolves from the fully-loaded environment (a host may import this package
+ * before its `.env` is loaded — the CLI binary does), and by jest between tests.
+ */
+export function resetTelemetryEnvCache(): void {
+  cached = undefined
+}

package/src/facade/context.ts

@@ -0,0 +1,17 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { Span } from '../types'
+
+/**
+ * Carries the facade's active span across `await` boundaries for spans created
+ * via `withSpan`. (OTEL auto-instrumentation spans live in OTEL's own context;
+ * the OTLP provider's `activeSpan()` bridges to those — see `currentSpan`.)
+ */
+export const spanStore = new AsyncLocalStorage<Span>()
+
+export function runWithSpan<T>(span: Span, fn: () => T): T {
+  return spanStore.run(span, fn)
+}
+
+export function spanFromStore(): Span | undefined {
+  return spanStore.getStore()
+}

package/src/facade/http.ts

@@ -0,0 +1,25 @@
+import { histogram } from './meter'
+
+/**
+ * Emit the OpenTelemetry-standard HTTP server metric
+ * `http.server.request.duration` (histogram, seconds) with semconv attributes.
+ * `route` MUST be a low-cardinality route template, never a resolved pathname.
+ */
+export function recordHttpDuration(
+  method: string,
+  route: string,
+  status: number,
+  startedAt: number,
+): void {
+  histogram(
+    'http.server.request.duration',
+    (Date.now() - startedAt) / 1000,
+    {
+      'http.request.method': method,
+      'http.route': route,
+      'http.response.status_code': status,
+      'error.type': status >= 500 ? String(status) : undefined,
+    },
+    's',
+  )
+}

package/src/facade/logger-bridge.ts

@@ -0,0 +1,50 @@
+import {
+  registerLoggerExtension,
+  type LoggerExtensionRecord,
+} from '@open-mercato/shared/lib/logger'
+import type { Attributes, LogRecord, TelemetryProvider } from '../types'
+import { redactAttributes } from './redact'
+import { serializeError } from './serialize'
+
+function toAttributes(record: LoggerExtensionRecord): Attributes {
+  const attributes: Attributes = {
+    'logger.name': record.namespace,
+  }
+  for (const [key, value] of Object.entries(record.fields)) {
+    if (key === 'err' || value === undefined) continue
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      attributes[key] = value
+    }
+  }
+  return redactAttributes(attributes)
+}
+
+function toLogRecord(record: LoggerExtensionRecord): LogRecord {
+  const error = record.fields.err === undefined
+    ? undefined
+    : serializeError(record.fields.err)
+  return {
+    level: record.level,
+    message: record.message,
+    attributes: toAttributes(record),
+    error,
+    time: record.time,
+  }
+}
+
+/**
+ * Extend the canonical shared logger with trace correlation + remote export.
+ * The shared logger remains the sole application-facing logger and sole local
+ * output path; telemetry observes the already-normalized record exactly once.
+ */
+export function registerTelemetryLogger(provider: TelemetryProvider): () => void {
+  return registerLoggerExtension({
+    enrich: () => {
+      const context = provider.activeTraceContext()
+      return context
+        ? { trace_id: context.traceId, span_id: context.spanId }
+        : undefined
+    },
+    emit: (record) => provider.emitLog(toLogRecord(record)),
+  })
+}

package/src/facade/meter.ts

@@ -0,0 +1,20 @@
+import type { Attributes } from '../types'
+import { getActiveProvider } from '../provider/registry'
+
+/**
+ * Metric helpers. Labels MUST be low-cardinality (never tenant/org/user IDs —
+ * those belong on span attributes, per the telemetry spec's R4). The active
+ * provider caches the underlying instrument by name; these are no-ops when
+ * metrics are off.
+ */
+export function counter(name: string, value = 1, labels?: Attributes, unit?: string): void {
+  getActiveProvider().recordMetric({ kind: 'counter', name, value, labels, unit })
+}
+
+export function histogram(name: string, value: number, labels?: Attributes, unit?: string): void {
+  getActiveProvider().recordMetric({ kind: 'histogram', name, value, labels, unit })
+}
+
+export function gauge(name: string, value: number, labels?: Attributes, unit?: string): void {
+  getActiveProvider().recordMetric({ kind: 'gauge', name, value, labels, unit })
+}

package/src/facade/propagation.ts

@@ -0,0 +1,31 @@
+import type { Span, SpanOptions, TraceCarrier } from '../types'
+import { getActiveProvider } from '../provider/registry'
+import { runWithSpan } from './context'
+
+/**
+ * Capture the active trace context into a fresh carrier, to embed in a queue job
+ * or event payload (the queue/event bus expose no metadata channel — see the
+ * telemetry spec's S5). Returns `{}` when telemetry is off.
+ */
+export function captureTraceContext(): TraceCarrier {
+  const carrier: TraceCarrier = {}
+  getActiveProvider().inject(carrier)
+  return carrier
+}
+
+/**
+ * Continue a trace on the consumer side (worker / subscriber): run `fn` inside a
+ * new active span named `name`, parented to the context in `carrier`. The job's
+ * spans (pg, etc.) then nest under the producer's trace as one waterfall. If
+ * `carrier` is empty/undefined the span simply starts a fresh root.
+ */
+export function continueTrace<T>(
+  carrier: TraceCarrier | undefined,
+  name: string,
+  fn: (span: Span) => T,
+  options?: SpanOptions,
+): T {
+  return getActiveProvider().runInRemoteSpan(carrier ?? {}, name, options ?? {}, (span) =>
+    runWithSpan(span, () => fn(span)),
+  )
+}

package/src/facade/redact.ts

@@ -0,0 +1,54 @@
+import type { Attributes } from '../types'
+
+/**
+ * Active redaction backstop for telemetry (Privacy section of the telemetry spec).
+ *
+ * Defense-in-depth over the don't-emit posture: callers are expected not to put
+ * PII or secrets into errors/logs, but error messages and stack frames can still
+ * pick them up a layer down (e.g. `Error: no user for jan.kowalski@example.com`,
+ * or a dumped `Authorization: Bearer …` header). This scrubs the highest-signal
+ * identifiers — email addresses and auth tokens — from any text that ships to the
+ * backend, without touching opaque UUIDs/ids (which we keep).
+ *
+ * Deliberately conservative (emails + auth tokens) to preserve debuggability;
+ * extend the pattern set here if a new leak vector is found.
+ */
+// Bound every component both to match the practical limits from RFC 5321 and
+// to keep scanning time linear for hostile strings with long runs of email
+// punctuation (CodeQL js/polynomial-redos).
+const EMAIL_RE = /[A-Z0-9._%+-]{1,64}@[A-Z0-9.-]{1,253}\.[A-Z]{2,63}/gi
+// `authorization: <value>` / `cookie: <value>` header dumps embedded in free text.
+// The value runs to the next separator (`;`/`,`/`}`) or newline, so it swallows a
+// `Bearer <token>` value in one pass (before the standalone-scheme rule below).
+const SECRET_HEADER_RE = /\b(authorization|proxy-authorization|cookie|set-cookie)(\s*[:=]\s*)([^\n;,}]+)/gi
+// `Bearer <token>` / `Basic <base64>` / `ApiKey <key>` standing alone in free text (message or stack).
+const AUTH_SCHEME_RE = /\b(Bearer|Basic|ApiKey)\s+[A-Za-z0-9._~+/=-]+/gi
+
+export function redactPii(text: string): string {
+  return text
+    .replace(EMAIL_RE, '[redacted-email]')
+    .replace(SECRET_HEADER_RE, (_match, name: string, separator: string) => `${name}${separator}[redacted]`)
+    .replace(AUTH_SCHEME_RE, (_match, scheme: string) => `${scheme} [redacted]`)
+}
+
+// Attribute KEYS whose value is a secret regardless of content. Intentionally
+// specific enough not to clobber benign fields like `token_count`, while
+// still masking the exact key `token`.
+const SECRET_KEY_RE =
+  /(authorization|cookie|password|passwd|\bpwd\b|secret|api[-_]?key|access[-_]?token|refresh[-_]?token|id[-_]?token|auth[-_]?token|^token$|\bbearer\b|private[-_]?key|credential)/i
+
+/**
+ * Redact a telemetry attribute bag before it ships: a value under a secret-looking
+ * KEY (`authorization`, `set-cookie`, `client_secret`, `x-api-key`, …) is masked
+ * wholesale; other string values still pass through `redactPii` so an inline email
+ * or auth token is caught too. Non-string values are left as-is.
+ */
+export function redactAttributes(attributes: Attributes): Attributes {
+  const result: Attributes = {}
+  for (const [key, value] of Object.entries(attributes)) {
+    if (SECRET_KEY_RE.test(key)) result[key] = '[redacted]'
+    else if (typeof value === 'string') result[key] = redactPii(value)
+    else result[key] = value
+  }
+  return result
+}

package/src/facade/report-error.ts

@@ -0,0 +1,41 @@
+import type { Attributes } from '../types'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { currentSpan } from './tracer'
+import { serializeError } from './serialize'
+import { counter } from './meter'
+import { redactAttributes } from './redact'
+
+const logger = createLogger('telemetry')
+
+export type ReportErrorContext = {
+  /** Owning module, e.g. 'orders'. Used as the only metric label. */
+  module?: string
+  /** Low-cardinality, NO-PII attributes (ids ok, never names/content). */
+  attributes?: Attributes
+}
+
+/**
+ * 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.
+ */
+export function reportError(error: unknown, ctx?: ReportErrorContext): void {
+  const span = currentSpan()
+  if (span) {
+    span.recordException(error)
+    span.setStatus('error')
+  }
+
+  const serialized = serializeError(error)
+  const attributes: 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 } : undefined)
+}

package/src/facade/serialize.ts

@@ -0,0 +1,46 @@
+import type { LogRecord } from '../types'
+import { redactPii } from './redact'
+
+/**
+ * Serialize an error for telemetry: name, message, and stack only.
+ *
+ * Deliberately does NOT include arbitrary error properties (request bodies,
+ * `cause` payloads, query parameters) — those can carry PII. The cause CHAIN is
+ * folded into the message text (names/messages only), never its data. Message +
+ * stack are run through `redactPii` so a leaked email never reaches the backend
+ * (active-redaction backstop over the don't-emit posture).
+ */
+export function serializeError(error: unknown): NonNullable<LogRecord['error']> {
+  if (error instanceof Error) {
+    return {
+      name: redactPii(error.name || 'Error'),
+      message: redactPii(foldCause(error)),
+      stack: error.stack ? redactPii(error.stack) : undefined,
+    }
+  }
+  return { name: 'NonError', message: redactPii(safeString(error)) }
+}
+
+function foldCause(error: Error, seen = new WeakSet<object>()): string {
+  if (seen.has(error)) return error.message
+  seen.add(error)
+  const cause = (error as { cause?: unknown }).cause
+  if (cause instanceof Error) {
+    return `${error.message} — caused by ${cause.name || 'Error'}: ${foldCause(cause, seen)}`
+  }
+  return error.message
+}
+
+function safeString(value: unknown): string {
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+    return String(value)
+  }
+  if (typeof value === 'symbol') return value.description ? `Symbol(${value.description})` : 'Symbol'
+  if (typeof value === 'function') return '[function]'
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+  // Never stringify arbitrary objects: request bodies, provider errors, and
+  // thrown payloads commonly contain credentials or personal data.
+  return '[non-error object]'
+}

package/src/facade/tracer.ts

@@ -0,0 +1,25 @@
+import type { Attributes, Span, SpanOptions } from '../types'
+import { getActiveProvider } from '../provider/registry'
+import { runWithSpan, spanFromStore } from './context'
+
+/**
+ * Run `fn` inside a new span named `name`. The active provider owns span
+ * creation + context, so any OTEL auto-instrumentation (pg/http) inside `fn`
+ * nests under this span in the same trace. Exceptions and duration are recorded
+ * automatically by the provider. No-op-cheap when telemetry is off.
+ */
+export function withSpan<T>(name: string, fn: (span: Span) => T, options?: SpanOptions): T {
+  return getActiveProvider().runInSpan(name, options ?? {}, (span) =>
+    runWithSpan(span, () => fn(span)),
+  )
+}
+
+/** The active span (facade-created or OTEL auto-instrumented), if any. */
+export function currentSpan(): Span | undefined {
+  return spanFromStore() ?? getActiveProvider().activeSpan()
+}
+
+/** Set attributes on the active span, if any. */
+export function setAttributes(attributes: Attributes): void {
+  currentSpan()?.setAttributes(attributes)
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Public facade for the telemetry package. Import from `@open-mercato/telemetry`.
+ *
+ * Vendor-neutral by construction — nothing here imports `@opentelemetry/*`;
+ * only `provider/otlp-provider.ts` does, and it is loaded dynamically.
+ */
+export { withSpan, currentSpan, setAttributes } from './facade/tracer'
+export { counter, histogram, gauge } from './facade/meter'
+export { reportError } from './facade/report-error'
+export type { ReportErrorContext } from './facade/report-error'
+export { captureTraceContext, continueTrace } from './facade/propagation'
+export { initTelemetry, shutdownTelemetry } from './init'
+export { registerProvider } from './provider/registry'
+
+export type {
+  Span,
+  SpanKind,
+  SpanOptions,
+  TelemetryProvider,
+  TelemetrySignal,
+  TelemetryBackendName,
+  LogRecord,
+  LogLevel,
+  MetricKind,
+  MetricPoint,
+  Attributes,
+  AttributeValue,
+  TraceCarrier,
+  TraceContext,
+} from './types'