Unleashing the power of OpenTelemetry auto-instrumentation in JavaScript

TL;DR: Learn how to effortlessly instrument your JavaScript applications using the groundbreaking OpenTelemetry auto-instrumentation feature.

What is OpenTelemetry auto instrumentation? Navigating the complexity of micro-services

In the world of micro-services, debugging complex application architectures has become a formidable challenge. With multiple independent services working together, understanding how they interact and impact each other is no easy task.

To address this, the OpenTelemetry observability framework is a game-changer.

OpenTelemetry empowers developers to collect, process, and export telemetry data from distributed systems effectively. A critical aspect of OpenTelemetry is instrumentation, which involves integrating telemetry collection code into an application to transmit valuable data to an observability backend or collector. Traditionally, this required manual coding, but with the release of OpenTelemetry auto-instrumentation, the process has been revolutionized. Auto-instrumentation allows you to effortlessly gather telemetry data without modifying a single line of code.

For more on OpenTelemetry’s features, visit our Get Started with OpenTelemetry series.

Zero-code instrumentation to automate telemetry data

Zero-code instrumentation, a cutting-edge technique, enables automatic telemetry data collection without code modifications. This approach has numerous advantages over manual instrumentation, including faster time-to-value, reduced risk of human errors, and unparalleled ease of use. 

With zero-code instrumentation, developers can promptly initiate telemetry data collection without diving into the intricacies of the underlying telemetry framework or API. This saves precious time and effort while ensuring the consistency and accuracy of telemetry data across applications and teams, making it an indispensable asset for organizations.

Getting started with auto-instrumentation

Let's kick off our auto-instrumentation journey by creating a simple app.js application that sends a GET request:

const http = require('http');

const options = {
    hostname: 'example.com',
    port: 80,
    path: '/',
    method: 'GET'
};

const req = http.request(options);

req.end();

Before we proceed, we need to install the following packages to leverage the OpenTelemetry auto-instrumentation:

npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node

For effective visualization of the collected traces, we will be utilizing the open-source Jaeger as our backend.

To run Jaeger locally, execute the following Docker command:

docker run -d --name jaeger \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 6831:6831/udp \
  -p 6832:6832/udp \
  -p 5778:5778 \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 14250:14250 \
  -p 14268:14268 \
  -p 14269:14269 \
  -p 9411:9411 \
  jaegertracing/all-in-one:latest

To send the generated traces to Jaeger, we must configure the auto-instrumentation exporter by setting the following environment variable:

export OTEL_TRACES_EXPORTER="jaeger"

Note: To see the full range of configuration options, see the Auto-Instrumentation GitHub repository.

Next, we'll run our application with auto instrumentation enabled using the --require flag:

node --require '@opentelemetry/auto-instrumentations-node/register' app.js

If your Node.JS application is encapsulated within a complex run script, you can set the auto-instrumentation via an environment variable before executing Node.JS:

env NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"

The auto-instrumentation module offers extensive configurability through environment variables. You can fine-tune its behavior to suit your specific requirements, including resource detectors, exporter configuration, trace context propagation headers, and more.

Note: Auto instrumentation configuration via environment variables is not yet supported. If you require instrumentation configuration, you must initialize OpenTelemetry programmatically.

Considerations when using auto-instrumentation

While auto instrumentation simplifies the process of instrumenting your applications, there are some considerations to keep in mind. This approach may introduce some performance overhead, potentially impacting your application's behavior. Additionally, auto-instrumentation may not offer the same level of configurability as programmatically using the OpenTelemetry SDK. Therefore, it's crucial to review its compatibility with your needs before fully adopting it. For more details, consult the OpenTelemetry JS Documentation.

In summary: Auto instrumentation via OpenTelemtry

The groundbreaking auto-instrumentation feature of OpenTelemetry enables developers to effortlessly collect telemetry data without manual coding. By leveraging auto-instrumentation, JavaScript applications can seamlessly gather telemetry data without requiring any code changes. While this approach simplifies the instrumentation process, it's important to consider the potential performance overhead and compatibility with specific frameworks or libraries. As OpenTelemetry continues to evolve, developers can look forward to expanded auto-instrumentation capabilities, supporting a broader range of languages and frameworks in the future.

With this powerful auto-instrumentation technique, you can unlock unparalleled observability and gain invaluable insights into your distributed systems.

Remember, embracing auto-instrumentation is a leap towards a more streamlined and effective observability experience.

For more key insights into OpenTelemetry and the power it gives you, visit our post on making the most out of OpenTelemetry.

Sami Musallam is a Software Engineer and open-source advocate in Cisco’s Emerging Technology & Incubation organization, now known as Outshift. You can follow him on LinkedIn @samimusallam.