Documentação do Oracle Cloud Infrastructure

Configurar o Agente Java do APM para Trabalhar com OpenTelemetry

O Agente Java do APM pode ser configurado para funcionar com OpenTelemetry.

Você pode continuar usando a instrumentação e o monitoramento do Agente Java do APM e fazer com que ele se conecte ao monitoramento OpenTelemetry existente.

Se quiser poder utilizar agentes OpenTelemetry existentes com o APM, consulte o seguinte: Configurar OpenTelemetry e Outros Rastreadores.

Observação

OpenTelemetry A instrumentação automática do agente Java (opentelemetry-javaagent.jar) não é suportada. Esse recurso destina-se a trabalhar com aplicativos/bibliotecas que estão usando as APIs OpenTelemetry para fazer instrumentação manual, criando seus próprios intervalos/rastreamentos (opentelemetry-api).

Depois que o agente Java do APM é configurado, ele funciona semelhante ao modo híbrido do agente Java do APM, com a exceção de que também funciona com as APIs OpenTelemetry junto com as APIs OpenTracing.

Esta seção abrange os seguintes tópicos:

Observação

W3C A propagação de bagagem é suportada a partir da versão 1.17 do agente Java do APM.

O cenário somente para rastreador não está disponível. No entanto, quando o agente Java do APM estiver configurado para funcionar com OpenTelemetry, seu valor padrão será ajustado para W3C, que é o formato que o OpenTelemetry usa por padrão.

Ativar OpenTelemetry no Agente do APM

O agente Java do APM suporta rastreamentos e métricas OpenTelemetry. Use a seguinte propriedade para ativar OpenTelemetry para instrumentação manual e métricas personalizadas:

Tipo e Descrição de Propriedades Propriedades Padrão Exemplo

AgentConfig.properties

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

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

Propriedades do Sistema

Atualiza as propriedades do sistema.

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

Variáveis de Ambiente

Atualiza as variáveis de ambiente.

 com_oracle_apm_agent_otel falso

Para Windows: set com_oracle_apm_agent_otel=false

Para Linux: export com_oracle_apm_agent_otel=false
Observação

OpenTelemetry requer o Java 8 e versões posteriores. A propriedade: com.oracle.apm.agent.otel=false é imposta no Java 7 ou abaixo.

Na inicialização do agente Java do APM, a instância OpenTelemetry é iniciada. A instância OpenTelemetry pode ser acessada com GlobalOpenTelemetry.get().

Usar outras versões do OpenTelemetry

O agente Java do APM 1.14 tem bibliotecas OpenTelemetry 1.38.0 incorporadas. Como o agente Java do APM suporta instrumentação manual para OpenTelemetry, a versão da API da qual seu projeto depende pode ser diferente.

A API de versões mais recentes do OpenTelemetry normalmente é compatível com versões antigas. Os usuários podem substituir o OpenTelemetry 1.38.0 incorporado do agente Java do APM pela versão mais recente. Para usar outra versão do OpenTelemetry, siga as etapas:
  1. Crie o diretório opentelemetry no diretório home do agente. Por exemplo: oracle-apm-agent/opentelemetry.
  2. Copie as bibliotecas OpenTelemetry a serem usadas no novo diretório.

    As bibliotecas devem ter o seguinte id de artefato, e as que não começam com opentelemetry dependem de bibliotecas de opentelemetry.

    • opentelemetria-api

    • opentelemetria-api-incubadora

    • contexto da opentelemetria

    • opentelemetry-exporter-comum

    • opentelemetry-exporter-otlp

    • opentelemetry-exporter-otlp-common

    • opentelemetry-exporter-sender-okhttp

    • opentelemetria-extensão-traço-propagadores

    • opentelemetria-sdk

    • opentelemetry-sdk-common

    • opentelemetry-sdk-extension-autoconfigure

    • opentelemetry-sdk-extension-autoconfigure-spi

    • opentelemetry-sdk-logs

    • opentelemetry-sdk-metrics

    • opentelemetry-sdk-trace

    • anotações
    • kotlin-stdlib
    • kotlin-stdlib-comum
    • kotlin-stdlib-jdk7
    • kotlin-stdlib-jdk8

    • okhttp

    • okio-3.6.0.jarokio-jvm

    Observação

    As bibliotecas de outra versão do OpenTelemetry podem ter nomes de biblioteca diferentes.
  3. Use o comando apm-java-agent-installer provision-agent-upgrade do APM com a opção -overwrite para atualizar oracle-apm-agent/bootstrap/ApmAgent.jar.

    Esta etapa é necessária para atualizar ApmAgent.jar para usar bibliotecas de opentelemetria personalizadas. Por exemplo: 

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

Definições de Propagação

Os detalhes do tratamento do tipo de propagação do agente Java do APM podem ser vistos em Configurar OpenTelemetry e Outros Rastreadores.

Por padrão, ele usa o formato B3 (multicabeçalho) para tratar a propagação. No entanto, quando o agente Java do APM estiver configurado para funcionar com OpenTelemetry, esse valor padrão será ajustado para W3C, que é o formato que OpenTelemetry usa por padrão.

Se você decidir especificar o parâmetro: com.oracle.apm.agent.tracer.propagation.type no arquivo AgentConfig.properties, ele substituirá o comportamento padrão, permitindo que você use o tipo de propagação que preferir. Tenha em mente que o seguinte também precisa ser ajustado para ter tudo se conectando e trabalhando juntos:
  • Atualização OpenTelemetry: OpenTelemetry tem sua própria propriedade para alterar quais propagadores são usados.

    Você pode usar a propriedade do sistema: otel.propagators ou a variável de ambiente: OTEL_PROPAGATORS para atualizar os propagadores. Para obter detalhes do valor, consulte https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_propagators

    Observação

    Se você quiser alterar OpenTelemetry para usar o mesmo formato de cabeçalhos B3 que o agente Java do APM usa por padrão, atualize OpenTelemetry para usar o propagador b3multi. Se você estiver usando B3SINGLE para propagação, atualize OpenTelemetry para usar o propagador B3.

  • Atualização do Agente do Browser: Se você estiver usando a injeção do Agente do Browser, será necessário atualizar o javascript para usar outro tipo de propagação. Por padrão, ele usa B3 (multicabeçalho). Para obter detalhes, consulte Configurar Instrumentação de Chamadas Ajax.