Mastering Distributed Tracing with OpenTelemetry in Node.js

2026-05-03·4 min readobservability

Learn to implement end-to-end observability for your Node.js applications.

Dive into distributed tracing with OpenTelemetry in Node.js. This post guides you through setting up tracing, instrumenting your code, and visualizing traces to debug complex microservices architectures effectively.

#opentelemetry #nodejs #distributed_tracing #observability #microservices

Introduction

In today's complex, distributed systems, understanding how requests flow through various services is crucial for debugging, performance optimization, and maintaining system health. Traditional logging often falls short, providing only a fragmented view of an application's behavior. This is where distributed tracing comes into play, offering end-to-end visibility into the lifecycle of a request across multiple services.

OpenTelemetry has emerged as the open-source standard for instrumenting, generating, collecting, and exporting telemetry data (traces, metrics, and logs). By adopting OpenTelemetry, you can gain deep insights into your Node.js applications, regardless of their scale or architectural complexity. This guide will walk you through setting up and utilizing OpenTelemetry for distributed tracing in a Node.js environment.

Understanding Distributed Tracing and OpenTelemetry

Distributed tracing provides a detailed breakdown of how a request is processed across different services. It visualizes the path of a request as a trace, which is composed of multiple spans. Each span represents a single operation within a service, such as an HTTP request, a database query, or a function call. Spans are organized hierarchically, showing parent-child relationships and the duration of each operation.

OpenTelemetry simplifies the process of generating and collecting this telemetry data. It offers a vendor-agnostic API, SDKs for various languages (including Node.js), and an OTLP (OpenTelemetry Protocol) exporter to send data to a backend of your choice, such as Jaeger, Zipkin, or commercial observability platforms. This standardization means you're not locked into a specific vendor and can easily switch or integrate with different tools.

Setting Up OpenTelemetry in Node.js

To begin tracing your Node.js application, you'll need to install the necessary OpenTelemetry packages. This typically involves the core API and SDK, a tracing package, and an exporter to send your traces to a collector or backend. For this example, we'll use the OTLP exporter and instrument common libraries like HTTP and Express.

Install the required OpenTelemetry packages:

npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-http

Next, you'll need to configure an OpenTelemetry instance in your application's entry point. This setup typically involves initializing the NodeSDK, registering instrumentations for libraries you want to trace, and configuring an exporter. It's best practice to do this as early as possible in your application's lifecycle.

// tracer.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
 
const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces', // Replace with your OTLP collector endpoint
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
 
sdk.start();
 
console.log('OpenTelemetry tracing initialized.');
 
process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

Make sure to import and run this tracer.js file at the very beginning of your main application file (e.g., require('./tracer'); before any other imports). This ensures that all subsequent modules and operations are properly instrumented.

Manual Instrumentation and Context Propagation

While auto-instrumentation covers many common libraries, you might need to manually instrument specific parts of your code to capture business-specific logic or custom operations. OpenTelemetry provides an API for creating custom spans and managing context propagation.

// app.js (example Express app)
require('./tracer'); // Initialize OpenTelemetry first
const express = require('express');
const { trace, context, SpanStatusCode } = require('@opentelemetry/api');
 
const app = express();
const PORT = process.env.PORT || 3000;
const tracer = trace.getTracer('my-app-tracer');
 
app.get('/hello', async (req, res) => {
  // Get the current context, which should contain the parent span from auto-instrumentation
  const parentContext = context.active();
 
  // Create a new span that is a child of the current active span
  const span = tracer.startSpan('say-hello-operation', {}, parentContext);
 
  try {
    // Simulate some asynchronous work
    await new Promise(resolve => setTimeout(resolve, 100));
 
    span.setAttribute('user.id', '123');
    span.addEvent('fetching_user_data');
 
    res.send('Hello, World!');
  } catch (error) {
    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
    res.status(500).send('Error');
  } finally {
    span.end(); // End the span
  }
});
 
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

In this example, we manually create a span named say-hello-operation within our Express route. We also add attributes and events to enrich the trace data, providing more context about what happened during that operation. The context.active() ensures that our manually created span is correctly linked to the parent span created by the auto-instrumentation, maintaining the integrity of the trace.

Conclusion

Distributed tracing with OpenTelemetry is an indispensable tool for any full-stack engineer working with distributed systems. It transforms opaque request flows into clear, actionable insights, drastically reducing the time and effort required for debugging and performance analysis. By following the steps outlined in this guide, you can effectively instrument your Node.js applications and unlock a new level of observability.

Embrace OpenTelemetry to gain a comprehensive understanding of your application's behavior, optimize its performance, and build more resilient and maintainable systems. The journey to full observability starts with a single trace.

Happy tracing!

Other Blogs