Documentation sur Oracle Cloud Infrastructure

Configurer le mode hybride de l'agent Java APM

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

La fonction de mode hybride de l'agent APM combine à la fois l'instrumentation bytecode et l'instrumentation manuelle OpenTracing/OpenTelemetry pour fournir une image complète du flux d'application.

Il fournit un mécanisme pour 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 intervalles peuvent être créés dans l'application et ils sont liés automatiquement aux intervalles créés par la sonde de l'agent APM.

Les plages créées par la sonde Agent APM sont automatiquement liées à toute plage activée.

Préalables

  • 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.
    Note

    OpenTelemetry nécessite Java 8 et versions supé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, voir Configurer l'agent Java APM pour qu'il fonctionne avec OpenTelemetry.

Activer le mode hybride d'agent APM

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

Pour la 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 des propriétés Propriétés Exemple

AgentConfig.properties

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

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

Propriétés de système

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

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

Variables d'environnement

Mettre à 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 vous assurer que l'agent APM utilise la même définition de classe OpenTracing et OpenTelemetry, l'étape suivante supplémentaire peut être requise :

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

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

Agent APM et bibliothèques 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 de l'API spécifique à la version 0.32 de OpenTracing, 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 que l'application utilise une version différente de OpenTelemetry, configurez l'agent Java APM pour qu'il fonctionne avec OpenTelemetry.

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

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

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

Foire aux questions

  1. Pourquoi l'étendue de la sonde Agent telle que l'étendue JDBC n'a-t-elle pas été liée à l'étendue de l'application, même si 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 plage d'application doit être activée avant les appels JDBC.

  2. Pourquoi les portées de la sonde Agent n'étaient-elles pas liées aux portées Helidon ?

    R : Si les intervalles créés par Helidon ne sont pas activés, vous pouvez créer une nouvelle plage et l'activer avec le parent SpanContext à partir de ServerRequest. Après cela, toutes les plages de l'agent Probe seront enfants de la nouvelle plage.

  3. Comment fonctionne le mode hybride Agent lorsque mon application intègre OpenTracing version 0.32 alors que l'agent APM a OpenTracing version 0.33 ?

    R : Dans ces cas, vous devez envisager de mettre à jour l'application pour utiliser OpenTracing 0.33.

    If that's not possible, you can change the OpenTracing libraries in oracle-apm-agent/install/<version>/lib/ext to 0.32. The APM Agent is compatible with both OpenTracing versions 0.32 and 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 Agent ?

    R : Vérifiez les étapes de configuration et vérifiez que la propriété a été définie correctement. Pour plus de détails, voir Activer le mode hybride d'agent APM.

    If the problem persists, you may need to copy OpenTracing libraries to 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 ci-dessous)?

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

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

    R : Dans le cas du mode hybride, APM Agent démarre un traceur et il est enregistré en tant que traceur global. Si un traceur est démarré par l'application ou le micro-service, 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. Pour 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 du 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 de détails, voir Utiliser le traceur APM dans Micronaut.