Documentación de Oracle Cloud Infrastructure

Configuración del modo híbrido del agente Java de APM

El modo híbrido APM Java Agent, también denominado modo híbrido APM Agent, permite que el período de sondeo del agente y el período de aplicación formen un rastreo completo.

La función de modo híbrido APM Agent combina la instrumentación de código de byte y la instrumentación manual OpenTracing/OpenTelemetry para proporcionar una imagen completa del flujo de aplicaciones.

Proporciona un mecanismo para asegurarse de que las bibliotecas OpenTracing y OpenTelemetry se cargan en un ClassLoader común al que se puede acceder desde el agente de APM y toda la aplicación. Por lo tanto, los períodos se pueden crear en la aplicación y se enlazan a los períodos creados por el sondeo del agente de APM automáticamente.

Los períodos creados por el sondeo del agente APM se enlazan automáticamente a cualquier intervalo activado.

Requisitos

  • El agente de APM es totalmente funcional antes de activar la propiedad.
    Para OpenTelemetry, utilice la propiedad com.oracle.apm.agent.otel=true.
    Nota

    OpenTelemetry necesita Java 8 y superior.
  • La aplicación debe obtener la instancia de rastreo OpenTracing mediante GlobalTracer.get() u obtener la instancia OpenTelemetry con el método GlobalOpenTelemetry.get().
  • Misma versión de biblioteca.

    Para OpenTracing, el agente de APM y la aplicación utilizan la misma versión de biblioteca OpenTracing.

    Para OpenTelemetry, el agente de APM y la aplicación utilizan la misma versión de biblioteca OpenTelemetry. Para obtener más información, consulte Configuración del agente Java de APM para trabajar con OpenTelemetry.

Activar modo híbrido de agente de APM

El modo híbrido del agente de APM está activado por defecto.

Para desactivarla, utilice la propiedad: com.oracle.apm.agent.hybrid=false. Sin embargo, si la propiedad OpenTelemetry: com.oracle.apm.agent.otel=true está definida, el modo híbrido siempre está activado.

Tipo y descripción de propiedades Propiedades Ejemplo

AgentConfig.properties

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

com.oracle.apm.agent.hybrid com.oracle.apm.agent.hybrid=true

Propiedades del sistema

Actualiza las propiedades del sistema.

 com.oracle.apm.agent.hybrid -Dcom.oracle.apm.agent.hybrid=true

Variables de entorno

Actualiza las variables de entorno.

 com_oracle_apm_agent_hybrid
Para Windows: 
set com_oracle_apm_agent_hybrid=true
Para Linux: 
export com_oracle_apm_agent_hybrid=true

Definir la propiedad es el único paso necesario para la mayoría de los servidores de aplicaciones y microservicios. Sin embargo, algunos servidores de aplicaciones pueden tener una lógica de carga de clases diferente y aislamientos de definición de clase. Para asegurarse de que el agente de APM utiliza la misma definición de clase OpenTracing y OpenTelemetry, puede que sea necesario el siguiente paso adicional:

  • Copie las bibliotecas OpenTracing y OpenTelemetry del directorio oracle-apm-agent/install/<version>/lib/ext en el directorio oracle-apm-agent/bootstrap.

El paso anterior garantiza que el agente de APM y todas las aplicaciones utilizarán las bibliotecas OpenTracing y OpenTelemetry copiadas, por lo tanto, las mismas definiciones de clase OpenTracing y OpenTelemetry.

Bibliotecas del agente de APM y las bibliotecas OpenTracing y OpenTelemetry: las bibliotecas OpenTracing versión 0.33 y OpenTelemetry versión 1.38.0 se incluyen con el agente de APM. Si la aplicación necesita utilizar la API específica de la versión 0.32 de OpenTracing, es posible copiar las bibliotecas OpenTracing 0.32 en el directorio oracle-apm-agent/bootstrap. APM admite bibliotecas OpenTracing 0.32 y 0.33. Para que la aplicación necesite utilizar una versión OpenTelemetry diferente, Configure el agente Java de APM para trabajar con OpenTelemetry.

En general, el paso adicional es necesario para lo siguiente:

  • Cuando las bibliotecas OpenTracing se incluyen explícitamente en la classpath de microservicios.

  • Cuando el cargador de clases del servidor de aplicaciones no prioriza la carga de clases al cargador de clases principal. Por ejemplo, Tomcat.

Preguntas frecuentes

  1. ¿Por qué el intervalo de sondeo del agente, como el intervalo JDBC, no se ha enlazado al intervalo de aplicación, ni siquiera las llamadas JDBC se han realizado dentro del ámbito de abarcamiento de la aplicación?

    R: Para que el sondeo del agente cree un enlace de expansión, el intervalo de aplicación se debe activar antes de las llamadas JDBC.

  2. ¿Por qué no se han vinculado los períodos de sondeo del agente a los períodos de Helidon?

    R: Si los períodos creados por Helidon no están activados, puede crear un nuevo período y activarlos con el principal SpanContext desde ServerRequest. Después, todos los períodos del sondeo de agente serán secundarios del nuevo período.

  3. ¿Cómo funciona el modo híbrido del agente cuando mi aplicación ha incrustado OpenTracing versión 0.32 mientras que el agente de APM tiene la versión 0.33 de OpenTracing?

    R: En esos casos, debe considerar la actualización de la aplicación para utilizar OpenTracing 0.33.

    Si eso no es posible, puede cambiar las bibliotecas OpenTracing de oracle-apm-agent/install/<version>/lib/ext a 0.32. El agente de APM es compatible con las versiones 0.32 y 0.33 de OpenTracing.

  4. ¿Por qué el agente de APM y mi aplicación crearon rastreos independientes a petición después de activar el modo híbrido del agente?

    R: Compruebe los pasos de configuración y confirme que la propiedad se ha definido correctamente. Para obtener más información, consulte Activación del modo híbrido del agente de APM.

    Si el problema persiste, es posible que deba copiar bibliotecas OpenTracing en oracle-apm-agent/bootstrap.

  5. ¿Puedo utilizar el modo híbrido desde el agente (1.3+) con la aplicación existente creada con el rastreador de APM (1.2 o inferior)?

    A: No. El agente de APM desplegado y el rastreador de APM utilizados para la creación de aplicaciones deben ser al menos 1,3.

  6. ¿Por qué se utiliza el nombre de servicio en AgentConfig.properties para el rastreador con una configuración de nombre de servicio diferente cuando el modo híbrido está activado?

    R: En el caso del modo híbrido, el agente de APM inicia un rastreador y se registra como rastreador global. Si la aplicación o el microservicio inician un rastreo, la instancia de rastreo es en realidad la instancia de rastreo global. Por lo tanto, utiliza el mismo nombre de servicio que el definido en el archivo AgentConfig.properties. Para utilizar un nombre de servicio diferente para distintas instancias de agente, se debe sustituir el nombre de servicio por la propiedad del sistema java o la variable de entorno.

  7. ¿Cómo sustituir el nombre de servicio en el archivo AgentConfig.properties?

    R: Se puede sustituir el nombre del servicio definiendo la propiedad del sistema java (com.oracle.apm.agent.service.name) o la variable de entorno (com_oracle_apm_agent_service_name).

  8. ¿Cómo habilitar el modo híbrido Opentracing para aplicaciones Micronaut?
    1. Siga las instrucciones descritas anteriormente en Configuración del modo híbrido de agente Java de APM.
    2. Agregue el rastreador de Micronaut de APM en el archivo pom.xml de la aplicación como una dependencia. Consulte Uso del rastreador de APM en Micronaut para obtener más información.