Documentación de Oracle Cloud Infrastructure

Configurar el agente Java de APM para que funcione con OpenTelemetry

El agente Java de APM se puede configurar para que funcione con OpenTelemetry.

Puede seguir utilizando la instrumentación y la supervisión del agente Java de APM y hacer que se conecte a la supervisión OpenTelemetry existente.

Si desea poder utilizar agentes OpenTelemetry existentes con APM, consulte lo siguiente: Configuración de OpenTelemetry y otros rastreadores.

Nota

La instrumentación automática del agente Java OpenTelemetry (opentelemetry-javaagent.jar) no está soportada. Esta función está diseñada para funcionar con aplicaciones/bibliotecas que utilizan las API OpenTelemetry para realizar la instrumentación manual, creando sus propios intervalos/rastreos (opentelemetry-api).

Una vez configurado el agente Java de APM, funciona de forma similar al modo híbrido del agente Java de APM, excepto que también funciona con las API de OpenTelemetry junto con las API de OpenTracing.

En esta sección, se tratan los siguientes temas:

Nota

W3C La propagación de equipaje está soportada a partir de la versión 1.17 del agente Java de APM.

El escenario de solo rastreo no está disponible. Sin embargo, cuando el agente Java de APM está configurado para funcionar con OpenTelemetry, su valor por defecto se ajustará a W3C, que es el formato que OpenTelemetry utiliza por defecto.

Activar OpenTelemetry en el agente de APM

El agente Java de APM soporta rastreos y métricas de OpenTelemetry. Utilice la siguiente propiedad para activar OpenTelemetry para la instrumentación manual y las métricas personalizadas:

Tipo y descripción de propiedades Propiedades Por defecto Ejemplo

AgentConfig.properties

Actualice el archivo AgentConfig.properties ubicado en el directorio oracle-apm-agent/config/<version>.

com.oracle.apm.agent.otel false com.oracle.apm.agent.hybrid=false

Propiedades del sistema

Actualiza las propiedades del sistema.

 com.oracle.apm.agent.otel false com.oracle.apm.agent.otel=false

Variables de entorno

Actualiza las variables de entorno.

 com_oracle_apm_agent_otel false

Para Windows: set com_oracle_apm_agent_otel=false

Para Linux: export com_oracle_apm_agent_otel=false
Nota

OpenTelemetry necesita Java 8 y superior. La propiedad: com.oracle.apm.agent.otel=false se aplica en Java 7 o inferior.

Al iniciar el agente Java de APM, se inicia la instancia OpenTelemetry. Se puede acceder a la instancia OpenTelemetry con GlobalOpenTelemetry.get().

Utilizar otras versiones de OpenTelemetry

El agente Java de APM 1.14 tiene bibliotecas OpenTelemetry 1.38.0 incorporadas. Dado que el agente Java de APM soporta la instrumentación manual para OpenTelemetry, la versión de API de la que depende el proyecto puede ser diferente.

Las API de las versiones más recientes de OpenTelemetry normalmente son compatibles con versiones anteriores. Los usuarios pueden sustituir el agente Java de APM incorporado OpenTelemetry 1.38.0 por una versión más reciente. Para utilizar otra versión de OpenTelemetry, siga estos pasos:
  1. Cree el directorio opentelemetry en el directorio principal del agente. Por ejemplo: oracle-apm-agent/opentelemetry.
  2. Copie las bibliotecas OpenTelemetry que se utilizarán en el nuevo directorio.

    Las bibliotecas deben tener el siguiente ID de artefacto, y las que no empiecen por opentelemetry dependen de las bibliotecas de opentelemetry.

    • opentelemetría-api

    • opentelemetría-api-incubadora

    • contexto de opentelemetría

    • opentelemetría-exportador-común

    • opentelemetría-exportador-otlp

    • opentelemetría-exportador-otlp-común

    • opentelemetría-exportador-sender-okhttp

    • propagadores opentelemetry-extension-trace

    • opentelemetría-sdk

    • opentelemetría-sdk-común

    • opentelemetry-sdk-extension-autoconfiguración

    • opentelemetry-sdk-extension-autoconfigure-spi

    • opentelemetry-sdk-logs

    • opentelemetría-sdk-métricas

    • opentelemetry-sdk-trace

    • anotaciones
    • kotlin-stdlib
    • kotlin-stdlib-común
    • kotlin-stdlib-jdk7
    • kotlin-stdlib-jdk8

    • okhttp

    • okio-3.6.0.jarokio-jvm

    Nota

    Las bibliotecas de diferentes versiones de OpenTelemetry pueden tener nombres de biblioteca diferentes.
  3. Utilice el comando apm-java-agent-installer provision-agent-upgrade de APM con la opción -overwrite para actualizar oracle-apm-agent/bootstrap/ApmAgent.jar.

    Este paso es necesario para actualizar ApmAgent.jar para utilizar bibliotecas de opentelemetría personalizadas. Por ejemplo: 

    java -jar apm-java-agent-installer-<version>.jar provision-agent-upgrade -destination=<oracle-apm-agent_parent_path> -overwrite

Configuración de propagación

Los detalles del manejo del tipo de propagación del agente Java de APM se pueden ver en Configuración de OpenTelemetry y otros rastreadores.

Por defecto, utiliza el formato B3 (varias cabeceras) para manejar la propagación. Sin embargo, cuando el agente Java de APM está configurado para trabajar con OpenTelemetry, este valor por defecto se ajustará a W3C, que es el formato que utiliza OpenTelemetry por defecto.

Si decide especificar el parámetro: com.oracle.apm.agent.tracer.propagation.type en el archivo AgentConfig.properties, sustituirá el comportamiento por defecto, lo que le permitirá utilizar el tipo de propagación que prefiera. Tenga en cuenta que lo siguiente también debe ajustarse para tener todo conectado y trabajando juntos:
  • Actualización de OpenTelemetry: OpenTelemetry tiene su propia propiedad para cambiar los propagadores que se utilizan.

    Puede utilizar la propiedad del sistema: otel.propagators o la variable de entorno: OTEL_PROPAGATORS para actualizar los propagadores. Para obtener detalles sobre los valores, consulte https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_propagators.

    Nota

    Si desea cambiar OpenTelemetry para utilizar el mismo formato de cabeceras B3 que utiliza por defecto el agente Java de APM, actualice OpenTelemetry para utilizar el propagador b3multi. Si utiliza B3SINGLE para la propagación, actualice OpenTelemetry para utilizar el propagador B3.

  • Actualización del agente de explorador: si utiliza la inyección del agente de explorador, debe actualizar el javascript para utilizar un tipo de propagación diferente. Por defecto, utiliza B3 (varias cabeceras). Para obtener más información, consulte Configuración de instrumentación de llamadas Ajax.