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

package/src/provider/registry.ts

@@ -0,0 +1,60 @@
+import type { TelemetryProvider } from '../types'
+import { NoopProvider } from './noop-provider'
+
+/**
+ * The active provider is a PROCESS-WIDE singleton, stored on `globalThis` rather
+ * than in a module variable. This is load-bearing: the worker bootstrap
+ * esbuild-bundles the generated DI registry into a `.mjs` that can inline a
+ * *private copy* of this module, while job handlers are dynamic-imported as
+ * source and use the *source copy*. With module-level state, `initTelemetry()`
+ * would set the provider on one copy while the handlers read a still-noop other
+ * — so worker logs/spans would never reach the backend. Keying the state on a
+ * global symbol makes every copy share one provider. Mirrors the framework's own
+ * DI-registrar global.
+ */
+const GLOBAL_KEY = Symbol.for('@open-mercato/telemetry.providerRegistry')
+
+type ProviderRegistry = {
+  active: TelemetryProvider
+  registered: Map<string, TelemetryProvider>
+}
+
+function store(): ProviderRegistry {
+  const g = globalThis as unknown as Record<symbol, ProviderRegistry | undefined>
+  let reg = g[GLOBAL_KEY]
+  if (!reg) {
+    reg = { active: new NoopProvider(), registered: new Map() }
+    g[GLOBAL_KEY] = reg
+  }
+  return reg
+}
+
+/** Plug a custom backend before `initTelemetry()` (e.g. tests or a bespoke sink). */
+export function registerProvider(provider: TelemetryProvider): void {
+  store().registered.set(provider.name, provider)
+}
+
+export function getRegisteredProvider(name: string): TelemetryProvider | undefined {
+  return store().registered.get(name)
+}
+
+export function getActiveProvider(): TelemetryProvider {
+  return store().active
+}
+
+/** Set the active provider. Called by `initTelemetry()`. */
+export function setActiveProvider(provider: TelemetryProvider): void {
+  store().active = provider
+}
+
+/** Restore only the active provider while preserving custom registrations. */
+export function clearActiveProvider(): void {
+  store().active = new NoopProvider()
+}
+
+/** Test-only: restore the default no-op provider. */
+export function resetActiveProvider(): void {
+  const reg = store()
+  clearActiveProvider()
+  reg.registered.clear()
+}

package/src/provider/run-span.ts

@@ -0,0 +1,45 @@
+import type { Span } from '../types'
+
+function isThenable(value: unknown): value is Promise<unknown> {
+  return (
+    value != null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof (value as { then?: unknown }).then === 'function'
+  )
+}
+
+/**
+ * Run `fn(span)` and end `span` when it settles — synchronously for sync
+ * returns, on resolve/reject for promises. Exceptions (sync throw or rejected
+ * promise) are recorded on the span and re-thrown. Shared by the console and
+ * OTLP providers so async spans get correct durations.
+ */
+export function runSpan<T>(span: Span, fn: (span: Span) => T): T {
+  let result: T
+  try {
+    result = fn(span)
+  } catch (error) {
+    span.recordException(error)
+    span.setStatus('error')
+    span.end()
+    throw error
+  }
+
+  if (isThenable(result)) {
+    return result.then(
+      (value) => {
+        span.end()
+        return value
+      },
+      (error) => {
+        span.recordException(error)
+        span.setStatus('error')
+        span.end()
+        throw error
+      },
+    ) as T
+  }
+
+  span.end()
+  return result
+}

package/src/types.ts

@@ -0,0 +1,108 @@
+/**
+ * Public, vendor-neutral telemetry contract.
+ *
+ * Nothing in this package's facade may import any `@opentelemetry/*` package —
+ * only `provider/otlp-provider.ts` does, and it is loaded dynamically so the SDK
+ * never resolves when telemetry is off.
+ */
+
+/** Signal categories a provider may support. Unsupported signals no-op. */
+export type TelemetrySignal = 'traces' | 'metrics' | 'logs' | 'errors'
+
+/** Attribute primitive values allowed on spans/logs/metrics (low-cardinality, no PII). */
+export type AttributeValue = string | number | boolean
+export type Attributes = Record<string, AttributeValue | undefined>
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+/** A structured log record routed through the active provider. */
+export type LogRecord = {
+  level: LogLevel
+  message: string
+  attributes?: Attributes
+  /** Serialized error (stack only, no PII payloads). */
+  error?: { name: string; message: string; stack?: string }
+  /** Epoch milliseconds; defaults to emit time. */
+  time?: number
+}
+
+/** A single metric observation. */
+export type MetricKind = 'counter' | 'histogram' | 'gauge'
+export type MetricPoint = {
+  kind: MetricKind
+  name: string
+  value: number
+  /** Low-cardinality labels only (never tenant/org/user IDs — those are span attributes). */
+  labels?: Attributes
+  /** UCUM unit (e.g. `s`, `By`); set once per metric name at instrument creation. */
+  unit?: string
+}
+
+/** Options when starting a span. */
+export type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer'
+export type SpanOptions = {
+  kind?: SpanKind
+  attributes?: Attributes
+}
+
+/**
+ * Vendor-neutral handle to an active span. Backed by a real OTEL span under the
+ * OTLP provider, or a cheap shim under noop/console.
+ */
+export interface Span {
+  setAttribute(key: string, value: AttributeValue): void
+  setAttributes(attributes: Attributes): void
+  recordException(error: unknown): void
+  setStatus(status: 'ok' | 'error', message?: string): void
+  end(): void
+}
+
+/** The active trace + span ids, for correlating structured logs with traces. */
+export type TraceContext = { traceId: string; spanId: string }
+
+/**
+ * A telemetry backend.
+ *
+ * Tracing uses a DELEGATION model — the provider OWNS span creation and runs
+ * `fn` inside the span's context (`runInSpan`). This is required so manually
+ * created spans and OTEL auto-instrumentation spans (pg/http) share one trace;
+ * a detached "finished span" sink cannot propagate context. Logs/metrics stay
+ * sink-style.
+ */
+export interface TelemetryProvider {
+  readonly name: string
+  readonly supports: readonly TelemetrySignal[]
+  /** Initialize the backend (SDK start, exporters). Idempotent. */
+  start(): Promise<void>
+  /** Flush and tear down. Idempotent. */
+  shutdown(): Promise<void>
+  /** Run `fn` inside a new active span. Records exceptions + duration automatically. */
+  runInSpan<T>(name: string, options: SpanOptions, fn: (span: Span) => T): T
+  /** The currently active span in this async context, if any. */
+  activeSpan(): Span | undefined
+  /** The active trace/span ids (for log correlation), or undefined if none is active. */
+  activeTraceContext(): TraceContext | undefined
+  /** Write the active trace context into `carrier` (W3C propagation). */
+  inject(carrier: TraceCarrier): void
+  /** Extract a parent trace context from `carrier`, then run `fn` in a new active span under it. */
+  runInRemoteSpan<T>(carrier: TraceCarrier, name: string, options: SpanOptions, fn: (span: Span) => T): T
+  /** Emit a structured log record (no-op if `logs` unsupported). */
+  emitLog(record: LogRecord): void
+  /** Record a metric observation (no-op if `metrics` unsupported). */
+  recordMetric(point: MetricPoint): void
+}
+
+/**
+ * Carrier for cross-boundary trace context (W3C `traceparent`/`tracestate`).
+ * Embedded in queue job payloads / event payloads to link a producer's trace to
+ * the consumer's spans (the queue/event bus expose no metadata channel).
+ */
+export type TraceCarrier = Record<string, string>
+
+/**
+ * Resolved configuration for the active backend. `signoz`, `newrelic`, and the
+ * generic `otlp` all select the same OTLP provider — they differ only by the
+ * standard `OTEL_EXPORTER_OTLP_ENDPOINT`/`_HEADERS` that point it at a vendor.
+ * Modern New Relic ingests OTLP directly, so it needs no bespoke exporter.
+ */
+export type TelemetryBackendName = 'noop' | 'console' | 'signoz' | 'newrelic' | 'otlp'

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/__tests__/**"]
+}

package/watch.mjs

@@ -0,0 +1,6 @@
+import { watch } from '../../scripts/watch.mjs'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+watch(__dirname)