Loading

Migrate to EDOT Node.js from the Elastic APM Node.js agent

Elastic Stack Serverless Observability

Compared to the Elastic APM Node.js agent, the Elastic Distribution of OpenTelemetry Node.js presents a number of advantages:

  • Fully automatic instrumentation with zero code changes. No need to modify application code.
  • EDOT Node.js is built on top of OpenTelemetry SDK and conventions, ensuring compatibility with community tools, vendor-neutral backends, and so on.
  • Modular, extensible architecture based on the OpenTelemetry SDK. You can add custom exporters, processors, and samplers.
  • You can use EDOT Node.js in environments where both tracing and metrics are collected using OpenTelemetry.

Follow these steps to migrate from the legacy Elastic APM PHP agent (elastic-apm-node) to the Elastic Distribution of OpenTelemetry PHP (@elastic/opentelemetry-node).

  1. Replace the Node.js package

    Remove the Elastic APM Node.js Agent package and install EDOT Node.js:

    npm uninstall elastic-apm-node
npm install --save @elastic/opentelemetry-node

  2. Remove APM Node.js start method

    For services starting the APM Node.js Agent by using require() with the require and start or require start module methods, the require('elastic-apm-node'), remove the code.

    For services starting with the --require Node.js CLI option, remove the option. If the --require option is defined in NODE_OPTIONS environment variable, remove it there.

  3. (Optional) Migrate manual instrumentation API

    If you're using the Elastic APM Node.js Agent API to create manual transactions and spans you should refactor the code to use @opentelemetry/api methods. OpenTelemetry documentation has several examples of how to create spans manually.

  4. Replace configuration options

    Refer to the Configuration mapping. Refer to Configuration for details on EDOT Node.js configuration.

  5. Add EDOT Node.js start method

    Use the Node.js --import option to start EDOT Node.js with your service.

    Set it on the command-line using node --import @elastic/opentelemetry-node service.js or in the NODE_OPTIONS environment variable: NODE_OPTIONS="--import @elastic/opentelemetry-node" node service.js.

This list contains Elastic APM Node.js agent configuration options that can be migrated to EDOT Node.js SDK configuration because they have an equivalent in OpenTelemetry.

The Elastic APM Node.js agent serverUrl option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_ENDPOINT option.

The Elastic APM Node.js agent secretToken option corresponds to setting the Authorization header in the OpenTelemetry OTEL_EXPORTER_OTLP_HEADERS option.

For example: OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer an_apm_secret_token".

Note

Secret token usage is discouraged. Use API keys for authentication.

The Elastic APM Node.js agent apiKey option corresponds to setting the Authorization header in the OpenTelemetry OTEL_EXPORTER_OTLP_HEADERS option.

For example:OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_api_key".

The Elastic APM Node.js agent serviceName option corresponds to the OpenTelemetry OTEL_SERVICE_NAME option.

You can also set the service name using OTEL_RESOURCE_ATTRIBUTES. For example: OTEL_RESOURCE_ATTRIBUTES=service.name=myservice. A value in OTEL_SERVICE_NAME takes precedence over a service.name value in OTEL_RESOURCE_ATTRIBUTES.

The Elastic APM Node.js agent active option corresponds to the OpenTelemetry OTEL_SDK_DISABLED option but it has the opposite meaning.

Set the OTEL_SDK_DISABLED to true if you want to deactivate the agent. For example: OTEL_SDK_DISABLED=true.

The Elastic APM Node.js agent serviceVersion option corresponds to setting the service.version key in OTEL_RESOURCE_ATTRIBUTES.

For example: OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3.

The Elastic APM Node.js agent environment option corresponds to setting the deployment.environment key in OTEL_RESOURCE_ATTRIBUTES.

For example: OTEL_RESOURCE_ATTRIBUTES=deployment.environment=testing.

The Elastic APM Node.js agent globalLabels option corresponds to adding key=value comma separated pairs in OTEL_RESOURCE_ATTRIBUTES.

For example: OTEL_RESOURCE_ATTRIBUTES=alice=first,bob=second. Such labels will result in labels.key=value attributes on the server. For example, labels.alice=first.

The Elastic APM Node.js agent transactionSampleRate corresponds to the OpenTelemetry OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG options.

For example, for the equivalent of transactionSampleRate: '0.25' use OTEL_TRACES_SAMPLER=parentbased_traceidratio OTEL_TRACES_SAMPLER_ARG=0.25.

The Elastic APM Node.js agent logLevel option corresponds to the OpenTelemetry OTEL_LOG_LEVEL option.

The following table shows the equivalent values of log levels between elastic-apm-node and EDOT Node.js.

ELASTIC_APM_LOG_LEVEL OTEL_LOG_LEVEL
off none
error error
warn warn
info info
debug debug
trace verbose
trace all

The Elastic APM Node.js agent maxQueueSize option corresponds to a couple of OpenTelemetry options:

For example: OTEL_BSP_MAX_QUEUE_SIZE=2048 OTEL_BLRP_MAX_QUEUE_SIZE=4096.

The Elastic APM Node.js agent serverTimeout option corresponds to a OpenTelemetry options per signal:

For example: OTEL_BSP_EXPORT_TIMEOUT=50000 OTEL_BLRP_EXPORT_TIMEOUT=50000 OTEL_METRIC_EXPORT_TIMEOUT=50000.

The Elastic APM Node.js agent apmClientHeaders option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_HEADERS option.

For example: OTEL_EXPORTER_OTLP_HEADERS=foo=bar,baz=quux.

The Elastic APM Node.js agent disableInstrumentations option corresponds to the EDOT Node.js OTEL_NODE_DISABLED_INSTRUMENTATIONS option.

For example: OTEL_NODE_DISABLED_INSTRUMENTATIONS=express,mysql.

The Elastic APM Node.js agent metricsInterval option corresponds to the OpenTelemetry OTEL_METRIC_EXPORT_INTERVAL option.

For example: OTEL_METRIC_EXPORT_INTERVAL=30000.

The Elastic APM Node.js agent cloudProvider option does not corresponds directly to an OpenTelemetry option but you can get similar behavior by properly setting OTEL_NODE_RESOURCE_DETECTORS option. If you set this option make sure you add along with the cloud detector the non-cloud detectors that apply to your service. For a full list of detectors check OTEL_NODE_RESOURCE_DETECTORS details. Not setting this option is the equivalent of auto.

For example: OTEL_NODE_RESOURCE_DETECTORS=os,env,host,serviceinstance,process,aws will make the agent query for AWS metadata only and use other non-cloud detectors to enrich that metadata.

The following limitations apply to EDOT Node.js.

EDOT Node.js and OpenTelemetry upstream SDK support Node.js versions in the range ^18.19.0 || >=20.6.0. Elastic APM Node.js works with Node.js versions >=14.17.0, though with limited support for Node.js 14 and 16 given that those major versions of Node.js are out of long-term support.

EDOT Node.js doesn't currently support instrumentation for AWS Lambda and Azure Functions. However, there are upstream and third-party options based on OpenTelemetry:

Currently EDOT Node.js does not yet have an equivalent of the central configuration feature that the Elastic APM Node.js agent supports. When using EDOT Node.js, all the configurations are static and must be provided to the application as environment variables.

EDOT Node.js does not implement span compression.