OpenTelemetry Node.js: The Basics and a Quick Tutorial

What Is OpenTelemetry Node.js? 

OpenTelemetry is an open-source observability framework for generating, collecting, and describing telemetry data from your software services and applications. It is an observability toolkit that includes APIs for tracing, metrics, and logs. OpenTelemetry provides instrumentation for Node.js and many other languages and frameworks.

The OpenTelemetry project is the result of a merger between OpenCensus and OpenTracing, two prominent open-source observability solutions. The project is dedicated to making telemetry a built-in feature of cloud-native software, and it’s supported by the Cloud Native Computing Foundation.

In the context of Node.js, OpenTelemetry provides a single set of APIs to capture distributed traces and metrics from their applications, allowing them to understand their software’s performance and behavior. This will enable you to create observability for your Node.js applications, identify issues quickly, and understand exactly what’s happening within complex software systems. 

However, it’s important to understand that OpenTelemetry is not a full observability solution—it must be integrated with monitoring or troubleshooting systems which make use of its metrics.

Benefits of OpenTelemetry in the Node.js Ecosystem

Enhanced Observability

With OpenTelemetry, you get a complete picture of what’s happening within your system at any given time. This includes performance metrics, logs, and traces, which can all be collected and analyzed in one place.

Observability is crucial in a complex software environment, where applications are often distributed across multiple services and platforms. With OpenTelemetry, in combination with the appropriate monitoring or troubleshooting tools, you can gain insight into the entire lifecycle of a request, from the initial user interaction to the final output. This can help you identify bottlenecks, understand dependencies, and improve your applications’ overall performance and reliability.

Simplified Instrumentation

OpenTelemetry simplifies the process of instrumenting your applications. Instrumentation is the process of adding observability to your software. This can be a complex task, especially in large, distributed systems. However, OpenTelemetry provides a unified, easy-to-use API that simplifies this process.

With OpenTelemetry, you can instrument your applications with just a few lines of code. It supports both auto instrumentation, which is effortless and lets you collect standard metrics from your applications, and provides an easy-to-use API for adding custom instrumentation to collect metrics specific to your Node.js applications.

Cross-Language Consistency

OpenTelemetry provides APIs and SDKs for various commonly used programming languages, including Node.js, Java, and Python. This means that you can use the same observability framework across all of your applications, regardless of the language they’re written in.

This cross-language consistency brings several benefits. It reduces the learning curve, because you only need to familiarize yourself with one set of APIs. It also simplifies maintaining and updating your observability stack, as you can update all your applications at once rather than having to update each one individually.

Performance Insights

By collecting and analyzing telemetry data, you can better understand how your applications are performing. You can see which parts of your system are slow, which ones are error-prone, and which ones are functioning smoothly.

These performance insights can help you identify and resolve issues quickly before they impact your users. They can also guide your optimization efforts, helping you make informed decisions about where to invest your resources.

Related content: Read our guide to OpenTelemetry architecture

Tutorial: Auto-Instrumenting Node.js Apps with OpenTelemetry and Jaeger 

Here are the main steps involved in auto-instrumenting your Node.js apps and exporting the traces to Jaeger, an open-source distributed tracing solution. 

If you want to go a step further and collect custom metrics from your application, see the OpenTelemetry documentation for manual instrumentation.

Install OpenTelemetry Packages

The first step in adding the Node.js OpenTelemetry package to your application, is installing the necessary packages using Node Package Manager (npm). To do so run the following commands within your application root directory via terminal:

npm i @opentelemetry/api @opentelemetry/node @opentelemetry/tracing @opentelemetry/exporter-jaeger

These commands will install the OpenTelemetry API, Node functionality, tracing packages, and any required dependencies. Once the installation is complete, verify that the packages have been successfully installed. You can check this by looking at the node_modules directory or using the npm list command.

Add a Tracer to the Node.js Application

The tracer is a vital component of the OpenTelemetry Node.js system as it creates and manages the spans. Spans are units of work within a trace, representing a single operation within a trace.

To add a tracer, you first need to initialize it in your application. This is done by including the following lines of code at the beginning of your main application file:

const { NodeTracerProvider } = require('@opentelemetry/node');
const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');

const provider = new NodeTracerProvider();
const exporter = new JaegerExporter({
  serviceName: 'my-service',
});

provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();

This block of code initializes the NodeTracerProvider, which handles automatic instrumentation in Node.js applications. It also sets up the JaegerExporter (for exporting traces to Jaeger) and registers the provider with OpenTelemetry to make it available globally.

Set Up OpenTelemetry Collector to Collect and Export Traces

It’s important to note that for this next section you will need to have Jaeger installed in your development environment, follow this link to find out how to get started with Jaeger.

The OpenTelemetry collector is a vendor-agnostic implementation that can receive, process, and export telemetry data. This means your applications can send data to the collector, and it will export the data to your analytics platform.

To set up the collector, you need to create a configuration file. This file specifies the receivers, processors, and exporters that the collector will use. Here is an example of a simple configuration file:

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:

exporters:
  logging:
  jaeger:
    endpoint: "localhost:14250"
    insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging, jaeger]

In this configuration, we’ve specified an OTLP receiver (which accepts data in the OpenTelemetry Protocol format), a batch processor (which batches the data before sending it), and two exporters (one for logging the data and one for sending the data to Jaeger).

Verify Traces in Jaeger UI

Finally, after setting up all the components, it’s time to run the application and verify if everything is working as expected.

Start your application by running node app.js in the terminal. Once your application is running, it should start sending trace data to the OpenTelemetry Collector. The collector, in turn, will process this data and send it to Jaeger.

To verify that everything is working correctly, open the Jaeger UI in your web browser. You should see your service listed in the dropdown menu. Choose your service and click on Find Traces. If everything works correctly, you should see a list of traces from your application.

Microservices Monitoring with Lumigo

Lumigo is cloud native observability tool that provides automated distributed tracing of microservice applications and supports OpenTelemetry for reporting of tracing data and resources. With Lumigo, users can:

• See the end-to-end path of a transaction and full system map of applications
• Monitor and debug open-source libraries like ExpressJS and Python Flask, and managed services like. Amazon DynamoDB, Twilio, Stripe
• Go from alert to root cause analysis in one click with no code changes
• Understand system behavior and explore performance and cost issues 
• Group services into business contexts

Get started with a free trial of Lumigo for your microservice applications