Oracle Cloud Infrastructure-Dokumentation

APM-Java-Agent für die Arbeit mit OpenTelemetry konfigurieren

Der APM-Java-Agent kann für die Arbeit mit OpenTelemetry konfiguriert werden.

Sie können die Instrumentierung und Überwachung des APM-Java-Agent weiterhin verwenden und eine Verbindung mit der vorhandenen OpenTelemetry-Überwachung herstellen lassen.

Wenn Sie vorhandene OpenTelemetry-Agents mit APM verwenden möchten, finden Sie weitere Informationen unter OpenTelemetry und andere Tracer konfigurieren.

Hinweis

OpenTelemetry Automatische Java-Agent-Instrumentierung (opentelemetry-javaagent.jar) wird nicht unterstützt. Dieses Feature soll mit Anwendungen/Bibliotheken arbeiten, die mit den OpenTelemetry-APIs manuelle Instrumentierung ausführen und ihre eigenen Spans/Traces (opentelemetry-api) erstellen.

Nachdem der APM-Java-Agent konfiguriert wurde, funktioniert er ähnlich wie der APM-Java-Agent-Hybridmodus. Er funktioniert jedoch auch mit den OpenTelemetry-APIs neben den OpenTracing-APIs.

In diesem Abschnitt werden folgende Themen behandelt:

Hinweis

W3C Die Gepäckweitergabe wird ab Version 1.17 von APM Java Agent unterstützt.

Nur-Tracer-Szenario ist nicht verfügbar. Wenn der APM-Java-Agent jedoch so konfiguriert ist, dass er mit OpenTelemetry funktioniert, wird sein Standardwert an W3C angepasst. Dies ist das Format, das OpenTelemetry standardmäßig verwendet.

OpenTelemetry in APM-Agent aktivieren

Der APM-Java-Agent unterstützt OpenTelemetry-Traces und -Metriken. Verwenden Sie die folgende Eigenschaft, um OpenTelemetry für manuelle Instrumentierung und benutzerdefinierte Metriken zu aktivieren:

Eigenschaftstyp und Beschreibung Eigenschaften Standardwert Beispiel

AgentConfig.properties

Datei AgentConfig.properties im Verzeichnis oracle-apm-agent/config/<version> aktualisieren.

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

Systemeigenschaften

Systemeigenschaften aktualisieren.

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

Umgebungsvariablen

Umgebungsvariablen aktualisieren.

 com_oracle_apm_agent_otel false

Für Windows: set com_oracle_apm_agent_otel=false

Für Linux: export com_oracle_apm_agent_otel=false
Hinweis

Für OpenTelemetry ist Java 8 und höher erforderlich. Die Eigenschaft: com.oracle.apm.agent.otel=false wird für Java 7 oder höher durchgesetzt.

Beim Hochfahren des APM-Java-Agent wird die Instanz OpenTelemetry gestartet. Auf die Instanz OpenTelemetry kann mit GlobalOpenTelemetry.get() zugegriffen werden.

Andere OpenTelemetry-Versionen verwenden

Für den APM-Java-Agent 1.14 sind OpenTelemetry 1.38.0-Librarys integriert. Da der APM-Java-Agent die manuelle Instrumentierung für OpenTelemetry unterstützt, kann die API-Version, von der Ihr Projekt abhängt, unterschiedlich sein.

API neuerer OpenTelemetry-Versionen ist normalerweise abwärtskompatibel mit alten Versionen. Benutzer können das integrierte APM-Java-Agent OpenTelemetry 1.38.0 mit einer neueren Version außer Kraft setzen. Um eine andere OpenTelemetry-Version zu verwenden, gehen Sie wie folgt vor:
  1. Erstellen Sie das Verzeichnis opentelemetry im Agent-Home-Verzeichnis. Beispiel: oracle-apm-agent/opentelemetry.
  2. Kopieren Sie die OpenTelemetry-Bibliotheken, die im neuen Verzeichnis verwendet werden sollen.

    Bibliotheken müssen die folgende Artefakt-ID aufweisen. Bibliotheken, die nicht mit opentelemetry beginnen, sind abhängig von Librarys der Opentelemetrie.

    • Opentelemetrie-api

    • Opentelemetrie-API-Inkubator

    • opentelemetry-Kontext

    • opentelemetry-exporter-common

    • opentelemetry-exporter-otlp

    • opentelemetry-exporter-otlp-common

    • opentelemetry-exporter-sender-okhttp

    • Opentelemetrie-Extension-Trace-Propagatoren

    • opentelemetry-sdk

    • opentelemetry-sdk-common

    • opentelemetry-sdk-extension-autoconfigure

    • opentelemetry-sdk-extension-autoconfigure-spi

    • opentelemetry-sdk-logs

    • opentelemetry-sdk-metrics

    • opentelemetry-sdk-trace

    • Anmerkungen
    • kotlin-stdlib
    • kotlin-stdlib-common
    • kotlin-stdlib-jdk7
    • kotlin-stdlib-jdk8

    • okhttp

    • okio-3.6.0.jarokio-jvm

    Hinweis

    Librarys mit unterschiedlicher OpenTelemetry-Version können unterschiedliche Library-Namen aufweisen.
  3. Verwenden Sie den APM-Befehl apm-java-agent-installer provision-agent-upgrade mit der Option -overwrite, um oracle-apm-agent/bootstrap/ApmAgent.jar zu aktualisieren.

    Dieser Schritt ist erforderlich, um ApmAgent.jar so zu aktualisieren, dass benutzerdefinierte Opentelemetriebibliotheken verwendet werden. Beispiel: 

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

Propagierungseinstellungen

Die Details zur Propagierungstypbehandlung des APM-Java-Agent finden Sie unter OpenTelemetry und andere Tracer konfigurieren.

Standardmäßig verwendet es das Format B3 (Multi-Header), um die Propagierung zu verarbeiten. Wenn der APM-Java-Agent jedoch für die Arbeit mit OpenTelemetry konfiguriert ist, wird dieser Standardwert an W3C angepasst. Dies ist das Format, das OpenTelemetry standardmäßig verwendet.

Wenn Sie den Parameter com.oracle.apm.agent.tracer.propagation.type in der Datei AgentConfig.properties angeben, wird das Standardverhalten außer Kraft gesetzt, sodass Sie den gewünschten Propagierungstyp verwenden können. Denken Sie daran, dass auch Folgendes angepasst werden muss, um alles miteinander zu verbinden und zusammenzuarbeiten:
  • OpenTelemetry update: OpenTelemetry verfügt über eine eigene Eigenschaft zum Ändern der verwendeten Propagatoren.

    Sie können die Systemeigenschaft otel.propagators oder die Umgebungsvariable OTEL_PROPAGATORS verwenden, um die Propagatoren zu aktualisieren. Wertdetails finden Sie unter https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_propagators

    Hinweis

    Wenn Sie OpenTelemetry ändern möchten, um dasselbe B3-Headerformat zu verwenden, das der APM-Java-Agent standardmäßig verwendet, aktualisieren Sie OpenTelemetry, um den b3multi-Propagator zu verwenden. Wenn Sie B3SINGLE für die Propagierung verwenden, aktualisieren Sie OpenTelemetry, um den Propagator B3 zu verwenden.

  • Browser-Agent-Update: Wenn Sie Browser-Agent-Injection verwenden, müssen Sie javascript so aktualisieren, dass ein anderer Propagierungstyp verwendet wird. Standardmäßig wird B3 (Multi-Header) verwendet. Weitere Informationen finden Sie unter Ajax-Aufrufinstrumentierung konfigurieren.