OpenTelemetry monitoring for Instana Node.js applications

Restrictions

Note:

Avoid using both the OpenTelemetry SDK and Instana Node.js Tracer in the same Node.js application. Using both might result in the following issues:

Missing calls in Instana
Duplicated telemetry data
Instrumentation failures

Node.js monitoring options with the OpenTelemetry SDK

When using the OpenTelemetry SDK, you can choose between the following tracing options:

Agent-based tracing: Traces and metrics are sent to the Instana agent endpoints by using the OpenTelemetry SDK
Serverless tracing:
- Serverless tracing with the OpenTelemetry SDK in the OTLP format: Traces and metrics are sent to the Instana OTLP endpoints by using the OpenTelemetry SDK (preferred)
- Serverless tracing with the OpenTelemetry SDK in the Instana format: Traces and metrics are send to Instana in the Instana format by using the OpenTelemetry SDK

Note:

You must send at least one metric to resolve infrastructure correlation between hosts, processes, and services.

Agent-based tracing with the OpenTelemetry SDK

You can enable agent-based tracing for Node.js applications by using the OpenTelemetry SDK.

Requirements

Installing the packages

To install the packages, run the following command:

npm i @opentelemetry/exporter-metrics-otlp-http @opentelemetry/exporter-trace-otlp-http @opentelemetry/propagator-instana @opentelemetry/resource-detector-instana @opentelemetry/resources @opentelemetry/sdk-metrics --save

Activating the packages

For a full working example, see Agent-based HTTP example.

...
          const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
          const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-http');
          const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
          const { instanaAgentDetector } = require('@opentelemetry/resource-detector-instana');
          const { processDetector, envDetector } = require('@opentelemetry/resources');
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');

          const instanaAgentHost = 'http://127.0.0.1:4318';

          const instanaReader = new PeriodicExportingMetricReader({
            exportIntervalMillis: 1000 * 10,
            exporter: new OTLPMetricExporter({
              url: `${otlpEndpoint}/v1/metrics`
            })
          });

          const sdk = new opentelemetry.NodeSDK({
            resourceDetectors: [envDetector, processDetector, instanaAgentDetector],
            traceExporter: new OTLPTraceExporter({
              url: `${otlpEndpoint}/v1/traces`
            }),
            propagator: new InstanaPropagator(),
            metricReader: instanaReader,
            instrumentations: ...
          });

Serverless tracing with the OpenTelemetry SDK in OTLP format

You can configure serverless tracing for Node.js applications by using the OpenTelemetry SDK in OTLP format to send traces and metrics to Instana.

Requirements

Set up the OpenTelemetry SDK for Node.js
Choose an OTLP acceptor serverless endpoint and set INSTANA_ENDPOINT_URL to the endpoint URL.
Get the agent key and set INSTANA_AGENT_KEY to the agent key.

Installing the packages

To install the following packages, run this command:

npm i @opentelemetry/exporter-metrics-otlp-grpc @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/propagator-instana @opentelemetry/sdk-metrics --save

Activating the packages

For a full working example, see Serverless OpenTelemetry OTLP format example.

...
          const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
          const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
          const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');

          const otlpEndpoint = process.env.INSTANA_ENDPOINT_URL;
          const metadata = new grpc.Metadata();
          metadata.set('x-instana-key', process.env.INSTANA_AGENT_KEY);

          const instanaReader = new PeriodicExportingMetricReader({
            exportIntervalMillis: 1000 * 10,
            exporter: new OTLPMetricExporter({
              url: otlpEndpoint,
              metadata
            })
          });

          const sdk = new opentelemetry.NodeSDK({
            traceExporter: new OTLPTraceExporter({
              url: otlpEndpoint,
              metadata
            }),
            propagator: new InstanaPropagator(),
            metricReader: instanaReader,
            instrumentations: [...]
          });

          ...

Serverless tracing with the OpenTelemetry SDK in Instana format

When the application that is monitored by OpenTelemetry runs, the Instana exporter converts the OpenTelemetry spans to Instana spans and sends them to the backend endpoint.

The OpenTelemetry traces appear in the Instana UI like regular Instana tracing spans.

Requirements

Install the OpenTelemetry SDK for Node.js
Choose an OTLP acceptor endpoint and set INSTANA_ENDPOINT_URL to the endpoint URL.
Get the agent key and set INSTANA_AGENT_KEY to the agent key.

Installing

Install the following packages by running this command:

npm i @instana/opentelemetry-exporter@ @opentelemetry/propagator-instana --save

Activating

For a full working example, see Serverless OpenTelemetry Instana format example.

...
          const { InstanaExporter } = require('@instana/opentelemetry-exporter');
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');

          /*
           * If you have not provided the agent key and the serverless endpoint URL via environment variables:
           * const instanaTraceExporter = new InstanaExporter({ agentKey: 'agent_key', endpointUrl: 'endpoint_url' });
           */
          const instanaTraceExporter = new InstanaExporter();

          const sdk = new opentelemetry.NodeSDK({
            ...
            traceExporter: instanaTraceExporter,
            propagator: new InstanaPropagator(),
            instrumentations: [...]
          });

OpenTelemetry plugins overview

Use Instana OpenTelemetry plugins for Node.js to manage trace propagation, sampling, and resource detection for improved correlation and context in your telemetry data.

OpenTelemetry propagator

The OpenTelemetry context propagator package @opentelemetry/propagator-instana translates the proprietary Instana trace correlation headers into an OpenTelemetry trace context and vice versa.

See OpenTelemetry propagators for general information on OpenTelemetry context propagators.

Installing the OpenTelemetry propagator

To install the OpenTelemetry propagator, run the following command:

npm install --save @opentelemetry/propagator-instana@

Activating the OpenTelemetry propagator

To activate the OpenTelemetry Propagator, run the following command:

...
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');
          // ...

          new opentelemetry.NodeSDK({
            ...
            propagator: new InstanaPropagator(),
            ...
          });

OpenTelemetry sampler

The OpenTelemetry sampler package @instana/opentelemetry-sampler overrides the default OpenTelemetry sampling behavior so that any request is sampled, unless the value of the sampled flag in the trace context is false.

Installing the OpenTelemetry sampler

To install the OpenTelemetry sampler, run the following command:

npm install --save @instana/opentelemetry-sampler@

Activating the OpenTelemetry sampler

The sampler needs to be used in conjunction with the package @opentelemetry/propagator-instana.

const { InstanaPropagator } = require('@opentelemetry/propagator-instana');
          const { InstanaAlwaysOnSampler } = require('@instana/opentelemetry-sampler');

          const sdk = new opentelemetry.NodeSDK({
            ...
            propagator: new InstanaPropagator(),
            sampler: new InstanaAlwaysOnSampler()
            ...
          });

          ...

OpenTelemetry resource detector

Note:

An Instana OpenTelemetry resource detector always requires an Instana agent to be deployed and running on the same host.

The OpenTelemetry resource detector package @opentelemetry/resource-detector-instana enriches OpenTelemetry tracing information with additional resource attributes.

Installing the OpenTelemetry resource detector

To install the OpenTelemetry resource detector, run the following command:

npm install --save @opentelemetry/resource-detector-instana

Activating the OpenTelemetry resource detector

import {
            Resource,
            processDetector,
            envDetector,
          } from "@opentelemetry/resources";
          import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
          import { NodeSDK } from "@opentelemetry/sdk-node";
          import { instanaAgentDetector } from "@opentelemetry/resource-detector-instana";

          const globalResource = new Resource({
             [SemanticResourceAttributes.SERVICE_NAME]: "TestService",
          });

          const sdk = new NodeSDK({
             resourceDetectors: [envDetector, processDetector, instanaAgentDetector]
             resource: globalResource,
          });

          ...

Additionally, you can provide the following environment variables:

INSTANA_RETRY_TIMEOUT_MS: The resource detector executes three retries to connect to the Instana agent. This value is the timeout between the retries. (default: 1000)
INSTANA_AGENT_TIMEOUT_MS: The client timeout when connecting to the Instana agent. (default: 3000)