GeekDas
••10 min read
GeekdasGeekdas

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

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 traceparent HTTP 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-http

The 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.js

The 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:latest

Start 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, https or fetch

  • spans 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 a finally block, 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.1

This 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

  1. Add auto-instrumentation and traces to one service, with Jaeger locally.

  2. Deploy it behind a sampling rate and confirm that the overhead is acceptable.

  3. Add custom spans around your two or three most important operations.

  4. Add request and error metrics and one alert for elevated error rate or latency.

  5. Include trace IDs in logs.

  6. 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...

Frequently Asked Questions

What is OpenTelemetry in simple terms?
OpenTelemetry is an open standard and set of libraries for collecting traces, metrics and logs from your applications. You instrument your code once and send the data to any compatible backend, such as Jaeger, Grafana or Datadog, without being tied to a single vendor.
Do I need to change my code to use OpenTelemetry with Node.js?
Not much. Auto-instrumentation patches popular libraries such as Express, HTTP clients and database drivers, so you only add a tracing file and start Node with it preloaded. You add custom spans only where you want extra detail about your own business logic.
Does OpenTelemetry slow down my application?
There is some overhead, usually small for tracing at reasonable sampling rates. Reduce it by sampling a percentage of traces, batching exports, keeping attributes small and running a Collector to take processing off your app. Measure in a staging environment before rolling out widely.
What is the difference between OpenTelemetry and Jaeger?
OpenTelemetry is the standard for generating and exporting telemetry data. Jaeger is a backend that stores traces and provides a UI to view them. You can use OpenTelemetry with Jaeger, or with many other backends, which is the whole point of the standard.
Do I need the OpenTelemetry Collector?
Not for a small project, because your app can export straight to a backend. The Collector becomes valuable when you have several services, want to filter sensitive data, need tail-based sampling or want to send data to more than one destination.
Why are my database queries not showing up as spans?
The most common cause is load order. The tracing file must be loaded before your application imports the database driver, for example with the require flag. Also check that the driver is supported by the auto-instrumentation package and that the instrumentation is not disabled in your configuration.

Related Articles