OpenTelemetry for Node.js: Add Tracing, Metrics and Logs to an Express API

When a request is slow in production, the first question is always the same: where did the time go? Was it your route handler, the database, a call to a payment provider or a cache miss? Without proper observability, you end up adding console.log lines, redeploying and guessing. With OpenTelemetry, you can see the whole journey of a request, every database query and outbound call included, in one view.
OpenTelemetry, usually shortened to OTel, is the open standard for collecting traces, metrics and logs from your applications. It is vendor neutral, so you can send the data to Jaeger, Grafana, Datadog, New Relic, Honeycomb or any other backend that understands its protocol. This guide shows how to add it to a Node.js Express API from scratch, with working code and the pitfalls to avoid.
Why observability matters (and what OpenTelemetry gives you)
Monitoring tells you that something is wrong. Observability helps you work out why. OpenTelemetry covers three signals, and each answers a different question.
The three signals
Traces show the path of a single request across functions and services, with timings. They answer "why was this request slow?"
Metrics are numbers over time, such as request rate, error rate and latency percentiles. They answer "is the system healthy right now?"
Logs are timestamped records of events. Linked to traces, they answer "what exactly happened during this request?"
Why a standard helps
Before OpenTelemetry, each monitoring vendor shipped its own agent and data format, and switching vendors meant re-instrumenting your code. With OTel, you instrument once and choose or change the backend with configuration. It is a Cloud Native Computing Foundation project with broad vendor support, which is why many teams are adopting it.
Core concepts in five minutes
Span: one unit of work with a name, start time, duration and attributes, such as "GET /orders" or "SELECT from users".
Trace: a tree of spans that belong to one request.
Context propagation: the mechanism that carries a trace ID between functions and across services, usually through the
traceparentHTTP header.Resource: attributes describing the service itself, such as its name and version.
Exporter: the component that sends data out, usually using OTLP, the OpenTelemetry protocol.
Collector: an optional standalone process that receives data, processes it and forwards it to one or more backends.
Step 1: Set up a small Express API
If you already have a service, skip ahead. Otherwise, here is a minimal one to instrument:
// server.js
const express = require('express');
const app = express();
app.get('/orders/:id', async (req, res) => {
await new Promise((resolve) => setTimeout(resolve, 80)); // pretend database work
res.json({ id: req.params.id, status: 'shipped' });
});
app.listen(3000, () => console.log('Listening on 3000'));If you are new to building APIs, our REST API guide covers the fundamentals.
Step 2: Install the OpenTelemetry packages
npm install @opentelemetry/sdk-node \
@opentelemetry/auto-instrumentations-node \
@opentelemetry/exporter-trace-otlp-httpThe sdk-node package wires everything together. The auto-instrumentations package bundles instrumentation for popular libraries, including Express, HTTP, many database drivers, Redis and more, so you get spans without changing your handlers.
Step 3: Create the tracing file
Create a separate file that starts the SDK, and load it before your application code:
// tracing.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const sdk = new NodeSDK({
// Defaults to http://localhost:4318/v1/traces (OTLP over HTTP)
traceExporter: new OTLPTraceExporter(),
instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
process.on('SIGTERM', () => {
sdk.shutdown().finally(() => process.exit(0));
});Load order matters
Instrumentation works by patching modules when they are first required. If Express or your database driver is loaded before the SDK starts, those calls will not be traced. Start your app with the tracing file loaded first:
OTEL_SERVICE_NAME=orders-api node --require ./tracing.js server.jsThe official getting-started guide uses node --import ./instrumentation.mjs app.js with an ES module file, and --import also works with a CommonJS file on current Node versions. Either way, the SDK must start before your app code. Setting OTEL_SERVICE_NAME is important. Without it, every service shows up under a generic name, which makes dashboards confusing.
Step 4: See your first trace locally
Jaeger is a free trace viewer that accepts OTLP. Current Jaeger versions accept OTLP on ports 4317 and 4318 out of the box. Run it with Docker:
docker run --rm -p 16686:16686 -p 4317:4317 -p 4318:4318 jaegertracing/jaeger:latestStart your app, call http://localhost:3000/orders/42 a few times and open http://localhost:16686. Pick the orders-api service and click a trace. You will see a span for the incoming HTTP request, spans for Express middleware and your route handler, and the duration of each. If you ever called a database or another API, those would appear as child spans too.
What auto-instrumentation gives you for free
Without writing any tracing code, you typically get:
spans for every incoming HTTP request, with method, route and status code
spans for outgoing HTTP calls made with
http,httpsorfetchspans for queries to common database drivers and clients, such as PostgreSQL, MySQL, MongoDB and Redis (check the OpenTelemetry registry for your exact library and version)
context propagation, so a trace continues across services that also use OpenTelemetry
For quick wins, that is usually enough to find the slow query or the sluggish third-party API.
Step 5: Add custom spans for your business logic
Auto-instrumentation sees libraries, not your domain. When a handler does several meaningful steps, wrap them in your own spans so the trace tells a readable story.
const { trace, SpanStatusCode } = require('@opentelemetry/api');
const tracer = trace.getTracer('orders-api');
async function calculateShipping(order) {
return tracer.startActiveSpan('calculate-shipping', async (span) => {
try {
span.setAttribute('order.items', order.items.length);
const cost = await shippingProvider.quote(order);
span.setAttribute('shipping.cost', cost);
return cost;
} catch (err) {
span.recordException(err);
span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
throw err;
} finally {
span.end();
}
});
}Rules for good spans
Always call
span.end(), ideally in afinallyblock, or the span never ships.Record exceptions and set the error status so failed requests stand out.
Name spans after the operation, not the data. Use "calculate-shipping", not "calculate-shipping-for-order-8841".
Keep attributes low in cardinality. A user ID on a span is usually fine, but unique values on a metric label can overload your backend.
Step 6: Add metrics
Traces are great for investigating individual requests. Metrics are better for dashboards and alerts. Some auto-instrumentations emit useful HTTP metrics once a metric reader is configured. Without one, the metrics API does nothing. You can also define your own.
const { metrics } = require('@opentelemetry/api');
const meter = metrics.getMeter('orders-api');
const ordersCreated = meter.createCounter('orders.created', {
description: 'Number of orders created',
});
const checkoutDuration = meter.createHistogram('checkout.duration', {
description: 'Time taken to complete checkout',
unit: 'ms',
});
// inside a handler
ordersCreated.add(1, { 'payment.method': 'upi' });
checkoutDuration.record(elapsedMs, { 'payment.method': 'upi' });To export them, add a periodic metric reader with an OTLP metric exporter to the NodeSDK configuration, or enable the exporters through environment variables if your SDK version supports it. Start with a few high-value metrics: request rate, error rate, latency percentiles and one or two business numbers such as orders or signups.
Step 7: Connect logs to traces
A log line is far more useful when you can jump from it to the trace it belongs to. The simplest approach is to include the current trace and span IDs in every log entry. With a structured logger such as Pino, its OpenTelemetry instrumentation can add them for you. You can also do it manually. Log export through OpenTelemetry itself is still under development in JavaScript, so correlating IDs in your existing logger is the safer route today:
const { trace } = require('@opentelemetry/api');
function log(message, extra = {}) {
const span = trace.getActiveSpan();
const ctx = span ? span.spanContext() : {};
console.log(JSON.stringify({ message, traceId: ctx.traceId, spanId: ctx.spanId, ...extra }));
}Now, when a user reports an error, you search your logs by trace ID, then open the exact trace to see the timing of every step.
Sampling: control volume and cost
Tracing every request in a busy system can be expensive. Sampling keeps a fraction. The simplest option is a ratio, configured through environment variables:
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1This keeps about 10 percent of traces and respects the decision made by the upstream service, so a trace is either complete or absent. For production, consider keeping all error traces and slow traces, which usually requires tail-based sampling in the Collector.
Using the OpenTelemetry Collector in production
Sending data straight from your app to a backend works for small setups. As you grow, run a Collector between them. It lets you:
batch, retry and compress data so your app does less work
remove sensitive attributes before data leaves your network
fan out to several backends during a migration
apply tail-based sampling and other processing in one place
Apps send OTLP to the Collector on port 4317 (gRPC) or 4318 (HTTP), and the Collector exports to your chosen backend. Teams often deploy it as a sidecar or a small shared service.
Common pitfalls and how to avoid them
Instrumentation mistakes
Starting the SDK too late
If you see no database spans, check the load order first. The tracing file must run before anything else imports the instrumented libraries.
Forgetting to shut down cleanly
On shutdown, call sdk.shutdown() so buffered data is flushed. Otherwise, you lose the last seconds of telemetry, which are often the most interesting ones.
Data and cost mistakes
Capturing sensitive data
Do not put passwords, tokens, full card numbers or personal details into span attributes or log lines. Telemetry is often stored for weeks and visible to many people. If you handle Indian user data, this ties in closely with the DPDP Act; see our DPDP checklist for developers.
High-cardinality attributes
Metric labels such as user IDs, email addresses or request IDs create an enormous number of time series and can break dashboards or bills. Keep labels to small, bounded sets, like HTTP method, route template or payment method.
A practical rollout plan
Add auto-instrumentation and traces to one service, with Jaeger locally.
Deploy it behind a sampling rate and confirm that the overhead is acceptable.
Add custom spans around your two or three most important operations.
Add request and error metrics and one alert for elevated error rate or latency.
Include trace IDs in logs.
Introduce a Collector when you add a second service or a second backend.
If you want help setting up observability for a Node.js backend, or building a reliable API from the start, see my custom web application development service or get in touch.
Conclusion
OpenTelemetry takes the guesswork out of debugging production. A few dozen lines of setup gives you traces for every request, and each step after that, from custom spans to metrics and log correlation, adds clarity without locking you into a vendor. Start small with one service and a local Jaeger, learn what your traces reveal, and expand from there.
Was this article helpful?



Comments
Leave a comment
Loading comments...