feat(metrics): Add OTEL to api

[jsingleton-dev]

This PR adds OTEL tracing and metrics instrumentation to the API. We already have it in the workspace-engine, but this will give us tracing and o11y on our API layer.

Screen.Recording.2026-05-06.at.12.50.35.PM.mov

Summary by CodeRabbit

• New Features

  • Added OpenTelemetry integration for enhanced observability and monitoring of API operations, database queries, and HTTP requests.
  • Introduced configurable tracing middleware for improved request tracking and performance insights.

• Documentation

  • Updated installation guide with OpenTelemetry configuration options and environment variables.

[coderabbitai]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Walkthrough

This PR integrates OpenTelemetry instrumentation across the API and TRPC packages by adding SDK dependencies, configuring exporters via environment variables, implementing the instrumentation initialization logic, wiring up tracing middleware in TRPC, and updating relevant documentation.

Changes

OpenTelemetry Instrumentation

Layer / File(s)	Summary
Dependencies & Configuration apps/api/package.json, packages/trpc/package.json, apps/api/src/config.ts	OpenTelemetry packages added (@opentelemetry/api, OTLP exporters, instrumentations for Express, HTTP, PG, runtime). Environment variables OTEL_SERVICE_NAME and OTEL_EXPORTER_OTLP_ENDPOINT added to config with defaults.
Core Instrumentation Setup apps/api/src/instrumentation.ts	New file configures NodeSDK with resource attribution, parent-based sampling, OTLP trace and metric exporters, and instrumentations for HTTP, Express, PostgreSQL, and Node runtime. Implements startup logging and graceful shutdown on signals.
TRPC Integration packages/trpc/src/trpc.ts	OpenTelemetry tracer created and tracing middleware added to publicProcedure, which spans each TRPC call, attaches call metadata, and marks errors.
Startup Wiring apps/api/package.json	Dev and start scripts updated to import and initialize instrumentation.ts during startup.
Documentation docs/installation.mdx	Documentation expanded with OTEL_SDK_DISABLED toggle and OTEL_EXPORTER_OTLP_ENDPOINT configuration details.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• ctrlplanedev/ctrlplane#189: Adds OpenTelemetry instrumentation and configuration across services with shared environment variables like OTEL_EXPORTER_OTLP_ENDPOINT.

Suggested reviewers

• jsbroks

Poem

🐰 Observability hops into view,
Telemetry spans trace what you do,
From API to TRPC with care,
OpenTelemetry's now everywhere!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(metrics): Add OTEL to api' clearly and concisely summarizes the main change: adding OpenTelemetry instrumentation to the API service for observability.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jsingleton/api-otel

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[jsingleton-dev]

This one isn't strictly required for tracing to work in the API, but without this we won't see which trpc procedure is called in the traces. You can see in my demo that this will add a sub-span for each trpc proc so it's clear which query this is coming from.

[jsingleton-dev]

For both workspace-engine and now api, we have localhost as the default so if OTEL is not disabled it'll keep trying to send traces to a non-existent local service. This is the standard env var to disable OTEL but just calling out out here in the docs.

[jsingleton-dev]

We need this imported before express. Alternative to adding it here is to make it the first require in the server file, but I figured this was cleaner. Open to changing it though because I'm not super crazy about it here either.