Loading

Migrate to EDOT Java from the Elastic APM Java agent

Elastic Stack Serverless Observability

Compared to the Elastic APM Java agent, the Elastic Distribution of OpenTelemetry Java presents a number of advantages:

  • Fully automatic instrumentation with zero code changes. No need to modify application code.
  • Capture, send, transform, and store data in an OpenTelemetry native way. This includes for example the ability to use all features of the OpenTelemetry SDK for manual tracing, data following semantic conventions, or ability to use intermediate collectors and processors.
  • OpenTelemetry Java Instrumentation provides a broad coverage of libraries, frameworks, and applications.
  • EDOT Java is built on top of OpenTelemetry SDK and conventions, ensuring compatibility with community tools, vendor-neutral backends, and so on.

Follow these steps to migrate from the legacy Elastic APM Java agent to the Elastic Distribution of OpenTelemetry Java.

  1. (Optional) Migrate manual instrumentation API

    Migrate usages of the Elastic APM Agent API to OpenTelemetry API:

    Note

    Migration of application code using these APIs and annotations is not strictly required when deploying the EDOT agent. If not migrated, spans, transactions, and metrics that were previously created with those custom API calls and annotations will no longer be generated. OpenTelemetry instrumentation coverage might replace the need for some or all of these custom code changes.

  2. Replace configuration options

    Refer to the Configuration mapping. Refer to Configuration for ways to provide configuration settings.

  3. Replace the agent binary

    Remove the -javaagent: argument that contains the Elastic APM Java agent from the JVM arguments. Then add the -javaagent: argument to the JVM arguments to use EDOT Java, and restart the application or follow Kubernetes instructions or Runtime attach instructions if applicable. Refer to Setup.

The following are Elastic APM Java agent settings that you can migrate to EDOT Java.

The Elastic server_url option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_ENDPOINT option.

The Elastic server_urls option has no equivalent OpenTelemetry option. You can only specify one endpoint.

Use OTEL_EXPORTER_OTLP_ENDPOINT instead.

The Elastic secret_token option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_HEADERS option.

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

The Elastic api_key option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_HEADERS option.

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

The Elastic service_name option corresponds to the OpenTelemetry OTEL_SERVICE_NAME option.

The service name value can also be set using OTEL_RESOURCE_ATTRIBUTES.

For example: OTEL_RESOURCE_ATTRIBUTES=service.name=myservice. If OTEL_SERVICE_NAME is set, it takes precedence over the resource attribute.

The Elastic enabled option corresponds to the OpenTelemetry OTEL_JAVAAGENT_ENABLED option.

The Elastic service_version option corresponds to setting the service.version key in OTEL_RESOURCE_ATTRIBUTES.

For example: OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3.

The Elastic environment option corresponds to setting the deployment.environment key in OTEL_RESOURCE_ATTRIBUTES.

For example: OTEL_RESOURCE_ATTRIBUTES=deployment.environment=testing.

The Elastic global_labels 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, e.g. labels.alice=first

The Elastic [trace_methods] option can be replaced by the OTEL_INSTRUMENTATION_METHODS_INCLUDE OpenTelemetry option, however the syntax is different and the ability to use wildcards is more limited.

The Elastic capture_jmx_metrics option can be replaced by OpenTelemetry JMX Insight feature which is included in EDOT Java.

The JMX Insight feature provides the following benefits:

  • Ability to define custom metrics using YAML.
  • Capturing metrics with pre-defined metrics by using OTEL_JMX_TARGET_SYSTEM configuration option.

Replace the Elastic capture_headers option with the following options:

  • otel.instrumentation.http.server.capture-request-headers for HTTP server request
  • otel.instrumentation.http.server.capture-response-headers for HTTP server response
  • otel.instrumentation.http.client.capture-request-headers for HTTP client request
  • otel.instrumentation.http.client.capture-response-headers for HTTP client response
  • otel.instrumentation.messaging.experimental.capture-headers for messaging

The capture_headers option is dynamically adjustable, while the otel.* options are statically set by startup and cannot be subsequently adjusted.

Replace the Elastic span_stack_trace_min_duration option with OTEL_JAVA_EXPERIMENTAL_SPAN_STACKTRACE_MIN_DURATION.

Replace the disable_instrumentations option, which allows to selectively disable instrumentation (opt-out), with OTEL_INSTRUMENTATION_<name>_ENABLED where <name> is the instrumentation name.

See OpenTelemetry documentation for reference and values.

The enable_instrumentations option allows to disable all instrumentation enabled by default and selectively enable instrumentation (opt-in) can be replaced with:

  • OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED = false to disable instrumentations enabled by default.
  • OTEL_INSTRUMENTATION_<name>_ENABLED = true where <name> is the name of the instrumentation to enable. See OpenTelemetry documentation for reference and values.

The Elastic hostname option corresponds to setting the host.name key in OTEL_RESOURCE_ATTRIBUTES.

For example: OTEL_RESOURCE_ATTRIBUTES=host.name=myhost.

The Elastic service_node_name option corresponds to setting the service.instance.id key in OTEL_RESOURCE_ATTRIBUTES. Warning: by default this is a generated unique ID; if you set this it must be a unique value for each JVM otherwise metric views cannot be correctly aggregated nor disambiguated

For example: OTEL_RESOURCE_ATTRIBUTES=service.instance.id=myserviceinstance001.

The Elastic cloud_provider option corresponds to the per-provider otel.resource.providers.{provider}.enabled configuration options.

By default, with EDOT otel.resource.providers.{provider}.enabled is set to true, this is equivalent to the cloud_provider default valuem which is auto, or automatically detect cloud providers. Notice that this behavior differs from upstream OpenTelemetry distribution.

When the cloud provider is known, or there is none, turning off the non-relevant providers with otel.resource.providers.{provider}.enabled = false allows to minimize the application startup overhead.

The following limitations apply to EDOT Java.

EDOT Java agent and OpenTelemetry Java instrumentation are only compatible with Java 8 and later.

Support for LDAP client instrumentation is not currently available in EDOT Java.

Currently EDOT Java does not have an equivalent of the central configuration feature that the Elastic APM Java agent supports.

When using EDOT Java, all the configurations are static and should be provided to the application with other configurations, such as environment variables.

EDOT Java does not implement span compression.

EDOT Java is not sending metrics that power the Breakdown metrics.

There is currently no EDOT Java equivalent for starting the agent with the remote attach capability. The -javaagent: option is the preferred startup mechanism.

A migration path is available for starting the agent with self attach, which is to use runtime attachment. Some limitations apply, and the agent must be started early during application startup.

By default, Micrometer instrumentation is inactive and doesn't capture metrics. To turn it on, use the otel.instrumentation.micrometer.enabled=true setting.