Configure the EDOT Node.js SDK

Elastic Stack Serverless Observability

The Elastic Distribution of OpenTelemetry Node.js (EDOT Node.js) is configured with environment variables beginning with OTEL_ or ELASTIC_OTEL_. Any OTEL_* environment variables behave the same as with the upstream OpenTelemetry SDK. For example, all the OpenTelemetry General SDK Configuration env vars are supported. If EDOT Node.js provides a configuration setting specific to the Elastic distribution, it will begin with ELASTIC_OTEL_.

If not configured, EDOT Node.js will send telemetry data to http://localhost:4318 with no authentication information, and identify the running service as unknown_service:node. Typically a minimal configuration will include

• OTEL_EXPORTER_OTLP_ENDPOINT: The full URL of an OpenTelemetry Collector where data will be sent.
• OTEL_EXPORTER_OTLP_HEADERS: A comma-separated list of HTTP headers used for exporting data, typically used to set the Authorization header with auth information.
• OTEL_SERVICE_NAME: The name of your service, used to distinguish telemetry data from other services in your system.

For example, when using an Elastic Cloud Serverless deployment this might be:

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

This section attempts to list all environment variables that can be used to configure EDOT Node.js. Some settings also have a section below discussing behavior that is interesting and/or specific to EDOT Node.js.

The 🔹 symbol denotes settings with a default value or behavior that differs between EDOT Node.js and upstream OTel JS, or that only exists in EDOT Node.js.

The following settings are deprecated:

This section includes additional details on some configuration settings that merit more explanation, or that have behavior that differs in EDOT Node.js when compared to upstream OpenTelemetry JS.

A comma-separated list of named resource detectors to use. EDOT Node.js supports the same set as the upstream @opentelemetry/auto-instrumentations-node:

• env
• host
• os
• process
• serviceinstance
• container
• alibaba
• aws
• azure
• gcp - (temporarily removed)
• all - enable all resource detectors (the default)
• none - disable resource detection

The "cloud" resource detectors (alibaba, aws, azure, gcp) typically make HTTP requests to local metadata services to gather cloud.* and related resource attributes. If it is important to your application to not attempt to gather cloud data on startup, use the following or similar:

export OTEL_NODE_RESOURCE_DETECTORS=env,host,os,process,serviceinstance,container

In addition, EDOT Node.js always includes the telemetry.distro.* resource attributes.

OTEL_NODE_DISABLED_INSTRUMENTATIONS is a comma-separated list of instrumentation names to disable, from the default set. OTEL_NODE_ENABLED_INSTRUMENTATIONS is a comma-separated list of instrumentation names to enable. Specifying this results in only those instrumentations being enabled.

The default set of enabled instrumentations is the set of included instrumentations, minus any that are noted as "disabled by default".

EDOT Node.js handles these settings the same as the upstream @opentelemetry/auto-instrumentations-node, with one addition. In @opentelemetry/auto-instrumentations-node, the name of an instrumentation is the name of the package with the @opentelemetry/instrumentation- prefix removed -- cassandra-driver refers to the instrumentation provided by @opentelemetry/instrumentation-cassandra. EDOT Node.js can include instrumentations that do not have this prefix, e.g. @elastic/opentelemetry-instrumentation-openai. In these cases, the "name" for the instrumentation is the full package name. For example, to enable only instrumentation for openai, http, fastify, and pino one could use:

export OTEL_NODE_ENABLED_INSTRUMENTATIONS=http,fastify,pino,@elastic/opentelemetry-instrumentation-openai

EDOT Node.js enables the collection and export of metrics by default. If you wish to disable metrics you can by setting the environment variable ELASTIC_OTEL_METRICS_DISABLED to the string true.

Setting ELASTIC_OTEL_METRICS_DISABLED=true is similar to setting OTEL_METRICS_EXPORTER=none, in that it ensures no metrics are exported by the SDK. However, this setting will also disable the collection of metrics by the @opentelemetry/host-metrics and @opentelemetry/instrumentation-runtime-node packages, which can be a minor performace improvement.

You can achieve better control of the metrics by setting the appropiate values through the OTEL_NODE_{DISABLED,ENABLED}_INSTRUMENTATIONS and ELASTIC_OTEL_HOST_METRICS_DISABLED environment variables.

• To turn off collection for the @opentelemetry/host-metrics package, set ELASTIC_OTEL_HOST_METRICS_DISABLED to false.
• To turn off collection for the @opentelemetry/instrumentation-runtime-node package, set OTEL_NODE_{DISABLED,ENABLED}_INSTRUMENTATIONS to exclude that instrumentation. (EDOT Ref)

EDOT Node.js collects and export host metrics by default. To turn off metrics collected through the @opentelemetry/host-metrics package, set the ELASTIC_HOST_OTEL_METRICS_DISABLED environment variable to true.

Elasticsearch and Kibana work best with metrics provided in delta-temporality. Therefore, the EDOT Node.js changes the default value of OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE to delta. You can override this default if needed, note though that some provided Kibana dashboards will not work correctly in this case.

Upstream OpenTelemetry defaults the temporality preference to cumulative. See https://opentelemetry.io/docs/specs/otel/metrics/sdk_exporters/otlp/#additional-environment-variable-configuration

The OTEL_SEMCONV_STABILITY_OPT_IN environment variable is defined by OpenTelemetry as the mechanism for user-controlled migration from experimental to stable semantic conventions. Currently it only applies to HTTP semantic conventions. See the OpenTelemetry HTTP semconv stability migration doc for an introduction.

For Node.js usage, the following instrumentations produce telemetry using HTTP semantic conventions:

• @opentelemetry/instrumentation-http: Currently transitioning from old to stable HTTP semantic conventions, via the OTEL_SEMCONV_STABILITY_OPT_IN setting.
• @opentelemetry/instrumentation-undici: Uses the stable HTTP semantic conventions, because this instrumentation was created after HTTP semconv had stabilized.

EDOT Node.js differs from current upstream OTel JS in that it defaults OTEL_SEMCONV_STABILITY_OPT_IN to http. This means that, by default, all HTTP-related telemetry from EDOT Node.js will use the newer, stable HTTP semantic conventions. (This difference from upstream is expected to be temporary, as upstream @opentelemetry/instrumentation-http switches to producing only stable HTTP semantic conventions after its transition period.)

Set OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT to true to enable capture of content data, such as prompt and completion content, in GenAI telemetry. Currently this applies to the @elastic/opentelemetry-instrumentation-openai instrumentation for the OpenAI Node.js client that is included in EDOT Node.js

The OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT boolean environment variable is a convention established by the OpenTelemetry GenAI SIG. It is referenced in https://opentelemetry.io/blog/2024/otel-generative-ai/.