feat: OpenTelemetry support to export metrics and tracing to an Otel collector

[Ignacio-Vidal]

Summary

Adds OpenTelemetry support to the Prism HTTP service: distributed tracing, metrics, and log↔trace correlation for both mock and proxy, exported to any OTLP-compatible collector (Jaeger, Grafana Tempo, Datadog, the OpenTelemetry Collector, grafana/otel-lgtm, etc.).

Telemetry is opt-in and off by default — when disabled, Prism behaves exactly as before and the OTel SDK is never started (zero overhead, no behavior change).

What's included

• Tracing — each request produces a server span (METHOD /path) carrying request method, URL path, response status code, and recorded exceptions on errors. In proxy mode, outbound upstream calls are traced via HTTP auto-instrumentation.
• Metrics — request count + latency histogram (tagged with method/path/status), plus Node.js VM metrics (event loop delay/utilization, GC duration, V8 heap) via @opentelemetry/instrumentation-runtime-node. Enabled together with tracing by the single --otel-telemetry flag.
• Log ↔ trace correlation — createLogger injects the active span's trace_id/span_id into every log record (via a pino mixin), and the CLI terminal output appends [trace=<id>]. Lets you pivot between a log line and its trace in the backend.
• Configurable exporter — OTLP endpoint, service name, and transport (http/protobuf or grpc) are all configurable, each with the standard OTEL_* env-var fallback.
• Graceful shutdown — traces/metrics buffered by the batch processors are flushed on SIGINT/SIGTERM (single- and multi-process), so the last batch isn't dropped on exit.
• Multiprocess support — telemetry initializes in the cluster worker; the primary forwards shutdown so the worker flushes before exit.

Configuration

Concern	CLI flag	Env var fallback	Default
Enable	--otel-telemetry	PRISM_TELEMETRY	false
Collector URL	--otel-exporter-url	OTEL_EXPORTER_OTLP_ENDPOINT	exporter default
Service name	--otel-service-name	OTEL_SERVICE_NAME	prism
Transport	--otel-exporter-protocol	OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf

A single --otel-telemetry flag enables tracing and metrics together. CLI flags take precedence over env vars.

prism mock api.oas.yaml \
  --otel-telemetry \
  --otel-exporter-url http://localhost:4318/v1/traces \
  --otel-service-name prism-mock

For metrics, the OTLP /v1/traces URL is automatically rewritten to /v1/metrics, so the one --otel-exporter-url covers both signals.

Benefits

• See request-level traces, latency, status codes, and Node runtime health from Prism in your existing observability stack — previously the only signal was stdout logs.
• Log lines carry the trace id, so you can jump from a log to its distributed trace and back.
• Vendor-neutral via OTLP; no dependency on any specific backend.
• Zero overhead and no behavior change when telemetry is off (the default).

Also included: a standalone bug fix

fix(cli): correct node:cluster import for multiprocess mode — multiprocess mode (--multiprocess, the default when NODE_ENV=production, e.g. in the Docker image) crashed on startup with Cannot read properties of undefined (reading 'isPrimary'). The node:cluster default import resolved to undefined at runtime because the project builds CommonJS without esModuleInterop. This is required for multiprocess telemetry to work and fixes multiprocess mode in general.

Implementation notes

• Telemetry is initialized before the CLI logger is created so the active-span lookup in the logger mixin is meaningful from the first request.
• Metric instruments are created inside createServer (after the MeterProvider is registered), not at module load, so they bind to the real meter rather than a no-op.
• Log correlation uses a pino mixin rather than @opentelemetry/instrumentation-pino: pino is required at module load, before the flag-driven SDK init runs, so the auto-instrumentation's require-hook can't patch it.

Testing

• Unit tests for telemetry init (enabled/disabled, HTTP/gRPC, metrics) and the shutdown-flush handler.
• End-to-end harness test asserting --otel-telemetry does not change served responses.
• Manually validated end to end against a grafana/otel-lgtm collector (also added as a runnable demo): traces visible in Tempo, request + Node VM metrics in Prometheus, and trace_id in logs — over both HTTP and gRPC, single- and multi-process.

Checklist

• The basics
  • I tested these changes manually in my local or dev environment
• Tests
  • Added or updated
• Event Tracking
  • N/A
• Error Reporting
  • N/A