Notes for OpenTelemetry Node.js developers

Auto-instrumentation

Auto instrumentation is a mechanism to collect telemetry data without modifying source code of the application. Auto instrumentation is a feature provided by OpenTelemetry that allows you to automatically instrument your application without writing custom code.

Use proper "resource detectors" to improve the infrastructure entity correlation used in Instana. The OpenTelemetry JavaScript auto-instrumentation must declare resource detectors to have enough resource attributes. You must have an external Instrumentation.js that has resource detectors to support enough resource attributes. For example, @opentelemetry/resource-detector-container version 0.3.4 or later is required for linking in a container environment such as a Kubernetes or Red Hat OpenShift cluster. The following example is a Instrumentation.js that is used in the OpenTelemetry official demo:

// Copyright The OpenTelemetry Authors
// SPDX-License-Identifier: Apache-2.0

const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { alibabaCloudEcsDetector } = require('@opentelemetry/resource-detector-alibaba-cloud');
const { awsEc2Detector, awsEksDetector } = require('@opentelemetry/resource-detector-aws');
const { containerDetector } = require('@opentelemetry/resource-detector-container');
const { gcpDetector } = require('@opentelemetry/resource-detector-gcp');
const { envDetector, hostDetector, osDetector, processDetector } = require('@opentelemetry/resources');

const sdk = new opentelemetry.NodeSDK({
    traceExporter: new OTLPTraceExporter(),
    instrumentations: [getNodeAutoInstrumentations()],
    metricReader: new PeriodicExportingMetricReader({
        exporter: new OTLPMetricExporter(),
    }),
    resourceDetectors: [
        containerDetector,
        envDetector,
        hostDetector,
        osDetector,
        processDetector,
        alibabaCloudEcsDetector,
        awsEksDetector,
        awsEc2Detector,
        gcpDetector,
    ],
});

sdk.start();

Manual instrumentation

Manual instrumentation involves writing custom code to instrument specific parts of your application. This requires manually configuring the source code of the application to configure OpenTelemetry SDK to receive, process and export the telemetry data. For more detailed instructions refer Manual Instrumentation.

Sending telemetry data to Instana Agent

The Instana agent can directly receive OpenTelemetry traces, metrics, and logs in OTLP format. Then, the Instana agent forwards the data to the Instana backend. For more details, see Send data to Instana Agent.

You must specify the Instana agent endpoint in the configuration of OTLPMetricExporter. Set the endpoint along with the Instana key in JSON format and pass it as an argument to OTLPMetricExporter as shown in the following example. For more details, see Usage with Node.js.

metricReader: new PeriodicExportingMetricReader({
  exporter: new OTLPMetricExporter({
    url: '<agent-otlp-endpoint>/v1/metrics', // url is optional and can be omitted - default is https://otlp-orange-saas.instana.io:4318/v1/metrics
    headers: { // an optional object containing custom headers to be sent with each request
      'x-instana-key': '<Instana key>'
    }
  }),
}),

Sending telemetry data to Instana Backend

Telemetry data can be sent in OTLP format directly from applications or systems to the Instana backend, which is also referred as Agent-less communication. For more details refer Send data to To Instana Backend

You must specify the Instana backend endpoint in the configuration of OTLPMetricExporter. Set the endpoint along with the Instana key and Instana host details in JSON format and pass as an argument to OTLPMetricExporter as shown in the following example. For more details, see Usage with Node.js.

metricReader: new PeriodicExportingMetricReader({
  exporter: new OTLPMetricExporter({
    url: '<backend-otlp-endpoint>/v1/metrics', // url is optional and can be omitted - default is https://otlp-orange-saas.instana.io:4318/v1/metrics
    headers: { // an optional object containing custom headers to be sent with each request
      'x-instana-key': '<Instana key>',
      'x-instana-host': '<hostname>'
    }
  }),
}),

To enable auto instrumentation, run the following command to point to the instrumentation.js file when you run the application:

node --require ./instrumentation.js app.js

For more information about Node.JS resource detector, see opentelemetry-js-contrib.

NodeJS instance is not listed under the OpenTelemetry applications list

1. Check Instana host agent logs to see whether any messages are related to this OpenTelemetry process.
2. Check whether NodeJS was properly instrumented either automatically or manually.
3. Check whether configuration such as endpoint and Instana key are set properly in the instrumented code.