Documentation Oracle Cloud Infrastructure

Configurer le mode hybride d'agent Java APM

Le mode hybride d'agent Java APM, également appelé mode hybride d'agent APM, permet à l'étendue de la sonde d'agent et à l'étendue de l'application de former une trace complète.

La fonction de mode hybride Agent APM combine l'instrumentation par code exécutable et l'instrumentation manuelle OpenTracing/OpenTelemetry pour fournir une image complète du flux d'application.

Elle fournit un mécanisme permettant de s'assurer que les bibliothèques OpenTracing et OpenTelemetry sont chargées dans un fichier ClassLoader commun accessible à partir de l'agent APM et de toute l'application. Par conséquent, les étendues peuvent être créées dans l'application et elles sont automatiquement liées aux étendues créées par la sonde d'agent APM.

Les étendues créées par la sonde de l'agent APM sont automatiquement liées à toute étendue activée.

Prérequis

  • L'agent APM est entièrement fonctionnel avant d'activer la propriété.
    Pour OpenTelemetry, utilisez la propriété com.oracle.apm.agent.otel=true.
    Remarque

    OpenTelemetry requiert Java 8 et versions ultérieures.
  • L'application doit obtenir l'instance de traceur OpenTracing à l'aide de GlobalTracer.get() ou obtenir l'instance OpenTelemetry avec la méthode GlobalOpenTelemetry.get().
  • Même version de bibliothèque.

    Pour OpenTracing, l'agent APM et l'application utilisent la même version de bibliothèque OpenTracing.

    Pour OpenTelemetry, l'agent APM et l'application utilisent la même version de bibliothèque OpenTelemetry. Pour plus de détails, reportez-vous à Configuration de l'agent Java APM pour qu'il fonctionne avec OpenTelemetry.

Activer le mode hybride de l'agent APM

Le mode hybride de l'agent APM est activé par défaut.

Pour le désactiver, utilisez la propriété : com.oracle.apm.agent.hybrid=false. Toutefois, si la propriété OpenTelemetry com.oracle.apm.agent.otel=true est définie, le mode hybride est toujours activé.

Type et description de propriété Propriétés Exemple

AgentConfig.properties

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

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

Propriétés système

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

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

Variables d'environnement

Mettez à jour les variables d'environnement.

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

La définition de la propriété est la seule étape requise pour la plupart des serveurs d'applications et des microservices. Toutefois, certains serveurs d'applications peuvent avoir des logiques de chargement de classe et des isolations de définition de classe différentes. Pour garantir que l'agent APM utilise la même définition de classe OpenTracing et OpenTelemetry, l'étape supplémentaire suivante peut être requise :

  • Copiez les bibliothèques OpenTracing et OpenTelemetry du répertoire oracle-apm-agent/install/<version>/lib/ext vers le répertoire oracle-apm-agent/bootstrap.

L'étape ci-dessus garantit que l'agent APM et toutes les applications utiliseront les bibliothèques OpenTracing et OpenTelemetry copiées, d'où les mêmes définitions de classe OpenTracing et OpenTelemetry.

Bibliothèques d'agent APM et OpenTracing et OpenTelemetry : les bibliothèques OpenTracing version 0.33 et OpenTelemetry version 1.38.0 sont incluses avec l'agent APM. Si l'application nécessite l'utilisation d'une API spécifique à OpenTracing version 0.32, il est possible de copier les bibliothèques OpenTracing 0.32 dans le répertoire oracle-apm-agent/bootstrap. APM prend en charge les bibliothèques OpenTracing 0.32 et 0.33. Pour l'application devant utiliser une autre version de OpenTelemetry, Configurez l'agent Java APM pour qu'il fonctionne avec OpenTelemetry.

En général, l'étape supplémentaire est requise pour les éléments suivants :

  • Lorsque les bibliothèques OpenTracing sont explicitement incluses dans la variable d'environnement classpath des microservices.

  • Lorsque le chargeur de classe du serveur d'applications n'affecte pas de priorité au chargeur de classe parent. Par exemple, Tomcat.

Foire aux questions

  1. Pourquoi l'étendue de la sonde de l'agent telle que JDBC n'a-t-elle pas été liée à l'étendue de l'application, même les appels JDBC ont été effectués dans l'étendue de l'application ?

    R : pour que la sonde Agent crée une liaison d'étendue, la portée de l'application doit être activée avant les appels JDBC.

  2. Pourquoi les extensions de sonde d'agent n'étaient-elles pas liées aux étendues Helidon ?

    R : si les étendues créées par Helidon ne sont pas activées, vous pouvez créer une étendue et l'activer avec le parent SpanContext à partir de ServerRequest. Ensuite, toutes les étendues de la sonde d'agent seront des enfants de la nouvelle étendue.

  3. Comment le mode hybride d'agent fonctionne-t-il lorsque mon application a intégré OpenTracing version 0.32 alors que l'agent APM dispose de OpenTracing version 0.33 ?

    R : Dans ce cas, vous devez envisager de mettre à jour l'application pour qu'elle utilise OpenTracing 0.33.

    Si cela n'est pas possible, vous pouvez remplacer les bibliothèques OpenTracing dans oracle-apm-agent/install/<version>/lib/ext par 0.32. L'agent APM est compatible avec les versions OpenTracing 0.32 et 0.33.

  4. Pourquoi l'agent APM et mon application ont-ils créé des traces distinctes sur demande après l'activation du mode hybride de l'agent ?

    R : Vérifiez les étapes de configuration et confirmez que la propriété a été correctement définie. Pour plus de détails, reportez-vous à Activation du mode hybride de l'agent APM.

    Si le problème persiste, vous devrez peut-être copier les bibliothèques OpenTracing vers oracle-apm-agent/bootstrap.

  5. Puis-je utiliser le mode hybride de l'agent (1.3+) avec une application existante créée avec le traceur APM (1.2 ou inférieur) ?

    R : Non. L'agent APM déployé et le traceur APM utilisés pour la création d'application doivent être au moins de 1.3.

  6. Pourquoi le nom de service dans AgentConfig.properties est-il utilisé pour le traceur avec un paramètre de nom de service différent lorsque le mode hybride est activé ?

    R : Dans le cas du mode hybride, l'agent APM démarre un traceur et il est enregistré en tant que traceur global. Si un traceur est démarré par l'application ou le service micro, l'instance de traceur est en fait l'instance de traceur globale. Par conséquent, il utilise le même nom de service que celui défini dans le fichier AgentConfig.properties. Afin d'utiliser un nom de service différent pour différentes instances d'agent, il faut remplacer le nom de service par la propriété système java ou la variable d'environnement.

  7. Comment remplacer le nom de service dans le fichier AgentConfig.properties ?

    R : Vous pouvez remplacer le nom du service en définissant la propriété système java (com.oracle.apm.agent.service.name) ou la variable d'environnement (com_oracle_apm_agent_service_name).

  8. Comment activer le mode hybride Opentracing pour les applications Micronaut ?
    1. Suivez les instructions décrites ci-dessus sous Configurer le mode hybride de l'agent Java APM.
    2. Ajoutez le traceur APM Micronaut dans le fichier d'application pom.xml en tant que dépendance. Pour plus d'informations, reportez-vous à la section Use APM Tracer in Micronaut.