Migrating to EDOT Java from the Elastic Java Agent

This documentation describes how to update applications that are currently using the Elastic APM Java agent to use the Elastic Distribution of OpenTelemetry Java (EDOT Java).

Advantages of using EDOT Java agent

OpenTelemetry-native Data

Allows to 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.

Broad Coverage of Instrumentation

OpenTelemetry Java Instrumentation provides a broad coverage of libraries, frameworks and applications.

• Libraries and frameworks
• Application servers

Compatible Drop-in Replacement

The upstream OpenTelemetry Java Agent is a vendor-neutral implementation. EDOT Java is a distribution of it and is thus a fully compatible drop-in replacement of the upstream OpenTelemetry Java Agent.

Hence, exclusive features of EDOT aside, there is no vendor lock-in through proprietary instrumentation or agent.

Limitations

Supported Java Versions

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

Missing Instrumentations

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

Central and Dynamic configuration

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, e.g. environment variables.

Span compression

EDOT Java does not implement span compression.

Breakdown metrics

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

No remote attach

There is currently no EDOT Java equivalent for starting the agent with the remote attach capability. The -javaagent: option is the preferred startup mechanism. There is a migration path for starting the agent with self attach, which is to use runtime attachment.

Micrometer disabled by default

By default, micrometer instrumentation is disabled and won’t capture metrics, enabling requires to set otel.instrumentation.micrometer.enabled=true.

Migration steps

1. Review all pros/cons of this migration guide including the differences in performance overhead.
2. (Optional) Migrate manual instrumentation API: Usages of the Elastic APM Agent API require migration to OpenTelemetry API:
   • for Annotation API see OpenTelemetry Annotations.
   • for Transaction API see OpenTelemetry API.

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

3. Replace configuration options using the Reference below, see Configuration for ways to provide those.
4. Replace Agent binary
   • Remove the -javaagent: argument containing Elastic APM Java agent from the JVM arguments
   • Add -javaagent: argument to the JVM arguments to use EDOT Java and restart the application or follow Kubernetes instructions if applicable

Option reference

This list contains APM Java agent configuration options that can be migrated to EDOT Java agent configuration because they have an equivalent in OpenTelemetry:

• server_url
• server_urls
• secret_token
• api_key
• service_name
• enabled
• service_version
• environment
• global_labels
• trace_methods

server_url

The Elastic server_url option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_ENDPOINT option.

server_urls

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

Use OTEL_EXPORTER_OTLP_ENDPOINT instead.

secret_token

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".

api_key

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".

service_name

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.

enabled

The Elastic enabled option corresponds to the OpenTelemetry OTEL_JAVAAGENT_ENABLED option.

service_version

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.

environment

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

For example: OTEL_RESOURCE_ATTRIBUTES=deployment.environment=testing.

global_labels

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

trace_methods

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.