Instrument Node.js applications with OpenTelemetry

This guide shows how to instrument your Node.js application with OpenTelemetry and export the traces to Dynatrace. To learn more about how Dynatrace works with OpenTelemetry, see Send data to Dynatrace with OpenTelemetry.

Node.js applications are automatically instrumented by OneAgent, without any configuration or code changes required. The option described below is recommended when OneAgent cannot be deployed on your platform.

Instrument without OneAgent code module

For prerequisites and limitations, see Send OpenTelemetry trace data to Dynatrace. If your application is already instrumented, go directly to Send the traces to Dynatrace.

Follow the steps below to

  1. Instrument your service with OpenTelemetry
  2. Send the traces to Dynatrace
  3. Verify that the traces are ingested into Dynatrace

Optional:

1. Instrument your service with OpenTelemetry for Node.js

To instrument your service with OpenTelemetry for Node.js, install the OpenTelemetry SDK and instrumentation modules, add and configure the tracing code, and run the application with tracing.

1.1 Install the OpenTelemetry SDK

The following dependencies are required to add the OpenTelemetry SDK to your application and create spans.

npm install @opentelemetry/sdk-node @opentelemetry/api

1.2 Install the instrumentation modules

Many common modules such as the HTTP standard library module, express, and others can be automatically instrumented using auto-instrumentation modules. To find auto-instrumenatation modules, see the OpenTelemetry registry. All of those instrumentations are maintained by the open source community; be sure to check the license before using them in your code.

You can also install all instrumentations maintained by the open source community by using the @opentelemetry/auto-instrumentations-node module.

npm install @opentelemetry/auto-instrumentations-node

1.3 Add and configure the tracing code

Tracing setup and configuration should be run before your application code. One tool commonly used for this task is the -r, --require module flag.

Create a file with a name like tracing.js, which will contain your tracing setup code. In this example, we use nodejs-quickstart as the name of the service that is being instrumented.

/* tracing.js */

// Require dependencies
const opentelemetry = require("@opentelemetry/sdk-node");
const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node");
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

const sdk = new opentelemetry.NodeSDK({
  resource: new Resource({
        [SemanticResourceAttributes.SERVICE_NAME]: 'nodejs-quickstart',
        [SemanticResourceAttributes.SERVICE_VERSION]: "1.0.1",

  }),
  traceExporter: new opentelemetry.tracing.ConsoleSpanExporter(),
  instrumentations: [getNodeAutoInstrumentations()]
});

sdk.start()

1.4 Run the application with tracing

Now you can run the application as you normally would, but you can use the --require flag to load the tracing code before the application code.

Linux:

$ node --require './tracing.js' app.js

Windows:

$ node --require .\tracing.js app.js

Traces are created, and you should see them on the app's output.

2. Send the traces to Dynatrace

Now that traces are being created, we want to see them in Dynatrace.

2.1 Install the OpenTelemetry exporter

To send your traces to Dynatrace, you need to use the OpenTelemetry exporter that exports the traces in the OTLP/HTTP binary Protobuf format. Install the following dependency:

npm install @opentelemetry/exporter-collector-proto

2.2 Create an authentication token

The trace ingest API requires an API token with the Ingest OpenTelemetry traces (openTelemetryTrace.ingest) scope.

2.3 Configure the OTLP/HTTP OpenTelemetry exporter in your code

Replace the content of your tracing.js file by the code below.

Make sure to replace the <URL> and the <TOKEN> placeholders as follow:

  1. Use your Environment ID to set the URL:
    • Dynatrace SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/otlp/v1/traces
    • Dynatrace Managed https://{your-domain}/e/{your-environment-id}/api/v2/otlp/v1/traces
  2. Set the Authorization HTTP header as Api-Token <TOKEN>, where <TOKEN> is the API token you created earlier.
/* tracing.js */

// Require dependencies
const opentelemetry = require("@opentelemetry/sdk-node");
const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node");
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');
const { CollectorTraceExporter } = require("@opentelemetry/exporter-collector-proto");

/*
   OTLPoptions contains the configurations required to configure the OTLP exporter.
   This is the only configuration required to send the spans to Dynatrace (url and authorization header).
   Everything else is specific to OpenTelemetry.
*/
const OTLPoptions = {
    url: "<URL>",
    headers: {
        Authorization: "Api-Token <TOKEN>" // the API token should be put in a configuration file
    },
};

const collectorExporter = new CollectorTraceExporter(OTLPoptions);

const sdk = new opentelemetry.NodeSDK({
  resource: new Resource({
        [SemanticResourceAttributes.SERVICE_NAME]: 'nodejs-quickstart',
        [SemanticResourceAttributes.SERVICE_VERSION]: "1.0.1",
      }),
  traceExporter: collectorExporter,
  instrumentations: [getNodeAutoInstrumentations()]
});

sdk.start()

3. Verify that the traces are ingested into Dynatrace

To view your OpenTelemetry traces, in the Dynatrace menu, go to Distributed traces and looks for the traces.

The dsfm:server.spans.persisted metrics via the Data explorer or Metrics v2 API show you how many spans are being ingested by Dynatrace.

(Optional) Configure data capture to meet privacy requirements

While Dynatrace automatically captures all OpenTelemetry resource and span attributes, only attribute values specified in the allowlist are stored and shown in the web UI. This prevents accidental storage of personal data, so you can meet your privacy requirements and control the amount of monitoring data that's being stored.

To view and edit the allowlists:

  • Span attributes In the Dynatrace menu, go to Settings > Server-side service monitoring > Span attributes.
  • Resource attributes In the Dynatrace menu, go to Settings > Server-side service monitoring > Resource attributes.