Documentação do Oracle Cloud Infrastructure

Configurar Modo Híbrido do Agente Java do APM

O modo híbrido do Agente Java do APM, também conhecido como modo híbrido do Agente do APM, permite que o alcance da sondagem do agente e o alcance do aplicativo formem um rastreamento completo.

O recurso de modo híbrido do Agente do APM combina instrumentação de código de bytes e instrumentação manual do OpenTracing/OpenTelemetry para fornecer uma imagem completa do fluxo do aplicativo.

Ele fornece um mecanismo para garantir que as bibliotecas OpenTracing e OpenTelemetry sejam carregadas em um ClassLoader comum acessível pelo Agente do APM e por todo o aplicativo. Portanto, os intervalos podem ser criados no aplicativo e eles são vinculados aos intervalos criados pela sondagem do Agente do APM automaticamente.

Os intervalos criados pela sondagem do Agente APM são automaticamente vinculados a qualquer intervalo ativado.

Pré-requisitos

  • O Agente do APM está totalmente funcional antes de ativar a propriedade.
    Para OpenTelemetry, use a propriedade com.oracle.apm.agent.otel=true.
    Observação

    OpenTelemetry requer o Java 8 e versões posteriores.
  • O aplicativo deve obter a instância do rastreador OpenTracing usando GlobalTracer.get() ou obter a instância OpenTelemetry com o método GlobalOpenTelemetry.get().
  • Mesma versão da biblioteca.

    Para OpenTracing, o Agente do APM e o aplicativo usam a mesma versão da biblioteca OpenTracing.

    Para OpenTelemetry, o Agente do APM e o aplicativo usam a mesma versão da biblioteca OpenTelemetry. Para obter detalhes, consulte Configurar o Agente Java do APM para Trabalhar com OpenTelemetry.

Ativar Modo Híbrido do Agente do APM

O modo híbrido do Agente do APM é ativado por padrão.

Para desativá-lo, use a propriedade: com.oracle.apm.agent.hybrid=false. No entanto, se a propriedade OpenTelemetry: com.oracle.apm.agent.otel=true estiver definida, o modo híbrido estará sempre ativado.

Tipo e Descrição de Propriedades Propriedades Exemplo

AgentConfig.properties

Atualiza o arquivo AgentConfig.properties localizado no diretório oracle-apm-agent/config/<version>.

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

Propriedades do Sistema

Atualiza as propriedades do sistema.

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

Variáveis de Ambiente

Atualiza as variáveis de ambiente.

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

Definir a propriedade é a única etapa necessária para a maioria dos servidores de aplicativos e microsserviços. No entanto, alguns servidores de aplicativos podem ter uma lógica de carregamento de classe diferente e isolações de definição de classe. Para garantir que o Agente do APM use a mesma definição de classe OpenTracing e OpenTelemetry, talvez seja necessária a seguinte etapa adicional:

  • Copie as bibliotecas OpenTracing e OpenTelemetry do diretório oracle-apm-agent/install/<version>/lib/ext para o diretório oracle-apm-agent/bootstrap.

A etapa acima garante que o Agente do APM e todos os aplicativos usarão as bibliotecas OpenTracing e OpenTelemetry copiadas, portanto, as mesmas definições de classe OpenTracing e OpenTelemetry.

As bibliotecas APM Agent e OpenTracing e OpenTelemetry: as versões 0.33 e OpenTelemetry das bibliotecas OpenTracing, versão 1.38.0, estão incluídas no Agente do APM. Se o aplicativo exigir o uso de uma API específica do OpenTracing versão 0.32, será possível copiar as bibliotecas OpenTracing 0.32 para o diretório oracle-apm-agent/bootstrap. O APM suporta as bibliotecas OpenTracing 0.32 e 0.33. Para o aplicativo necessário para usar outra versão do OpenTelemetry, Configure o Agente Java do APM para Trabalhar com o OpenTelemetry.

Em geral, a etapa adicional é necessária para o seguinte:

  • Quando as bibliotecas OpenTracing são explicitamente incluídas no classpath dos microsserviços.

  • Quando o classloaderver apps não prioriza o carregamento de classes para o classloader pai. Por exemplo, Tomcat.

Perguntas Mais Frequentes

  1. Por que o intervalo de investigação do Agente, como o intervalo JDBC, não foi vinculado ao intervalo do aplicativo, mesmo as chamadas JDBC foram feitas dentro do escopo do intervalo do aplicativo?

    A: Para que a sondagem do Agente crie um linkage de extensão, o intervalo do aplicativo deve ser ativado antes das chamadas JDBC.

  2. Por que os intervalos da sonda do Agente não estavam ligados aos intervalos do Helidon?

    A: Se os intervalos criados pelo Helidon não estiverem ativados, você poderá criar um novo intervalo e ativar com o pai SpanContext de ServerRequest. Depois disso, todos os intervalos da Sonda do Agente serão filhos do novo intervalo.

  3. Como o modo híbrido Agente funciona quando meu aplicativo incorporou o OpenTracing versão 0.32 enquanto o Agente do APM tem o OpenTracing versão 0.33?

    A: Nesses casos, você deve considerar a atualização do aplicativo para usar OpenTracing 0,33.

    Se isso não for possível, você poderá alterar as bibliotecas OpenTracing em oracle-apm-agent/install/<version>/lib/ext para 0.32. O Agente do APM é compatível com as versões 0.32 e 0.33 do OpenTracing.

  4. Por que o Agente APM e meu aplicativo criaram rastreamentos separados mediante solicitação após ativar o modo híbrido do Agente?

    R: Verifique as etapas de configuração e confirme se a propriedade foi definida corretamente. Para obter detalhes, consulte Ativar Modo Híbrido do Agente do APM.

    Se o problema persistir, talvez você precise copiar as bibliotecas OpenTracing para oracle-apm-agent/bootstrap.

  5. Posso usar o Modo Híbrido do Agente (1.3+) com aplicativo existente criado com Rastreador do APM (1.2 ou abaixo)?

    A: Não. O Agente do APM implantado e o Rastreador do APM usados para o build do aplicativo devem ser pelo menos 1,3.

  6. Por que o nome do serviço em AgentConfig.properties é usado para o rastreador com outra definição de nome de serviço quando o modo híbrido está ativado?

    R: No caso do modo híbrido, o Agente do APM inicia um rastreador e é registrado como rastreador global. Se um rastreador for iniciado pelo aplicativo ou pelo microsserviço, a instância do rastreador será, na verdade, a instância do rastreador global. Portanto, ele usa o mesmo nome de serviço conforme definido no arquivo AgentConfig.properties. Para usar um nome de serviço diferente para diferentes instâncias do agente, é necessário substituir o nome do serviço pela propriedade do sistema java ou pela variável de ambiente.

  7. Como substituir o nome do serviço no arquivo AgentConfig.properties?

    R: É possível substituir o nome do serviço definindo a propriedade do sistema java (com.oracle.apm.agent.service.name) ou a variável de ambiente (com_oracle_apm_agent_service_name).

  8. Como habilitar o modo híbrido Opentracing para aplicações Micronaut?
    1. Siga as instruções descritas acima em Configurar Modo Híbrido do Agente Java do APM.
    2. Adicione o rastreador Micronaut do APM no arquivo pom.xml do aplicativo como uma dependência. Consulte Usar o Rastreador do APM no Micronaut para obter detalhes.