Skip to content

feat(http-server): add OpenTelemetry tracing (Phase 1)#2805

Open
Ignacio-Vidal wants to merge 2 commits into
stoplightio:masterfrom
Ignacio-Vidal:feature/otel-telemetry-phase1
Open

feat(http-server): add OpenTelemetry tracing (Phase 1)#2805
Ignacio-Vidal wants to merge 2 commits into
stoplightio:masterfrom
Ignacio-Vidal:feature/otel-telemetry-phase1

Conversation

@Ignacio-Vidal

@Ignacio-Vidal Ignacio-Vidal commented Jun 13, 2026

Copy link
Copy Markdown

Refs #2804

Summary

Adds OpenTelemetry (OTel) tracing to the Prism HTTP service (Phase 1 of #2804). Telemetry is opt-in via a configuration flag, and the OTLP/HTTP exporter endpoint is configurable, so users can point Prism at any remote OTel collector (Jaeger, Grafana Tempo, Datadog, an OpenTelemetry Collector, etc.).

When disabled (the default), Prism behaves exactly as before — the OTel SDK is never started and there is no overhead.

What's included

  • New telemetry init module (packages/http-server/src/telemetry.ts): initTelemetry() wires up the OTel NodeSDK with an OTLP/HTTP trace exporter and HTTP auto-instrumentation. It is a no-op when disabled.
  • The Micri request handler is wrapped in a server span when telemetry is enabled, recording request method, path, response status code, and exceptions on the error path.
  • New CLI flags on both mock and proxy:
    • --telemetry (also via PRISM_TELEMETRY env var)
    • --otel-exporter-url (also via OTEL_EXPORTER_OTLP_ENDPOINT)
    • --otel-service-name (also via OTEL_SERVICE_NAME, defaults to prism)
    • CLI flags take precedence over env vars.
  • Unit test for the telemetry module (enabled + disabled paths).
  • End-to-end harness test asserting that enabling --telemetry does not change the served response.

Example usage

# Mock server with tracing to a local collector
prism mock api.oas.yaml \
  --telemetry \
  --otel-exporter-url http://localhost:4318/v1/traces \
  --otel-service-name prism-mock

# Proxy server, configured via standard OTel env vars
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 \
OTEL_SERVICE_NAME=prism-proxy \
prism proxy api.oas.yaml https://upstream.example.com --telemetry

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

Additional context

  • New runtime dependencies were added to packages/http-server/package.json (per CONTRIBUTING): @opentelemetry/sdk-node, @opentelemetry/api, @opentelemetry/exporter-trace-otlp-http, @opentelemetry/instrumentation-http, @opentelemetry/resources, @opentelemetry/semantic-conventions.
  • Verified manually with the mock server (200/401/422 responses) and via the compiled binary that the OTel SDK bundles correctly and does not block startup when no collector is reachable.
  • npm test passes (full suite). The new harness test passes; the only failing harness tests locally are the pre-existing proxy/* cases that require a reachable httpbin upstream.

@Ignacio-Vidal Ignacio-Vidal requested a review from a team as a code owner June 13, 2026 08:46
@Ignacio-Vidal Ignacio-Vidal force-pushed the feature/otel-telemetry-phase1 branch from abfd662 to 15e6161 Compare June 13, 2026 08:46
@Ignacio-Vidal Ignacio-Vidal changed the title feat(http-server): add OpenTelemetry tracing (Phase 1) DRAFT: feat(http-server): add OpenTelemetry tracing (Phase 1) Jun 13, 2026
@Ignacio-Vidal Ignacio-Vidal force-pushed the feature/otel-telemetry-phase1 branch 2 times, most recently from ab756b2 to 6abd618 Compare June 13, 2026 09:05
Add OpenTelemetry tracing to the Prism HTTP service, toggled via a
configuration flag with a configurable OTLP/HTTP exporter.

- New telemetry module (initTelemetry) sets up the OTel NodeSDK with an
  OTLP/HTTP trace exporter and HTTP auto-instrumentation; no-op when disabled.
- Micri request handler is wrapped in a server span when enabled, recording
  method, path, response status code, and exceptions.
- CLI flags --telemetry, --otel-exporter-url, --otel-service-name on both
  mock and proxy, with PRISM_TELEMETRY / OTEL_* env-var fallbacks.
- Flush and shut down the OTel SDK on SIGINT/SIGTERM so spans buffered by the
  BatchSpanProcessor are exported instead of dropped on exit.
- Unit tests for the telemetry module and the shutdown-flush handler.

Single-process only; multiprocess hardening and metrics deferred to later phases.

Refs stoplightio#2804
Verifies that enabling OpenTelemetry tracing via --telemetry does not affect
the served response: the server span wraps the request handler transparently
and the mock response is returned as normal.

Refs stoplightio#2804
@Ignacio-Vidal Ignacio-Vidal force-pushed the feature/otel-telemetry-phase1 branch from 6abd618 to 89197bd Compare June 13, 2026 09:42
@Ignacio-Vidal Ignacio-Vidal changed the title DRAFT: feat(http-server): add OpenTelemetry tracing (Phase 1) feat(http-server): add OpenTelemetry tracing (Phase 1) Jun 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant