Documentation Oracle Cloud Infrastructure

Utilisation du traceur APM dans Helidon

Pour utiliser le traceur APM Tracer avec Helidon, procédez comme suit :

  1. Ajoutez le traceur APM à un projet Maven. Pour plus d'informations, reportez-vous à Ajout du traceur APM à un projet Maven.
  2. Vérifiez la version de Helidon et ajoutez la dépendance correspondante.

    Pour Helidon 2, ajoutez la dépendance suivante : 

    <dependency>
    <groupId>com.oracle.apm.agent.java</groupId>
    <artifactId>apm-java-agent-helidon</artifactId>
    <version>[1.0.1389,)</version>
</dependency>
    Pour Helidon 3 SE, ajoutez la dépendance suivante : 
    <dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-opentracing</artifactId>
</dependency>         
<dependency>
    <groupId>com.oracle.apm.agent.java</groupId>
    <artifactId>apm-java-agent-helidon3</artifactId>
    <version>[1.8.3326,)</version>
</dependency>
    Pour Helidon 3 MP, ajoutez la dépendance suivante : 
    <dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-opentracing</artifactId>
</dependency>         
<dependency> 
    <groupId>io.helidon.microprofile.tracing</groupId> 
    <artifactId>helidon-microprofile-tracing</artifactId> 
</dependency>
<dependency>
    <groupId>com.oracle.apm.agent.java</groupId>
    <artifactId>apm-java-agent-helidon3</artifactId>
    <version>[1.8.3326,)</version>
</dependency>
    Pour Helidon 4 SE, ajoutez la dépendance suivante : 
    <dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-opentracing</artifactId>
</dependency>
<dependency>
    <groupId>io.helidon.tracing.providers</groupId>
    <artifactId>helidon-tracing-providers-opentracing</artifactId>
</dependency>        
<dependency>
    <groupId>com.oracle.apm.agent.java</groupId>
    <artifactId>apm-java-agent-helidon4</artifactId>
    <version>[1.15.0.516,)</version>
</dependency>
    Remarque

    Pour Helidon 4, y compris Helidon 4 MP, reportez-vous à la section Opentelemetry Support for Helidon 4.

  3. Procédez à la configuration d'Helidon.

    Le traceur APM utilise les propriétés suivantes dans le fichier de configuration Helidon :

    Propriété Valeur par défaut Requis Description
    name   Non Nom du traceur. Cette propriété ne peut pas être NULL.
    service   Oui Nom du service. Cette propriété ne peut pas être NULL.
    private-data-key   Oui Clé de téléchargement de données APM requise pour la communication cloud du service Oracle APM.
    data-upload-endpoint   Oui Adresse de téléchargement de données APM requise pour la communication cloud du service Oracle APM.
    daemon-channel   Non Le canal de démon APM est une connexion de socket entre le traceur et le démon. Le format de cette valeur de propriété est <hôte>:<port>.

    Lorsque le démon est démarré avec cet ensemble de propriétés, il accepte la connexion de socket et écoute les données sur le canal indiqué.

    Lorsque le traceur est démarré avec cet ensemble, l'adresse de téléchargement de données est ignorée et les données sont uniquement envoyées au démon à l'aide de ce canal de socket.
    collecter-metrics True Non

    Collecte les mesures de serveur et génère des rapports vers le cloud du service OCI APM. La valeur par défaut est True.

    L'utilisateur peut accéder à toutes les mesures de serveur collectées à partir d'OCI Telemetry.
    collect-resources True Non

    Collecte les ressources de serveur et génère des rapports vers le cloud du service OCI APM.

    Toutes les ressources collectées sont utilisées en tant que dimensions pour la requête de données.
    log-directory apm-tracer-log dans le répertoire de travail de la JVM Non Chemin complet du répertoire de journaux dans lequel tous les journaux du traceur APM sont écrits. Si cette propriété n'est pas définie, le répertoire de journaux par défaut (apm-tracer-log) est créé dans le répertoire de travail de la JVM.
    tags   Non Balises statiques à inclure dans toutes les étendues de trace.
    properties   Non

    Autres propriétés du traceur APM. Cette méthode permet de définir des propriétés par programmation lors du démarrage du traceur APM.

    Les propriétés sont ignorées si la clé ou la valeur est NULL.
    Exemples :
    • Helidon SE : Vous devez le spécifier au format YAML. Le nom par défaut est application.yaml. Reportez-vous à l'exemple suivant : 
      tracing:
    service: "helidon-http"
    data-upload-endpoint: <data upload endpoint of your OCI domain>
    private-data-key: <privatedata key of your OCI domain>
    collect-metrics: true
    collect-resources: true
    log-directory: "/user/apm/log"
    tags:
        tag1: true
        tag2: 1234
        tag3: "hello"
    properties:
        com.oracle.apm.agent.logging.level: DEBUG
        com.oracle.apm.agent.key1: value123

      Le format préféré pour la section properties est utilisé ci-dessus. Le format suivant est également pris en charge : 

      tracing:
    ...
    ...
    ...
    properties:
        - key: com.oracle.apm.agent.logging.level
          value: DEBUG
        - key: com.oracle.apm.agent.key1
          value: value123
    • Helidon MP : vous devez le spécifier au format PROPERTIES (clé=valeur). Le nom par défaut est microprofile-config.properties. Reportez-vous à l'exemple suivant :
      tracing.service=my-helidon-service
tracing.data-upload-endpoint=<data upload endpoint of your OCI domain>
tracing.private-data-key=<private data key of your OCI domain>
tracing.collect-metrics=true
tracing.collect-resources=true
tracing.log-directory=/user/apm/log
tracing.tags.tag1=true
tracing.tags.tag2=1234
tracing.tags.tag3=hello
tracing.properties.com.oracle.apm.agent.data.upload.file=stdout
tracing.properties.com.oracle.apm.agent.json.pretty=true
      Le format ci-dessus est le format préféré pour la section properties, mais il prend également en charge le format suivant :
      tracing.service=my-helidon-service
...
...
...
tracing.properties.0.key=com.oracle.apm.agent.data.upload.file
tracing.properties.0.value=stdout
tracing.properties.1.key=com.oracle.apm.agent.json.pretty
tracing.properties.1.value=true
  4. Si vous avez Helidon MP, ignorez cette étape.

    Démarrez et configurez le traceur d'Helidon SE, comme l'application Main.java, en procédant comme suit : 

    Tracer tracer = TracerBuilder.create(Config.create()).build();

    Lorsque vous utilisez le code ci-dessus, vous vous assurez que le paramètre TracerBuilder est ajouté au projet Helidon. Vous créez un objet de configuration et utilisez le même objet de configuration pour créer un élément TracerBuilder dans Main.java.

    L'élément TracerBuilder démarre le traceur APM en tant que traceur d'opentracing et est inscrit dans l'élément opentracing GlobalTracer.

Prise en charge de l'opentelémétrie pour Helidon 4

Pour les applications Helidon 4, suivez les instructions répertoriées dans la section Activer OpenTelemetry dans l'agent APM de Configuration de l'agent Java APM pour l'utilisation de OpenTelemetry.

Remarque

La prise en charge d'Opentracing est en phase d'abandon pour Helidon 4 MP. Si vous devez configurer la prise en charge d'Opentelemetry, reportez-vous à Activation de OpenTelemetry dans l'agent APM dans Configuration de l'agent Java APM pour qu'il fonctionne avec OpenTelemetry.