Documentation Oracle Cloud Infrastructure

Configuration de l'agent Java APM pour qu'il fonctionne avec OpenTelemetry

L'agent Java APM peut être configuré pour fonctionner avec OpenTelemetry.

Vous pouvez continuer à utiliser l'instrumentation et la surveillance de l'agent Java APM et vous connecter à la surveillance OpenTelemetry existante.

Pour pouvoir utiliser des agents OpenTelemetry existants avec APM, reportez-vous à Configuration de OpenTelemetry et d'autres traceurs.

Remarque

OpenTelemetry L'instrumentation automatique d'agent Java (opentelemetry-javaagent.jar) n'est pas prise en charge. Cette fonctionnalité est destinée à fonctionner avec les applications/bibliothèques qui utilisent les API OpenTelemetry pour effectuer une instrumentation manuelle, en créant leurs propres étendues/traces (opentelemetry-api).

Une fois l'agent Java APM configuré, il fonctionne de la même manière que le mode hybride d'agent Java APM, sauf qu'il fonctionne également avec les API OpenTelemetry en plus des API OpenTracing.

Cette section couvre les rubriques suivantes :

Remarque

W3C La propagation des bagages est prise en charge à partir de la version 1.17 de l'agent Java APM.

Le scénario de rappel uniquement n'est pas disponible. Toutefois, lorsque l'agent Java APM est configuré pour fonctionner avec OpenTelemetry, sa valeur par défaut est ajustée en W3C, qui est le format utilisé par défaut par OpenTelemetry.

Activation de OpenTelemetry dans l'agent APM

L'agent Java APM prend en charge les mesures et les traces OpenTelemetry. Utilisez la propriété suivante pour activer OpenTelemetry pour l'instrumentation manuelle et les mesures personnalisées :

Type et description de propriété Propriétés Valeur par défaut Exemple

AgentConfig.properties

Mettez à jour le fichier AgentConfig.properties situé sous le répertoire oracle-apm-agent/config/<version>.

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

Propriétés système

Mettez à jour les propriétés système.

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

Variables d'environnement

Mettez à jour les variables d'environnement.

 com_oracle_apm_agent_otel False

Pour Windows : set com_oracle_apm_agent_otel=false

Pour Linux : export com_oracle_apm_agent_otel=false
Remarque

OpenTelemetry requiert Java 8 et versions ultérieures. La propriété com.oracle.apm.agent.otel=false est appliquée à Java 7 ou aux versions antérieures.

Au démarrage de l'agent Java APM, l'instance OpenTelemetry est démarrée. L'instance OpenTelemetry est accessible avec GlobalOpenTelemetry.get().

Utiliser d'autres versions de OpenTelemetry

L'agent Java APM 1.14 dispose de bibliothèques OpenTelemetry 1.38.0 intégrées. Etant donné que l'agent Java APM prend en charge l'instrumentation manuelle pour OpenTelemetry, la version d'API dont dépend votre projet peut être différente.

L'API des versions OpenTelemetry les plus récentes est normalement rétrocompatible avec les anciennes. Les utilisateurs peuvent remplacer l'agent Java APM OpenTelemetry 1.38.0 par une version plus récente. Pour utiliser une autre version de OpenTelemetry, procédez comme suit :
  1. Créez le répertoire opentelemetry dans le répertoire de base de l'agent. Par exemple : oracle-apm-agent/opentelemetry.
  2. Copiez les bibliothèques OpenTelemetry à utiliser dans le nouveau répertoire.

    Les bibliothèques doivent avoir l'ID d'artefact suivant et celles qui ne commencent pas par opentelemetry dépendent des bibliothèques d'opentelemetry.

    • opentélémétrie-api

    • opentélémétrie-api-incubateur

    • contexte d'opentélémétrie

    • opentélémétrie-exportateur-commun

    • opentélémétrie-exportateur-otlp

    • opentélémétrie-exportateur-otlp-commune

    • opentélémétrie-exportateur-expéditeur-okhttp

    • opentélémétrie-extension-trace-propagateurs

    • opentélémétrie-sdk

    • opentélémétrie-sdk-common

    • opentélémétrie-sdk-extension-autoconfiguration

    • opentelemetry-sdk-extension-autoconfigure-spi

    • journaux sdk-opentelemetry

    • opentélémétrie-sdk-métrie

    • opentélémétrie-sdk-trace

    • annotations
    • kotlin-stdlib
    • kotlin-stdlib-common
    • kotlin-stdlib-jdk7
    • kotlin-stdlib-jdk8

    • okhttp

    • okio-3.6.0.jarokio-jvm

    Remarque

    Les bibliothèques de versions OpenTelemetry différentes peuvent avoir des noms de bibliothèque différents.
  3. Utilisez la commande apm-java-agent-installer provision-agent-upgrade APM avec l'option -overwrite pour mettre à jour oracle-apm-agent/bootstrap/ApmAgent.jar.

    Cette étape est requise pour mettre à jour ApmAgent.jar afin d'utiliser des bibliothèques d'opentelemetry personnalisées. Par exemple : 

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

Paramètres de propagation

Les détails de la gestion du type de propagation de l'agent Java APM sont disponibles dans Configuration de OpenTelemetry et d'autres traceurs.

Par défaut, il utilise le format B3 (plusieurs en-têtes) pour gérer la propagation. Toutefois, lorsque l'agent Java APM est configuré pour fonctionner avec OpenTelemetry, cette valeur par défaut est ajustée sur W3C, qui est le format utilisé par défaut par OpenTelemetry.

Si vous décidez d'indiquer le paramètre com.oracle.apm.agent.tracer.propagation.type dans le fichier AgentConfig.properties, il remplace le comportement par défaut, ce qui vous permet d'utiliser le type de propagation de votre choix. Gardez à l'esprit que les éléments suivants doivent également être ajustés pour que tout se connecte et fonctionne ensemble :
  • OpenTelemetry update : OpenTelemetry possède sa propre propriété permettant de modifier les propagateurs utilisés.

    Vous pouvez utiliser la propriété système otel.propagators ou la variable d'environnement OTEL_PROPAGATORS pour mettre à jour les propagateurs. Pour plus d'informations sur les valeurs, reportez-vous à https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_propagators

    Remarque

    Pour modifier OpenTelemetry afin qu'il utilise le même format d'en-tête B3 que celui utilisé par l'agent Java APM par défaut, mettez à jour OpenTelemetry afin qu'il utilise le propagateur b3multi. Si vous utilisez B3SINGLE pour la propagation, mettez à jour OpenTelemetry pour utiliser le propagateur B3.

  • Mise à jour de l'agent de navigateur : si vous utilisez l'injection de l'agent de navigateur, vous devez mettre à jour le javascript pour utiliser un autre type de propagation. Par défaut, il utilise B3 (plusieurs en-têtes). Pour plus de détails, reportez-vous à Configuration de l'instrumentation des appels Ajax.