Node.js

Instrument your server-side JavaScript and CLIs with OpenTelemetry.

Running on Kubernetes? The RocketLogs Kubernetes Operator automatically instruments your Node.js workloads. Using the operator is the recommended way to get visibility into Node.js Kubernetes workloads.

Overview

Instrumenting your Node.js application to generate traces, logs, and metrics is a powerful way to gain deep insights into its behavior and performance. By adding instrumentation, you enable your application to emit valuable data that can be used for monitoring, troubleshooting, and optimization.

RocketLogs supports automatic instrumentation of Node.js applications through OpenTelemetry's open-source and vendor-agnostic packages.

Use Cases

Understand outgoing and incoming HTTP requests through traces and metrics. Allowing drill-downs to the database level.
You can see which database statements were executed and how long they took, which gives you valuable data to optimize your applications.
Reveal (uncaught) errors and the context in which they happened.

Install

The OpenTelemetry Node.js SDK comes with a ready-made auto-instrumentation package that gets you up and running in no time:

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

However, installing the @opentelemetry/auto-instrumentations-node package and its dependencies (including the OpenTelemetry JS SDK) is not sufficient by itself. You also need to activate the SDK, as described in the next section.

Configure

To send data to RocketLogs, you need to configure the following settings:

1. Activate the OpenTelemetry JS SDK

Use the NODE_OPTIONS environment variable to load OpenTelemetry dependencies during the Node.js runtime startup:

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

If you are using ESM, you have to use the following NODE_OPTIONS instead:

export NODE_OPTIONS="--experimental-loader=@opentelemetry/instrumentation/hook.mjs --import @opentelemetry/auto-instrumentations-node/register"

2. Specify the application service name

export OTEL_SERVICE_NAME="my-first-observable-service"

Replace my-first-observable-service with a name that identifies your application.

3. Set up the data export endpoint and authorization token

export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingress.us-east-2.rocketgraph.app"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_ROCKETLOGS_API_TOKEN"

Replace YOUR_ROCKETLOGS_API_TOKEN with your API token from Settings.

4. Configure the metrics exporter

The log and trace exporter defaults to otlp:

export OTEL_METRICS_EXPORTER=otlp

Supported libraries and frameworks

To understand which libraries are automatically instrumented by this package, please refer to the OpenTelemetry documentation

Troubleshooting

How do I ensure that the OpenTelemetry SDK is correctly initialized and active?

To debug issues, enable the OpenTelemetry SDK's logging at the debug level. This provides detailed logs about module instrumentation and initialization issues. However, this setting should only be used during troubleshooting and not in production environments.

Set the following environment variable:

export OTEL_LOG_LEVEL=debug