OpenTelemetry NestJS Guide: Distributed Tracing in Production (2026)

Q: What does OpenTelemetry give me that logs alone do not?

Logs are local; traces are global. A log line says "service A returned 500 to request X." A trace says "request X originated at the API gateway, passed through service A which called service B which called service C, where the database query took 18 seconds and timed out." The trace shows the causal chain across processes; the logs show the symptoms in isolation. In a NestJS microservices system, the difference is the difference between an investigation that takes minutes and one that takes hours. A trace is a tree of spans sharing a trace ID, with parent-child relationships expressed via parent span IDs. Each span has a name (typically the operation), a start and end time, a status (OK or error), and arbitrary key-value attributes. The collection of spans across all services forms the waterfall view that the trace UI displays. Logs remain useful for the detail of what happened inside a single span; traces are what tell you which spans existed in the first place and how they relate.

Q: How do I set up OpenTelemetry in a NestJS application?

Three steps. First, install the OpenTelemetry Node SDK plus auto-instrumentation packages (@opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node, @opentelemetry/exporter-trace-otlp-http). Second, create a tracing.ts file that initialises the NodeSDK with a Resource (service name, version, environment), an OTLP exporter pointing to your collector, and the auto-instrumentations (with @opentelemetry/instrumentation-fs disabled because it is noisy). Third — and this is critical — make import './tracing' the literal first line of main.ts, before NestFactory or any other import. The instrumentations patch Node modules at load time; if NestJS modules are imported before the SDK starts, the patches do not apply and you get zero spans. With this setup, the auto-instrumentations cover HTTP server, HTTP client, TypeORM/Prisma, Redis, PostgreSQL, BullMQ and most major libraries automatically, producing a complete distributed trace with no application code changes.

Q: When should I add custom spans versus relying on auto-instrumentation?

Auto-instrumentation captures infrastructure (HTTP requests, database queries, queue operations); custom spans capture business operations. The placement of an order is a business operation that includes "validate the cart," "apply the discount," "reserve inventory," and "calculate shipping" — none of which the auto-instrumentation knows about, all of which an engineer reading the trace will want to see as distinct spans. Use the OpenTelemetry tracer to wrap business methods in startActiveSpan, attach business-meaningful attributes (customer.id, order.total, discount.code), record exceptions if they occur, and end the span when the operation completes. The span name should be the operation (placeOrder.execute), not the URL — when the URL changes, the trace queries for the business operation continue to work. To reduce boilerplate, write a @Traced() decorator that wraps a method in a span using the class and method name automatically, captures exceptions, and records status. Apply it to controllers, use cases, and any other layer where business operations live.

Q: Should I choose Jaeger, Tempo, Honeycomb or something else?

Always export OTLP from the application; the back-end is what varies. Jaeger is the canonical open-source self-hosted choice — mature, free, runs on Kubernetes with an operator, with Elasticsearch/OpenSearch storage. Right when you have operational capacity for a tracing back-end and the workload does not justify SaaS. Grafana Tempo stores traces cheaply in object storage (S3/GCS) with no separate index, queries by trace ID directly, and integrates with Grafana alongside Prometheus and Loki — right when Grafana is already your observability hub and you want the "all telemetry in one UI" experience. Honeycomb (and Lightstep, New Relic, Datadog APM) are SaaS — Honeycomb in particular has an excellent query model for slicing by high-cardinality attributes without pre-aggregation. Right when engineering time saved exceeds the ingestion bill, which it usually does until traffic gets very large. The decision is reversible: switching from Jaeger to Tempo to Honeycomb is a configuration change (the OTLP endpoint), not a code change.

Q: How do I correlate traces with logs in NestJS?

Inject the active trace ID and span ID into every log line. Configure your logger (Pino, Winston, NestJS Logger) to read the active span from the OpenTelemetry context on every log call and add trace_id and span_id fields to the structured log output. With Pino, use the mixin option: trace.getSpan(context.active())?.spanContext() returns { traceId, spanId } which you spread into the log. With this in place, every log line is joined to its trace by a key the back-end can index. Engineers can pivot from a log line to the trace UI in one click and from the trace UI to the relevant logs for any span. The same correlation extends across services because the trace ID propagates via the W3C traceparent header (HTTP) and equivalent context carriers (gRPC, queues). Optionally maintain a separate, shorter X-Request-ID for user-facing references (support tickets, error pages); many teams use the trace ID directly as the request ID, which works as long as the 32-hex-character format is acceptable.

Q: What sampling strategy should I use in production?

Always keep error traces at 100 per cent; sample success traces at a rate the budget allows. The standard production setup is head sampling at 100 per cent (record every span in the SDK) plus tail sampling at the collector to make the keep/drop decision after the trace completes. Tail sampling rules: keep all traces with any span in error state, keep all traces over 1 second, keep 10 per cent (or whatever rate the budget allows) of OK traces under 1 second. This guarantees every production failure has a complete trace, every slow operation is captured for performance debugging, and storage is focused on the traces that matter. Head-only sampling is cheaper and decentralised but cannot make decisions based on what happened during the trace; tail-only sampling captures the right traces but requires buffering at the collector. The hybrid approach (head 100% + tail filtering) is what most production setups end up with. A service handling 1000 RPS produces 86 million traces per day; storing them all is unaffordable, so the sampling strategy is doing real work to make the budget viable.

Q: What is the performance overhead of OpenTelemetry?

The CPU overhead is typically 1 to 5 per cent for a typical NestJS service. Auto-instrumentation adds work for each instrumented operation — capturing timestamps, creating span objects, attaching attributes, queueing for export — but for HTTP and database calls the overhead is negligible compared to the call itself. For very tight loops with millions of cheap operations per second, the overhead becomes visible, but those operations should not be individually traced anyway. Network and storage cost is more significant than CPU: a trace with twenty spans and W3C context propagation produces a few kilobytes, and at high request rates the volume becomes substantial. The OTLP exporter batches spans (every 5 seconds or 512 spans, whichever comes first) to amortise network cost, and the collector compresses before forwarding. Always use the batch span processor in production (the default in NodeSDK); the simple processor exports synchronously on every span end and turns a slow collector into a slow application. The asynchronous batch exporter never blocks the request, so a slow or unreachable collector cannot slow down the application.

Q: What are the most common mistakes when setting up OpenTelemetry in NestJS?

Five common mistakes. First, importing the tracing module after the application starts — the instrumentations patch modules at load time; if NestJS modules are imported before the SDK starts, you get zero spans. Make import './tracing' the literal first line of main.ts. Second, using the simple span processor in production, which exports synchronously on every span end and blocks every request on a network call to the collector. Always use the batch span processor. Third, leaving noisy auto-instrumentations enabled — @opentelemetry/instrumentation-fs creates spans for every file system call, drowning the signal with millions of useless spans. Disable it. Fourth, recording high-cardinality attributes naively (user.email creates a new value for every user); reserve high-cardinality attributes for back-ends that handle them (Honeycomb), and prefer lower-cardinality alternatives (user.region, user.tier) for back-ends that don't. Fifth, forgetting to propagate context across asynchronous boundaries — when a request ends and an async job is enqueued, the trace context must travel with the message; major queue auto-instrumentations do this, but custom queue or event bus code needs explicit propagation.inject() / propagation.extract() calls.

Satyam Kumar

返回博客

microservices-patterns

OpenTelemetry for NestJS: Distributed Tracing in Production (2026)

By Satyam KumarApril 25, 202617 min read

OpenTelemetry NestJS observability distributed tracing OTLP auto-instrumentation custom spans Jaeger Grafana Tempo Honeycomb tail sampling head sampling correlation IDs trace context propagation W3C traceparent Pino logging BullMQ tracing TypeORM tracing production observability

OpenTelemetry for NestJS: Distributed Tracing in Production (2026)

Frequently Asked Questions

分享这篇文章

Twitter LinkedIn WhatsApp

Satyam Kumar

Founder & AI Architect, AppScale LLP

人工智能和云架构师。帮助团队构建可扩展到数百万的系统。

LinkedIn GitHub

OpenTelemetry for NestJS: Distributed Tracing in Production (2026)

Frequently Asked Questions

分享这篇文章

Comments

Leave a comment