Documentazione di Oracle Cloud Infrastructure

Configurare l'agente Java APM per l'utilizzo di OpenTelemetry

È possibile configurare l'agente Java APM per l'utilizzo con OpenTelemetry.

È possibile continuare a utilizzare la strumentazione e il monitoraggio dell'agente Java APM e far sì che si connetta al monitoraggio OpenTelemetry esistente.

Se si desidera utilizzare gli agenti OpenTelemetry esistenti con APM, vedere quanto segue: Configurare OpenTelemetry e altri trace.

Nota

OpenTelemetry La strumentazione automatica dell'agente Java (opentelemetry-javaagent.jar) non è supportata. Questa funzione è pensata per funzionare con applicazioni/librerie che utilizzano le API OpenTelemetry per eseguire la strumentazione manuale, creando intervalli/tracce personalizzati (opentelemetry-api).

Una volta configurato, l'agente Java APM funziona in modo simile alla modalità ibrida agente Java APM, ma funziona anche con le API OpenTelemetry insieme alle API OpenTracing.

In questa sezione vengono trattati i seguenti argomenti:

Nota

W3C La propagazione dei bagagli è supportata a partire dalla release 1.17 dell'agente Java APM.

Scenario solo Tracer non disponibile. Tuttavia, quando l'agente Java APM è configurato per funzionare con OpenTelemetry, il valore predefinito verrà modificato in W3C, ovvero il formato utilizzato per impostazione predefinita da OpenTelemetry.

Abilita OpenTelemetry nell'agente APM

L'agente Java APM supporta i trace e le metriche OpenTelemetry. Utilizzare la proprietà seguente per abilitare OpenTelemetry per la strumentazione manuale e le metriche personalizzate:

Tipo e descrizione proprietà Proprietà Valore predefinito Esempio

AgentConfig.properties

Aggiornare il file AgentConfig.properties situato nella directory oracle-apm-agent/config/<version>.

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

Proprietà di sistema

Aggiornare le proprietà di sistema.

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

Variabili di ambiente

Aggiornare le variabili di ambiente.

 com_oracle_apm_agent_otel false

Per Windows: set com_oracle_apm_agent_otel=false

Per Linux: export com_oracle_apm_agent_otel=false
Nota

OpenTelemetry richiede Java 8 e versioni successive. La proprietà com.oracle.apm.agent.otel=false viene applicata su Java 7 o in basso.

All'avvio dell'agente Java APM, viene avviata l'istanza OpenTelemetry. È possibile accedere all'istanza OpenTelemetry con GlobalOpenTelemetry.get().

Utilizzare altre versioni di OpenTelemetry

L'agente Java APM 1.14 dispone di librerie OpenTelemetry 1.38.0 incorporate. Poiché l'agente Java APM supporta la strumentazione manuale per OpenTelemetry, la versione API da cui dipende il progetto potrebbe essere diversa.

Le API delle versioni OpenTelemetry più recenti sono in genere compatibili con quelle precedenti. Gli utenti possono eseguire l'override dell'agente Java APM OpenTelemetry 1.38.0 con la versione più recente. Per utilizzare un'altra versione di OpenTelemetry, attenersi alla procedura riportata di seguito.
  1. Creare la directory opentelemetry nella directory home dell'agente. Ad esempio: oracle-apm-agent/opentelemetry.
  2. Copiare le librerie OpenTelemetry da utilizzare nella nuova directory.

    Le librerie devono avere il seguente ID artifact e quelle che non iniziano con l'opentelemetria dipendono dalle librerie di opentelemetria.

    • opentelemetria-api

    • opentelemetria-api-incubatrice

    • opentelemetria-contesto

    • opentelemetria-esportatore-comune

    • opentelemetria-esportatore-otlp

    • opentelemetria-esportatore-otlp-comune

    • opentelemetria-esportatore-mittente-okhttp

    • opentelemetria-estensione-traccia-propagatori

    • opentelemetria-sdk

    • opentelemetria-sdk-comune

    • opentelemetria-sdk-estensione-autoconfigurazione

    • opentelemetria-sdk-estensione-autoconfigurazione-spi

    • opentelemetria-sdk-log

    • opentelemetria-sdk-metrica

    • opentelemetria-sdk-trace

    • annotazioni
    • kotlin-stdlib
    • kotlin-stdlib-comune
    • kotlin-stdlib-jdk7
    • kotlin-stdlib-jdk8

    • okhttp

    • okio-3.6.0.jarokio-jvm

    Nota

    Le librerie di versioni OpenTelemetry diverse possono avere nomi di libreria diversi.
  3. Utilizzare il comando apm-java-agent-installer provision-agent-upgrade APM con l'opzione -overwrite per aggiornare oracle-apm-agent/bootstrap/ApmAgent.jar.

    Questo passo è necessario per aggiornare ApmAgent.jar in modo da utilizzare librerie opentelemetry personalizzate. Ad esempio: 

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

Impostazioni propagazione

I dettagli della gestione del tipo di propagazione dell'agente Java APM sono disponibili in Configura OpenTelemetry e altri trace.

Per impostazione predefinita, utilizza il formato B3 (multiintestazione) per gestire la propagazione. Tuttavia, quando l'agente Java APM è configurato per funzionare con OpenTelemetry, questo valore predefinito verrà modificato in W3C, ovvero il formato utilizzato da OpenTelemetry per impostazione predefinita.

Se si decide di specificare il parametro com.oracle.apm.agent.tracer.propagation.type nel file AgentConfig.properties, verrà eseguito l'override del funzionamento predefinito, consentendo di utilizzare il tipo di propagazione desiderato. Tieni presente che anche quanto segue deve essere regolato per avere tutto ciò che si collega e lavora insieme:
  • OpenTelemetry update: OpenTelemetry dispone di una propria proprietà per modificare i propagatori utilizzati.

    Per aggiornare i propagatori, è possibile utilizzare la proprietà di sistema otel.propagators o la variabile di ambiente OTEL_PROPAGATORS. Per ulteriori informazioni sui valori, vedere https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_propagators

    Nota

    Se si desidera modificare OpenTelemetry per utilizzare lo stesso formato di intestazioni B3 utilizzato dall'agente Java APM per impostazione predefinita, aggiornare OpenTelemetry per utilizzare il propagatore b3multi. Se si utilizza B3SINGLE per la propagazione, aggiornare OpenTelemetry per utilizzare il propagatore B3.

  • Aggiornamento agente browser: se si utilizza l'iniezione agente browser, è necessario aggiornare il javascript per utilizzare un tipo di propagazione diverso. Per impostazione predefinita, utilizza B3 (multi-header). Per i dettagli, vedere Configura strumentazione chiamate Ajax.