Documentazione di Oracle Cloud Infrastructure

Configura modalità ibrida agente Java APM

La modalità ibrida APM Java Agent, nota anche come modalità ibrida APM Agent, consente all'intervallo di prova dell'agente e all'intervallo dell'applicazione di formare un trace completo.

La modalità ibrida APM Agent combina sia la strumentazione bytecode che la strumentazione manuale OpenTracing/OpenTelemetry per fornire un quadro completo del flusso dell'applicazione.

Fornisce un meccanismo per assicurarsi che le librerie OpenTracing e OpenTelemetry siano caricate in un ClassLoader comune accessibile dall'agente APM e da tutta l'applicazione. Pertanto, gli intervalli possono essere creati nell'applicazione e sono collegati automaticamente agli intervalli creati dalla sonda agente APM.

Gli intervalli creati dalla sonda agente APM vengono collegati automaticamente a qualsiasi intervallo attivato.

Prerequisiti

  • L'agente APM è completamente operativo prima di abilitare la proprietà.
    Per OpenTelemetry, utilizzare la proprietà com.oracle.apm.agent.otel=true.
    Nota

    OpenTelemetry richiede Java 8 e versioni successive.
  • L'applicazione deve ottenere l'istanza di trace OpenTracing utilizzando GlobalTracer.get() oppure ottenere l'istanza OpenTelemetry con il metodo GlobalOpenTelemetry.get().
  • Stessa versione della libreria.

    Per OpenTracing, l'agente APM e l'applicazione utilizzano la stessa versione della libreria OpenTracing.

    Per OpenTelemetry, l'agente APM e l'applicazione utilizzano la stessa versione della libreria OpenTelemetry. Per i dettagli, vedere Configurare l'agente Java APM per l'utilizzo con OpenTelemetry.

Abilita modalità ibrida agente APM

La modalità ibrida agente APM è abilitata per impostazione predefinita.

Per disabilitarlo, utilizzare la proprietà: com.oracle.apm.agent.hybrid=false. Tuttavia, se la proprietà OpenTelemetry: com.oracle.apm.agent.otel=true è impostata, la modalità ibrida è sempre attiva.

Tipo e descrizione proprietà Proprietà Esempio

AgentConfig.properties

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

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

Proprietà di sistema

Aggiornare le proprietà di sistema.

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

Variabili di ambiente

Aggiornare le variabili di ambiente.

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

L'impostazione della proprietà è l'unico passo necessario per la maggior parte degli utenti e dei microservizi. Tuttavia, alcuni utenti possono avere logiche di caricamento delle classi e isolazioni di definizione delle classi diverse. Per assicurarsi che l'agente APM utilizzi la stessa definizione di classe OpenTracing e OpenTelemetry, potrebbe essere necessario eseguire il passo seguente aggiuntivo:

  • Copiare le librerie OpenTracing e OpenTelemetry dalla directory oracle-apm-agent/install/<version>/lib/ext nella directory oracle-apm-agent/bootstrap.

Il passo precedente garantisce che l'agente APM e tutte le applicazioni utilizzino le librerie OpenTracing e OpenTelemetry copiate, quindi le stesse definizioni di classe OpenTracing e OpenTelemetry.

Agente APM e librerie OpenTracing e OpenTelemetry: le librerie OpenTracing versione 0.33 e OpenTelemetry versione 1.38.0 sono incluse con l'agente APM. Se l'applicazione richiede l'uso di un'interfaccia API specifica OpenTracing versione 0.32, è possibile copiare le librerie OpenTracing 0.32 nella directory oracle-apm-agent/bootstrap. APM supporta sia la libreria OpenTracing 0.32 che la libreria 0.33. Per l'applicazione necessaria per utilizzare una versione diversa di OpenTelemetry, Configurare l'agente Java APM per utilizzare OpenTelemetry.

In generale, il passo aggiuntivo è necessario per quanto segue:

  • Quando le librerie OpenTracing sono incluse in modo esplicito nel classpath dei microservizi.

  • Quando appserver classloader non assegna la priorità al classloader padre. Ad esempio, Tomcat.

Domande frequenti

  1. Perché l'intervallo di prova dell'agente, ad esempio l'intervallo JDBC, non si è collegato all'intervallo di applicazione, anche le chiamate JDBC sono state effettuate nell'ambito dell'intervallo di applicazione?

    R: Affinché la sonda Agent crei un collegamento di intervallo, l'intervallo di applicazione deve essere attivato prima delle chiamate JDBC.

  2. Perché gli intervalli della sonda Agent non sono collegati agli intervalli Helidon?

    R: Se gli intervalli creati da Helidon non sono attivati, è possibile creare un nuovo intervallo e attivarlo con il padre SpanContext da ServerRequest. Successivamente, tutti gli intervalli della sonda agente saranno figli del nuovo intervallo.

  3. Come funziona la modalità ibrida agente quando l'applicazione ha incorporato OpenTracing versione 0.32 mentre l'agente APM dispone di OpenTracing versione 0.33?

    R: In questi casi, si consiglia di aggiornare l'applicazione per utilizzare OpenTracing 0.33.

    Se non è possibile, è possibile modificare le librerie OpenTracing in oracle-apm-agent/install/<version>/lib/ext impostandole su 0.32. L'agente APM è compatibile con entrambe le versioni OpenTracing 0.32 e 0.33.

  4. Perché l'agente APM e la mia applicazione hanno creato tracce separate su richiesta dopo aver abilitato la modalità ibrida agente?

    R: Controllare i passi di configurazione e verificare che la proprietà sia stata impostata correttamente. Per ulteriori informazioni, vedere Abilita modalità ibrida agente APM.

    Se il problema persiste, potrebbe essere necessario copiare le librerie OpenTracing in oracle-apm-agent/bootstrap.

  5. È possibile utilizzare la modalità ibrida dell'agente (1.3+) con l'applicazione esistente creata con APM Tracer (1.2 o versioni successive)?

    A: No. Sia l'agente APM distribuito che APM Tracer utilizzati per la build dell'applicazione devono essere almeno 1,3.

  6. Perché il nome del servizio in AgentConfig.properties viene utilizzato per il tracciante con un'impostazione del nome del servizio diversa quando è abilitata la modalità ibrida?

    R: Nel caso della modalità ibrida, APM Agent avvia un tracciante ed è registrato come tracciante globale. Se un tracciante viene avviato dall'applicazione o dal microservizio, l'istanza di tracciante è in realtà l'istanza di tracciante globale. Pertanto, utilizza lo stesso nome di servizio definito nel file AgentConfig.properties. Per utilizzare un nome di servizio diverso per istanze di agente diverse, è necessario sostituire il nome del servizio con la proprietà di sistema java o la variabile di ambiente.

  7. Come eseguire l'override del nome del servizio nel file AgentConfig.properties?

    R: È possibile sostituire il nome del servizio impostando la proprietà di sistema java (com.oracle.apm.agent.service.name) o la variabile di ambiente (com_oracle_apm_agent_service_name).

  8. Come abilitare la modalità ibrida Opentracing per le applicazioni Micronaut?
    1. Seguire le istruzioni descritte sopra nella sezione Configura modalità ibrida agente Java APM.
    2. Aggiungere il tracciatore APM Micronaut nel file applicazione pom.xml come dipendenza. Per ulteriori informazioni, vedere Usa APM Tracer in Micronaut.