Documentation sur Oracle Cloud Infrastructure

Configurer 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, voir : Configurer OpenTelemetry et d'autres traceurs.

Note

L'instrumentation automatique de l'agent Java OpenTelemetry (opentelemetry-javaagent.jar) n'est pas prise en charge. Cette fonction est conçue pour fonctionner avec les applications/bibliothèques qui utilisent les API OpenTelemetry pour effectuer une instrumentation manuelle, en créant leurs propres intervalles/traces (opentelemetry-api).

Une fois l'agent Java APM configuré, il fonctionne comme le mode hybride d'agent Java APM, sauf qu'il fonctionne également avec les API OpenTelemetry et les API OpenTracing.

Cette section traite des sujets suivants :

Note

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

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

Activer OpenTelemetry dans l'agent APM

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

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

AgentConfig.properties

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

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

Propriétés de système

Mettre à jour les propriétés du système.

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

Variables d'environnement

Mettre à 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
Note

OpenTelemetry nécessite Java 8 et versions supérieures. La propriété : com.oracle.apm.agent.otel=false est appliquée sur Java 7 ou ci-dessous.

Au démarrage de l'agent Java APM, l'instance OpenTelemetry est démarrée. Vous pouvez accéder à l'instance OpenTelemetry avec GlobalOpenTelemetry.get().

Utiliser d'autres versions de OpenTelemetry

L'agent Java APM 1.14 comporte des bibliothèques OpenTelemetry 1.38.0 intégrées. Comme 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 nouvelles versions de OpenTelemetry est normalement rétrocompatible avec les anciennes. Les utilisateurs peuvent remplacer l'agent Java APM intégré 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 artefact suivant, et celles qui ne commencent pas par opentelemetry dépendent des bibliothèques de l'opentelemetry.

    • opentelémétrie-api

    • opentelémétrie-api-incubateur

    • contexte d'opentelemetry

    • opentelémétrie-exportateur-commune

    • opentelémétrie-exportateur-otlp

    • opentelémétrie-exportateur-otlp-commune

    • opentelémétrie-exportateur-expéditeur-okhttp

    • opentelémétrie-extension-trace-propagateurs

    • opentelémétrie-sdk

    • opentelemetry-sdk-common

    • opentelemetry-sdk-extension-autoconfigure

    • opentelemetry-sdk-extension-autoconfigure-spi

    • opentelemetry-sdk-logs

    • opentelemetry-sdk-metrics

    • opentelémétrie-sdk-trace

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

    • okhttp

    • okio-3.6.0.jarokio-jvm

    Note

    Les bibliothèques de différentes versions de OpenTelemetry 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 du traitement du type de propagation de l'agent Java APM sont visibles dans Configurer OpenTelemetry et d'autres traceurs.

Par défaut, il utilise le format B3 (en-têtes multiples) 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 à W3C, qui est le format utilisé par défaut par OpenTelemetry.

Si vous décidez de spécifier le paramètre : com.oracle.apm.agent.tracer.propagation.type dans le fichier AgentConfig.properties, le comportement par défaut sera remplacé, ce qui vous permettra d'utiliser le type de propagation que vous préférez. Gardez à l'esprit que les éléments suivants doivent également être ajustés afin d'avoir tout connecter et travailler ensemble :
  • Mise à jour OpenTelemetry : OpenTelemetry a sa propre propriété pour modifier les propagateurs utilisés.

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

    Note

    Si vous voulez modifier OpenTelemetry pour utiliser le même format d'en-tête B3 que celui utilisé par l'agent Java APM par défaut, mettez à jour OpenTelemetry pour utiliser 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 type de propagation différent. Par défaut, il utilise B3 (en-têtes multiples). Pour plus de détails, voir Configurer l'instrumentation d'appels Ajax.