Technologies Supported by the EDOT Node.js SDK

EDOT Collector / Elastic Stack versions

The Elastic Distribution of OpenTelemetry Node.js (EDOT Node.js) sends data via the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support it is strongly recommended that you use either EDOT Collector versions 9.x or Elastic Cloud Serverless for OTLP ingest.

Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ is supported.

See EDOT SDKs compatibility for support details.

Node.js versions

EDOT Node.js supports Node.js 18.19.0, 20.6.0, or later. This follows from the OpenTelemetry JS supported runtimes.

TypeScript versions

To use this package, @elastic/opentelemetry-node, in TypeScript code requires:

  • TypeScript 5.0.4 or later, and
  • using "module": "node16" (or “nodenext”) in “tsconfig.json” to get support for handling the “exports” entry in package.json. This is so the @elastic/opentelemetry-node/sdk entry-point can be used. (See https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-7.html#ecmascript-module-support-in-nodejs)

Instrumentations

The following instrumentations are included in EDOT Node.js. All are enabled by default, except those noted “disabled by default”. 🔹 marks instrumentations that differ between EDOT Node.js and upstream OTel JS, or that only exist in EDOT Node.js.

Name Packages instrumented Notes
@elastic/opentelemetry-instrumentation-openai 🔹 openai version range >=4.19.0 <5 README
@opentelemetry/instrumentation-amqplib amqplib version range >=0.5.5 <1 README
@opentelemetry/instrumentation-aws-sdk aws-sdk v2 and @aws-sdk/client-* v3 README
@opentelemetry/instrumentation-bunyan bunyan version range ^1.0.0 README
@opentelemetry/instrumentation-cassandra-driver cassandra-driver version range >=4.4.0 <5 README
@opentelemetry/instrumentation-express express version range ^4.0.0 README
@opentelemetry/instrumentation-fastify fastify version range >=3 <5 README, disabled by default
@opentelemetry/instrumentation-fs fs module for suppported Node.js versions README, disabled by default
@opentelemetry/instrumentation-generic-pool generic-pool version range 2 - 2.3, ^2.4, >=3 README
@opentelemetry/instrumentation-graphql graphql version range >=14.0.0 <17 README
@opentelemetry/instrumentation-grpc @grpc/grpc-js version range ^1.0.0 README
@opentelemetry/instrumentation-hapi @hapi/hapi >=17.0.0 <21 README
@opentelemetry/instrumentation-http http module for suppported Node.js versions README
@opentelemetry/instrumentation-ioredis ioredis version range >=2 <6 README
@opentelemetry/instrumentation-kafkajs kafkajs version range >=0.1.0 <3 README
@opentelemetry/instrumentation-knex knex version range >=0.10.0 README
@opentelemetry/instrumentation-koa koa version range ^2.0.0 README
@opentelemetry/instrumentation-lru-memoizer lru-memoizer version range >=1.3 <3 README
@opentelemetry/instrumentation-memcached memcached version range >=2.2 README
@opentelemetry/instrumentation-mongodb mongodb version range >=3.3 <7 README
@opentelemetry/instrumentation-mongoose mongoose version range >=5.9.7 <9 README
@opentelemetry/instrumentation-mysql mysql version range >=2.0.0 <3 README
@opentelemetry/instrumentation-mysql2 mysql2 version range >=1.4.2 <4 README
@opentelemetry/instrumentation-nestjs-core @nestjs/core version range >=4.0.0 README
@opentelemetry/instrumentation-net net module for suppported Node.js versions README
@opentelemetry/instrumentation-pino pino version range >=5.14.0 <10 README
@opentelemetry/instrumentation-pg pg version range >=8 <9 README
@opentelemetry/instrumentation-redis-4 redis version range ^4.0.0 README
@opentelemetry/instrumentation-restify restify version range >=4.0.0 <12 README
@opentelemetry/instrumentation-router router version range 1 README
@opentelemetry/instrumentation-socket.io socket.io version range 2, >=3 <5 README
@opentelemetry/instrumentation-tedious tedious version range >=1.11.0 <=15 README
@opentelemetry/instrumentation-undici undici version range >=5.12.0 README
@opentelemetry/instrumentation-winston winston version range >1 <4 README

LLM instrumentations

We can instrument the following LLM (Large Language Model) libraries with instrumentations implementing the OpenTelemetry GenAI Semantic Conventions:

SDK Instrumentation Traces Metrics Logs Notes
OpenAI @elastic/opentelemetry-instrumentation-openai ✅ ✅ ✅ (1)

(1) Support for chat and embeddings API endpoints.

Disabled instrumentations

The following instrumentations are included in EDOT Node.js, but disabled by default:

To enable these instrumentations, use the OTEL_NODE_ENABLED_INSTRUMENTATIONS environment variable. Make sure you list all the instrumentations you need for your service since only the ones in that list will be enabled. For example:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://my-deployment-abc123.ingest.us-west-2.aws.elastic.cloud"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey Zm9vO...mJhcg=="
export OTEL_SERVICE_NAME=my-app
export OTEL_NODE_ENABLED_INSTRUMENTATIONS="fs,http,fastify" # only the ones in the list would be enabled
node --import @elastic/opentelemetry-node my-service.js

EDOT Node.js uses the upstream @opentelemetry/auto-instrumentations-node package’s set of instrumentations as a guide for instrumentations to include, exclude, or disable by default. This is to maximize compatibility between usage of EDOT Node.js and the vanilla OpenTelemetry JS SDK.

Native Instrumentations

“Native” instrumentation refers to OpenTelemetry instrumentation that is built into a library. When a library includes native OTel instrumentation, it will provide telemetry data to providers registered by a running OTel SDK. Native instrumentations of note are listed in the table below. To benefit from these instrumentations you only need to (a) use the library and (b) start the EDOT Node.js SDK:

node --import @elastic/opentelemetry-node my-app.js
Packages instrumented Reference
@elastic/elasticsearch version range >=8.15.0 Elasticsearch JavaScript Client docs

ECMAScript Modules (ESM)

This Distro includes limited and experimental support for instrumenting ECMAScript module (ESM) imports, i.e. modules that are loaded via import ... statements and import('...') (dynamic import). To enable ESM instrumentation, use node --import @elastic/opentelemetry-node ... to start the SDK. (Using node --require @elastic/opentelemetry-node ... will not enable ESM instrumentation. It is intended to signal that only CommonJS module usage should be instrumented.)

Limitations:

  • ESM instrumentation is only support for Node.js versions ^18.19.0 || >=20.6.0. These are the versions that include module.register() support. Using the older node --experimental-loader=... option is not supported.
  • Currently only a subset of instrumentations support ESM: express, ioredis, koa, pg, pino. See this OpenTelemetry JS tracking issue for progress.