OpenTelemetry NodeJS Instrumentation

Requirements

Node.js version 12 or newer
An app to add OpenTelemetry to

To install OpenTelemetry, we recommend LightStep's handy OTel-Launcher, which simplifies the process.

Sample Express Application#

For this tutorial, we’re going to make a very, very simple application: an express service that responds to http://localhost:9000/hello with "Hello World". It’s as basic as it is original!

First, make a directory to contain your project, and install express:

npm i express

Once we have that, let’s get to coding. Make a file called server.js and serve up some hello world:

const express = require('express');

const app = express();

app.get('/hello', (req, res) => {
 res.status(200).send('Hello World');
});

app.listen(9000);

Boot up server by

node server.js

and check that it works by visiting http://localhost:9000/hello

Setting up OpenTelemetry#

Installing the OpenTelemetry Launcher package will also install OpenTelemetry, plus all currently available instrumentation.

npm install lightstep-opentelemetry-launcher-node

Create a file called server_init.js. This will serve as your new entry point. You can copy and paste the below code.

const {
    lightstep,
    opentelemetry,
   } = require('lightstep-opentelemetry-launcher-node');

   const sdk = lightstep.configureOpenTelemetry();

   sdk.start().then(() => {
    require('./server');
   });

   function shutdown() {
    sdk.shutdown().then(
      () => console.log("SDK shut down successfully"),
      (err) => console.log("Error shutting down SDK", err),
    ).finally(() => process.exit(0))
   };

   process.on('exit', shutdown);
   process.on('SIGINT', shutdown);
   process.on('SIGTERM', shutdown);

Run Command#

OTEL_METRICS_EXPORTER=none OTEL_EXPORTER_OTLP_SPAN_ENDPOINT="http://<IP of SigNoz Backend>:55681/v1/trace" LS_SERVICE_NAME=<service name> node server_init.js

note

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

Instrumentation of a sample NodeJs application#

We have included a sample Express application with README.md at https://github.com/SigNoz/sample-nodejs-app.

Feel free to use this repo to test out OpenTelemetry instrumentation and how to send telemetry data to SigNoz.

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()