Configure APM Java Agent to Work with OpenTelemetry
The APM Java Agent can be configured to work with OpenTelemetry.
You can continue using the APM Java Agent's instrumentation and monitoring, and have it connect to existing OpenTelemetry monitoring.
If you want to be able to utilize existing OpenTelemetry agents with APM, see the following: Configure OpenTelemetry and Other Tracers.
OpenTelemetry Java agent automatic instrumentation (opentelemetry-javaagent.jar) is not supported. This feature is meant to work with applications/libraries that are using the OpenTelemetry APIs to do manual instrumentation, creating their own spans/traces (opentelemetry-api).
Once APM Java agent is configured, it works similar to the APM Java agent hybrid mode, except it also works with the OpenTelemetry APIs alongside the OpenTracing APIs.
This section covers the following topics:
Currently the following is not available with APM Java agent 1.14 release:
- Support for W3C's
baggage
header. - Tracer-only scenario.
Enable OpenTelemetry in APM Agent
The APM Java agent supports OpenTelemetry traces and metrics. Use the following property to enable OpenTelemetry for manual instrumentation and custom metrics:
Properties Type and Description | Properties | Default | Example |
---|---|---|---|
AgentConfig.properties Update the |
com.oracle.apm.agent.otel |
false | com.oracle.apm.agent.hybrid=false |
System Properties Update the system properties. |
com.oracle.apm.agent.otel |
false | com.oracle.apm.agent.otel=false |
Environment Variables Update the environment variables. |
com_oracle_apm_agent_otel |
false |
For Windows: For Linux: |
OpenTelemetry requires Java 8 and above. The property:
com.oracle.apm.agent.otel=false
is enforced on Java 7 or below.
Upon APM Java agent startup, OpenTelemetry instance is started. OpenTelemetry instance can be accessed with GlobalOpenTelemetry.get()
.
Use other OpenTelemetry versions
APM Java agent 1.14 has OpenTelemetry 1.38.0 libraries built-in. Since the APM Java agent supports manual instrumentation for OpenTelemetry, the API version that your project depends on could be different.
- Create the
opentelemetry
directory in agent home directory. For example:oracle-apm-agent/opentelemetry
. - Copy OpenTelemetry libraries to be used in the new directory.
Libraries should have the following artifact id, and those not starting with opentelemetry are depending libraries of opentelemetry.
-
opentelemetry-api
-
opentelemetry-api-incubator
-
opentelemetry-context
-
opentelemetry-exporter-common
-
opentelemetry-exporter-otlp
-
opentelemetry-exporter-otlp-common
-
opentelemetry-exporter-sender-okhttp
-
opentelemetry-extension-trace-propagators
-
opentelemetry-sdk
-
opentelemetry-sdk-common
-
opentelemetry-sdk-extension-autoconfigure
-
opentelemetry-sdk-extension-autoconfigure-spi
-
opentelemetry-sdk-logs
-
opentelemetry-sdk-metrics
-
opentelemetry-sdk-trace
- annotations
- kotlin-stdlib
- kotlin-stdlib-common
- kotlin-stdlib-jdk7
- kotlin-stdlib-jdk8
-
okhttp
-
okio-3.6.0.jarokio-jvm
Note
Libraries of different OpenTelemetry version may have different library names. -
- Use APM
apm-java-agent-installer provision-agent-upgrade
command with-overwrite
option to updateoracle-apm-agent/bootstrap/ApmAgent.jar
.This step is required to update
ApmAgent.jar
to use custom opentelemetry libraries. For example:java -jar apm-java-agent-installer-<version>.jar provision-agent-upgrade -destination=<oracle-apm-agent_parent_path> -overwrite
Propagation Settings
The details of the APM Java agent's propagation type handling can be seen in Configure OpenTelemetry and Other Tracers.
By default, it uses the B3
(multi-header) format to handle propagation. However, when the APM Java agent is configured to work with OpenTelemetry, this default value will be adjusted to W3C
which is the format that OpenTelemetry uses by default.
com.oracle.apm.agent.tracer.propagation.type
in the AgentConfig.properties
file, it will override the default behavior, allowing you to use whichever propagation type you prefer. Keep in mind, the following also needs to get adjusted in order to have everything connecting and working together:
- OpenTelemetry update: OpenTelemetry has its own property for changing what propagators are used.
You can use the system property:
otel.propagators
or the environment variable:OTEL_PROPAGATORS
to update the propagators. For value details, refer to https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_propagatorsNote
If you want to change OpenTelemetry to use the sameB3
headers format as the APM Java agent, you need to useb3multi
since APM Java agent does not currently supportB3
single header. - Browser Agent update: If you are using Browser Agent injection, you need to update the javascript to use a different propagation type. By default, it uses
B3
(multi-header). For details, see Configure Ajax Calls Instrumentation.