Oracle Cloud Infrastructure Documentation

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.

Note

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:

Note

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 AgentConfig.properties file located under oracle-apm-agent/config/<version> directory.

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: set com_oracle_apm_agent_otel=false

For Linux: export com_oracle_apm_agent_otel=false
Note

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.

API of newer OpenTelemetry versions are normally backward compatible with old ones. Users can override APM Java agent built-in OpenTelemetry 1.38.0 with newer version. To use other OpenTelemetry version, follow the steps:
  1. Create the opentelemetry directory in agent home directory. For example: oracle-apm-agent/opentelemetry.
  2. 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.
  3. Use APM apm-java-agent-installer provision-agent-upgrade command with -overwrite option to update oracle-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.

If you decide to specify the parameter: 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_propagators

    Note

    If you want to change OpenTelemetry to use the same B3 headers format as the APM Java agent, you need to use b3multi since APM Java agent does not currently support B3 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.