Instrument Node.js applications with OpenTelemetry Metrics

This guide shows how to instrument your Node.js application with OpenTelemetry and export the metrics to Dynatrace.

To learn more about how Dynatrace works with OpenTelemetry, see Send data to Dynatrace with OpenTelemetry.

Prerequisites

Dynatrace version 1.222+

Overview

To monitor your Node.js application with OpenTelemetry

Instrument your application

Send the data to Dynatrace

Restart your application and verify the data in Dynatrace

Instrument your application

To instrument manually, install the packages below and add the code snippet below to any Node.js method you want to monitor.

Set names for the meter and the instrument.
Add a description and attributes to the instrument as you see fit.

bash
npm install @opentelemetry/api
npm install @opentelemetry/resources
npm install @opentelemetry/sdk-metrics

js
const fs = require("fs");
const { MeterProvider } = require('@opentelemetry/sdk-metrics');
const { Resource } = require("@opentelemetry/resources");

let dtmetadata = new Resource({})
for (let name of ['dt_metadata_e617c525669e072eebe3d0f08212e8f2.json', '/var/lib/dynatrace/enrichment/dt_metadata.json']) {
    try {
        dtmetadata = dtmetadata.merge(
            new Resource(JSON.parse(fs.readFileSync(name.startsWith("/var") ?
                name : fs.readFileSync(name).toString('utf-8').trim()).toString('utf-8'))));
        break
    } catch { }
}

const provider = new MeterProvider({
    resource: new Resource({
        'service.name': 'opentelemetry-metrics-sample' // TODO Replace with the name of your application
    }).merge(dtmetadata)
});

//TODO Configure the provider MetricReader as mentioned in the next step

const meter = provider.getMeter('my-meter'); //TODO Replace with the name of your meter

const requestCounter = meter.createCounter('my-counter', { //TODO Replace with the name of your instrument
  description: 'Example of a Counter', //TODO Replace with the description of your isntrument
});

const upDownCounter = meter.createUpDownCounter('my-updowncounter', { //TODO Replace with the name of your instrument
  description: 'Example of an UpDownCounter', //TODO Replace with the description of your instrument
});

Add the code below to any call you want to monitor. You can also add attributes to each measurement. The data is generated randomly and needs to be replaced by your data. In this case, we used a Counter and an UpDownCounter instrument. To find the instrument that fits your needs, see the official OpenTelemetry documentation.

js
const attributes = { "my-key-1": "my-value-1", "my-key-2": "my-value-2" }; //TODO Replace with your attributes

requestCounter.add(Math.round(Math.random() * 1000), attributes);
upDownCounter.add(Math.random() > 0.5 ? 1 : -1, attributes);

Send data to Dynatrace

To send data to Dynatrace, you need to add the dependencies and then add and configure the code snippet below in your Node.js application code.

OTLP Exporter (Recommended)Dynatrace Exporter

bash
npm install @opentelemetry/exporter-metrics-otlp-proto

js
const { MeterProvider, PeriodicExportingMetricReader, AggregationTemporality} = require('@opentelemetry/sdk-metrics');
const { OTLPMetricExporter } =  require('@opentelemetry/exporter-metrics-otlp-proto');

const metricExporter = new OTLPMetricExporter({
    url: '<URL>', //TODO Replace <URL> to your SaaS/Managed-URL as mentioned in the next step
    headers: {
        Authorization: "Api-Token <TOKEN>" //TODO Replace <TOKEN> with your API Token as mentioned in the next step
    },
    temporalityPreference: AggregationTemporality.DELTA
});

provider.addMetricReader(new PeriodicExportingMetricReader({
    exporter: metricExporter,
    exportIntervalMillis: 6000,
}));

To make sure your data arrives where it should be, you need to define the correct endpoint and token.

To set the endpoint
1. Use your Environment ID to set the endpoint to which your app will send traces as follows:
  - Dynatrace SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/otlp/v1/metrics
  - Dynatrace Managed https://{your-domain}/e/{your-environment-id}/api/v2/otlp/v1/metrics
2. Replace <URL> in the code snippet above with your endpoint.
To create an authentication token
1. In the Dynatrace menu, go to Access tokens and select Generate new token.
2. Provide a Token name.
3. In the Search scopes box, search for Ingest metrics (under API v2 scopes), and select the checkbox.
4. Select Generate token.
5. Select Copy to copy the token to your clipboard.
6. Save the token in a safe place; you can't display it again.
7. Replace <TOKEN> in the code snippet above with your token.

bash
npm install @dynatrace/opentelemetry-exporter-metrics

js
const { configureDynatraceMetricExport } = require('@dynatrace/opentelemetry-exporter-metrics');

const reader = configureDynatraceMetricExport(
    // ExporterConfig
    {
        prefix: 'sample', // optional

        // If no OneAgent is available locally, export directly to the Dynatrace server:
        // url: '<URL>', //TODO Replace <URL> to your SaaS/Managed-URL as mentioned in the next step
        // apiToken: '<TOKEN>' //TODO Replace <TOKEN> with your API Token as mentioned in the next step
    },
    // ReaderConfig
    {
        exportIntervalMillis: 6000
    }
);
provider.addMetricReader(reader);

If no OneAgent is available locally, you need to define the correct endpoint and token to make sure your data arrives where it should be.

To set the endpoint
1. Use your Environment ID to set the endpoint to which your app will send traces as follows:
  - Dynatrace SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest
  - Dynatrace Managed https://{your-domain}/e/{your-environment-id}/api/v2/metrics/ingest
2. Replace <URL> in the code snippet above with your endpoint.
To create an authentication token
1. In the Dynatrace menu, go to Access tokens and select Generate new token.
2. Provide a Token name.
3. In the Search scopes box, search for Ingest metrics (under API v2 scopes), and select the checkbox.
4. Select Generate token.
5. Select Copy to copy the token to your clipboard.
6. Save the token in a safe place; you can't display it again.
7. Replace <TOKEN> in the code snippet above with your token.

Verify that the metrics are ingested into Dynatrace

A few minutes after restarting your app, look for your metrics:

In the Dynatrace menu, go to Metrics and filter for your metrics (by the names you have given them).
To get more detailed information, or to filter for different criteria, expand Details for a metric and select Create chart.

If your application does not receive any traffic, there will be no metrics.