Skip to main content

Express OpenTelemetry Instrumentation

This document contains instructions on how to set up OpenTelemetry instrumentation in your Express applications. OpenTelemetry, also known as OTel for short, is an open source observability framework that can help you generate and collect telemetry data - traces, metrics, and logs from your Express application.

Requirements​

Supported Versions

^4.0.0

Send traces to SigNoz Cloud​

Based on your application environment, you can choose the setup below to send traces to SigNoz Cloud.

From VMs, there are two ways to send data to SigNoz Cloud.

Send traces directly to SigNoz Cloud​

Step 1. Install OpenTelemetry packages

npm install --save @opentelemetry/api@^1.6.0                                                                       
npm install --save @opentelemetry/sdk-node@^0.45.0
npm install --save @opentelemetry/auto-instrumentations-node@^0.39.4
npm install --save @opentelemetry/exporter-trace-otlp-http@^0.45.0

Step 2. Create tracing.js file
You need to configure the endpoint for SigNoz cloud in this file. You can find your ingestion key from SigNoz cloud account details sent on your email.

// tracing.js
'use strict'
const process = require('process');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

// do not set headers in exporterOptions, the OTel spec recommends setting headers through ENV variables
// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#specifying-headers-via-environment-variables

const exporterOptions = {
url: 'https://ingest.{region}.signoz.cloud:443/v1/traces'
}

const traceExporter = new OTLPTraceExporter(exporterOptions);
const sdk = new opentelemetry.NodeSDK({
traceExporter,
instrumentations: [getNodeAutoInstrumentations()],
resource: new Resource({
[SemanticResourceAttributes.SERVICE_NAME]: 'node_app'
})
});

// initialize the SDK and register with the OpenTelemetry API
// this enables the API to record telemetry
sdk.start()

// gracefully shut down the SDK on process exit
process.on('SIGTERM', () => {
sdk.shutdown()
.then(() => console.log('Tracing terminated'))
.catch((error) => console.log('Error terminating tracing', error))
.finally(() => process.exit(0));
});

Depending on the choice of your region for SigNoz cloud, the ingest endpoint will vary according to this table.

RegionEndpoint
USingest.us.signoz.cloud:443/v1/traces
INingest.in.signoz.cloud:443/v1/traces
EUingest.eu.signoz.cloud:443/v1/traces

Step 3. Run the application
Make sure you set the OTEL_EXPORTER_OTLP_HEADERS env as follows

OTEL_EXPORTER_OTLP_HEADERS="signoz-access-token=<SIGNOZ_INGESTION_KEY>" node -r ./tracing.js app.js

SIGNOZ_INGESTION_KEY is the API token provided by SigNoz. You can find your ingestion key from SigNoz cloud account details sent on your email.

Step 4. You can validate if your application is sending traces to SigNoz cloud here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.


Send traces via OTel Collector binary​

OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes. It is recommended to install Otel Collector binary to collect and send traces to SigNoz cloud. You can correlate signals and have rich contextual data through this way.

note

You can find instructions to install OTel Collector binary here in your VM. Once you are done setting up your OTel Collector binary, you can follow the below steps for instrumenting your Javascript application.

Step 1. Install OpenTelemetry packages

npm install --save @opentelemetry/api@^1.6.0
npm install --save @opentelemetry/sdk-node@^0.45.0
npm install --save @opentelemetry/auto-instrumentations-node@^0.39.4
npm install --save @opentelemetry/exporter-trace-otlp-http@^0.45.0

Step 2. Create tracing.js file

// tracing.js
'use strict'
const process = require('process');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

const exporterOptions = {
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
}

const traceExporter = new OTLPTraceExporter(exporterOptions);
const sdk = new opentelemetry.NodeSDK({
traceExporter,
instrumentations: [getNodeAutoInstrumentations()],
resource: new Resource({
[SemanticResourceAttributes.SERVICE_NAME]: 'node_app'
})
});

// initialize the SDK and register with the OpenTelemetry API
// this enables the API to record telemetry
sdk.start()

// gracefully shut down the SDK on process exit
process.on('SIGTERM', () => {
sdk.shutdown()
.then(() => console.log('Tracing terminated'))
.catch((error) => console.log('Error terminating tracing', error))
.finally(() => process.exit(0));
});

Step 3. Run the application

node -r ./tracing.js app.js

Step 4. You can validate if your application is sending traces to SigNoz cloud here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

Send Traces to Self-Hosted SigNoz​

There are three major steps to using OpenTelemetry:

  • Instrumenting your Express application with OpenTelemetry
  • Configuring exporter to send data to SigNoz
  • Validating that configuration to ensure that data is being sent as expected.
All in one auto instrumentation library - identifies and instruments packages used by your NestJS application
All in one auto instrumentation library - identifies and instruments packages used by your Express application

You have two choices for instrumenting your Express application with OpenTelemetry.

info

If you are on K8s, you should checkout opentelemetry operators which enable auto instrumenting Javascript applications very easily.

  • Use a specific auto-instrumentation library
    You can use individual auto-instrumentation libraries too for a specific component of your application. For example, you can use @opentelemetry/instrumentation-express for instrumenting the Express web framework.

Let's see how to instrument your Express application with OpenTelemetry.

Using the all-in-one auto-instrumentation library​

The recommended way to instrument your Express application is to use the all-in-one auto-instrumentation library - @opentelemetry/auto-instrumentations-node. It provides a simple way to initialize multiple Nodejs instrumentations.

Internally, it calls the specific auto-instrumentation library for components used in the application. You can see the complete list here.

Steps to auto-instrument Express application​

  1. Install the dependencies
    We start by installing the relevant dependencies.

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

    The dependencies included are briefly explained below:

    @opentelemetry/sdk-node - This package provides the full OpenTelemetry SDK for Node.js including tracing and metrics.

    @opentelemetry/auto-instrumentations-node - This module provides a simple way to initialize multiple Node instrumentations.

    @opentelemetry/exporter-trace-otlp-http - This module provides the exporter to be used with OTLP (http/json) compatible receivers.

    note

    If you run into any error, you might want to use these pinned versions of OpenTelemetry libraries used in this GitHub repo.

  2. Create a tracing.js file
    The tracing.js file will contain the tracing setup code. Notice, that we have set some environment variables in the code(highlighted). You can update these variables based on your environment.

      // tracing.js
    'use strict'
    const process = require('process');
    const opentelemetry = require('@opentelemetry/sdk-node');
    const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
    const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
    const { Resource } = require('@opentelemetry/resources');
    const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

    const exporterOptions = {
    url: 'http://localhost:4318/v1/traces'
    }

    const traceExporter = new OTLPTraceExporter(exporterOptions);
    const sdk = new opentelemetry.NodeSDK({
    traceExporter,
    instrumentations: [getNodeAutoInstrumentations()],
    resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'node_app'
    })
    });

    // initialize the SDK and register with the OpenTelemetry API
    // this enables the API to record telemetry
    sdk.start()

    // gracefully shut down the SDK on process exit
    process.on('SIGTERM', () => {
    sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
    });

    OpenTelemetry Node SDK currently does not detect the OTEL_RESOURCE_ATTRIBUTES from .env files as of today. That’s why we need to include the variables in the tracing.js file itself.

    About environment variables:

    service_name : node_app (you can give whatever name that suits you)

    http://localhost:4318/v1/traces is the default url for sending your tracing data. We are assuming you have installed SigNoz on your localhost. Based on your environment, you can update it accordingly. It should be in the following format:

    http://<IP of SigNoz backend>:4318/v1/traces

    Here’s a handy grid to figure out which address to use to send data to SigNoz.

    note

    Remember to allow incoming requests to port 4318 of machine where SigNoz backend is hosted.

  1. Run the application
    The tracing configuration should be run before your application code. We will use the -r, —require module flag for that.

      node -r ./tracing.js app.js
    note

    If you're running your nodejs application in PM2 cluster mode, it doesn't support node args: Unitech/pm2#3227. As above sample app instrumentation requires to load tracing.js before app load by passing node arg, so nodejs instrumentation doesn't work in PM2 cluster mode. So you need to import tracing.js in your main application. The import ./tracing.js should be the first line of your application code and initialize it before any other function. Here's the sample github repo which shows the implementation.

    In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

Validating instrumentation by checking for traces​

With your application running, you can verify that you’ve instrumented your application with OpenTelemetry correctly by confirming that tracing data is being reported to SigNoz.

To do this, you need to ensure that your application generates some data. Applications will not produce traces unless they are being interacted with, and OpenTelemetry will often buffer data before sending. So you need to interact with your application and wait for some time to see your tracing data in SigNoz.

Validate your traces in SigNoz:

  1. Trigger an action in your app that generates a web request. Hit the endpoint a number of times to generate some data. Then, wait for some time.
  2. In SigNoz, open the Services tab. Hit the Refresh button on the top right corner, and your application should appear in the list of Applications.
  3. Go to the Traces tab, and apply relevant filters to see your application’s traces.

You might see other dummy applications if you’re using SigNoz for the first time. You can remove it by following the docs here.

Nestjs Application in the list of services being monitored in SigNoz
Express Application in the list of services being monitored in SigNoz

If you don't see your application reported in the list of services, try our troubleshooting guide.

Using a specific auto-instrumentation library​

If you want to instrument only your Express framework, then you need to use the following package:

npm install --save @opentelemetry/instrumentation-express

Note that in the above case, you will have to install packages for all the components that you want to instrument with OpenTelemetry individually. You can find detailed instructions here.

Instrumentation Modules for Databases​

The @opentelemetry/auto-instrumentations-node can inititialize instrumentation for popular databases. Hence it’s recommended to get started with it.

But if you are using specific auto-instrumentation packages, here’s a list of packages for popular databases.

MongoDB instrumentation​

Note if you’re using @opentelemetry/auto-instrumentations-node, you don’t need to install specific modules for your database.

Supported Versions

• >=3.3 <5

Module that provides automatic instrumentation for MongoDB:

npm install --save @opentelemetry/instrumentation-mongodb

Note: Refer here for sample NodeJs express application with MongoDB.

Redis Instrumentation​

Note if you’re using @opentelemetry/auto-instrumentations-node, you don’t need to install specific modules for your database.

Supported Versions

This package supports redis@^2.6.0 and redis@^3.0.0 For version redis@^4.0.0, please use @opentelemetry/instrumentation-redis-4

npm install --save @opentelemetry/instrumentation-redis

MySQL Instrumentation​

Note if you’re using @opentelemetry/auto-instrumentations-node, you don’t need to install specific modules for your database.

Supported Versions

• 2.x

Module that provides automatic instrumentation for MySQL:

npm install --save @opentelemetry/instrumentation-mysql

Memcached Instrumentation​

Note if you’re using @opentelemetry/auto-instrumentations-node, you don’t need to install specific modules for your database.

Supported Versions

  • >=2.2

Module that provides automatic instrumentation for Memcached:

npm install --save @opentelemetry/instrumentation-memcached

Troubleshooting your installation​

Set an environment variable to run the OpenTelemetry launcher in debug mode, where it logs details about the configuration and emitted spans:

export OTEL_LOG_LEVEL=debug

The output may be very verbose with some benign errors. Early in the console output, look for logs about the configuration. Next, look for lines like the ones below, which are emitted when spans are emitted to SigNoz.

{
"traceId": "985b66d592a1299f7d12ebca56ca1fe3",
"parentId": "8d62a70aa335a227",
"name": "bar",
"id": "17ada85c3d55376a",
"kind": 0,
"timestamp": 1685674607399000,
"duration": 299,
"attributes": {},
"status": { "code": 0 },
"events": []
}
{
"traceId": "985b66d592a1299f7d12ebca56ca1fe3",
"name": "foo",
"id": "8d62a70aa335a227",
"kind": 0,
"timestamp": 1585130342183948,
"duration": 315,
"attributes": {
"name": "value"
},
"status": { "code": 0 },
"events": [
{
"name": "event in foo",
"time": [1585130342, 184213041]
}
]
}

Running short applications (Lambda/Serverless/etc) If your application exits quickly after startup, you may need to explicitly shutdown the tracer to ensure that all spans are flushed:

opentelemetry.trace.getTracer('your_tracer_name').getActiveSpanProcessor().shutdown()

Sample Express App​

Further Reading​

Frequently Asked Questions​

  1. How to find what to use in IP of SigNoz if I have installed SigNoz in Kubernetes cluster?

    Based on where you have installed your application and where you have installed SigNoz, you need to find the right value for this. Please use this grid to find the value you should use for IP of SigNoz

  2. I am sending data from my application to SigNoz, but I don't see any events or graphs in the SigNoz dashboard. What should I do?

    This could be because of one of the following reasons:

    1. Your application is generating telemetry data, but not able to connect with SigNoz installation

      Please use this troubleshooting guide to find if your application is able to access SigNoz installation and send data to it.

    2. Your application is not actually generating telemetry data

      Please check if the application is generating telemetry data first. You can use Console Exporter to just print your telemetry data in console first. Join our Slack Community if you need help on how to export your telemetry data in console

    3. Your SigNoz installation is not running or behind a firewall

      Please double check if the pods in SigNoz installation are running fine. docker ps or kubectl get pods -n platform are your friends for this.