Partager via

Ingérer des données d’OpenTelemetry dans Azure Data Explorer

  • Article

Important

Ce connecteur peut être utilisé dans Real-Time Intelligence dans Microsoft Fabric. Utilisez les instructions contenues dans cet article avec les exceptions suivantes :

OpenTelemetry (OTel) est une infrastructure ouverte pour l’observabilité des applications. L’instrumentation est hébergée par la CNCF (Cloud Native Computing Foundation), qui fournit des interfaces standard pour les données d’observabilité, notamment les métriques, les journaux et les traces. Le collecteur OTel est constitué des trois composants suivants : les récepteurs se chargent de mettre les données dans le collecteur, les processeurs déterminent ce qu’il faut faire avec les données reçues et les exportateurs sont responsables de la destination des données reçues.

L’exportateur Azure Data Explorer prend en charge l’ingestion de données à partir de nombreux récepteurs dans Azure Data Explorer.

Remarque

Dans cet article, vous apprendrez comment :

  • Paramétrer votre environnement
  • Configurer l’exportateur Azure Data Explorer
  • Exécuter l’exemple d’application
  • Interroger les données entrantes

Prérequis

Paramétrer votre environnement

Dans cette section, vous allez préparer votre environnement pour utiliser l’exportateur OTel.

Créer une inscription d’application Microsoft Entra

L’authentification des applications Microsoft Entra est utilisée pour les applications qui doivent accéder à Azure Data Explorer sans la présence d’un utilisateur. Pour ingérer des données à l’aide de l’exportateur OTel, vous devez créer et enregistrer un principal de service Microsoft Entra, puis autoriser ce principal à ingérer les données d’une base de données Azure Data Explorer.

  1. À l’aide de votre cluster Azure Data Explorer, suivez les étapes 1 à 7 dans Créer une inscription d’application Microsoft Entra dans Azure Data Explorer.
  2. Enregistrez les valeurs suivantes à utiliser dans des étapes ultérieures :
    • ID d’application (client)
    • ID de l’annuaire (locataire)
    • Valeur de la clé du secret client

Accordez les autorisations d’application Microsoft Entra

  1. Sous l’onglet Requête de l’interface utilisateur web, connectez-vous à votre cluster. Pour plus d’informations sur le mode de connexion, consultez Ajouter des clusters.

  2. Accédez à la base de données dans laquelle vous souhaitez ingérer des données.

  3. Exécutez la commande de gestion suivante en remplaçant les espaces réservés. Remplacez DatabaseName par le nom de la base de données cible et ApplicationID par la valeur précédemment enregistrée. Cette commande accorde à l’application le rôle d’ingestion de base de données. Pour en savoir plus, consultez Gérer les rôles de sécurité de bases de données.

    .add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'Azure Data Explorer App Registration'

    Remarque

    Le dernier paramètre est une chaîne qui s’affiche sous la forme de notes lorsque vous interrogez les rôles associés à une base de données. Pour plus d’informations, voir Afficher les rôles de sécurité existants.

Créer des tables cibles

  1. Accédez à Interface utilisateur web Azure Data Explorer.

  2. Sélectionnez Interroger dans le menu de gauche.

  3. Développez le cluster cible dans le volet gauche.

  4. Sélectionnez la base de données cible pour donner à vos requêtes le contexte approprié.

  5. Exécutez les commandes suivantes pour créer des tables et un mappage de schéma pour les données entrantes :

    .create-merge table <Logs-Table-Name> (Timestamp:datetime, ObservedTimestamp:datetime, TraceID:string, SpanID:string, SeverityText:string, SeverityNumber:int, Body:string, ResourceAttributes:dynamic, LogsAttributes:dynamic) 

.create-merge table <Metrics-Table-Name> (Timestamp:datetime, MetricName:string, MetricType:string, MetricUnit:string, MetricDescription:string, MetricValue:real, Host:string, ResourceAttributes:dynamic,MetricAttributes:dynamic) 

.create-merge table <Traces-Table-Name> (TraceID:string, SpanID:string, ParentID:string, SpanName:string, SpanStatus:string, SpanKind:string, StartTime:datetime, EndTime:datetime, ResourceAttributes:dynamic, TraceAttributes:dynamic, Events:dynamic, Links:dynamic)

Configurer l’ingestion en streaming

Azure Data Explorer a deux types principaux d’ingestion : par lots et streaming. Pour plus d’informations, consultez Ingestion par lots et de streaming. La méthode de streaming est appelée managée dans la configuration de l’exportateur Azure Data Explorer. L’ingestion de streaming peut être un bon choix pour vous si vous avez besoin que les journaux et les traces soient disponibles en quasi temps réel. Cependant, l’ingestion de streaming utilise plus de ressources que l’ingestion par lots. Le framework OTel traite les données par lots elle-même, ce qui doit être pris en compte lors du choix de la méthode à utiliser pour l’ingestion.

Remarque

L’ingestion de streaming doit être activée sur le cluster Azure Data Explorer pour activer l’option managed. Vous pouvez vérifier si le streaming est activé en utilisant la commande .show database streaming ingestion policy.

Exécutez la commande suivante pour chacune des trois tables afin d’activer l’ingestion de streaming :

.alter table <Table-Name> policy streamingingestion enable

Configurer l’exportateur Azure Data Explorer

Pour ingérer vos données OpenTelemetry dans Azure Data Explorer, vous devez déployer et exécuter la distribution OpenTelemetry avec la configuration de l’exportateur Azure Data Explorer suivante.

  1. Configurez l’exportateur Azure Data Explorer en utilisant les champs suivants :

    Champ Description Paramétrage suggéré
    Exportateurs Type d’exportateur Explorateur de données Azure
    cluster_uri URI du cluster Azure Data Explorer qui détient la base de données et les tables https:// <cluster>.kusto.windows.net
    application_id ID client >ID de l’application<
    application_key Clè secrète client <Clé de l’application>
    tenant_id Client <Locataire de l’application>
    db_name Base de données qui reçoit les journaux oteldb ou une autre base de données que vous avez déjà créée
    metrics_table_name Table cible dans la base de données db_name qui stocke les données de métrique exportées. OTELMetrics
    logs_table_name Table cible dans la base de données db_name qui stocke les données de journal exportées. OTELLogs
    traces_table_name Table cible dans la base de données db_name qui stocke les données des traces exportées. OTELTraces
    ingestion_type Type d’ingestion : managée (streaming) ou par lots managed
    metrics_table_json_mapping Paramètre facultatif. Le mappage des tables par défaut est défini lors de la création des tables en fonction des attributs des métriques OTeL. Le mappage par défaut peut être modifié en utilisant ce paramètre. <mappage de metrics_table_name JSON>
    logs_table_json_mapping Paramètre facultatif. Le mappage des tables par défaut est défini lors de la création des tables en fonction des attributs des journaux OTeL. Le mappage par défaut peut être modifié en utilisant ce paramètre. <mappage de logs_table_name JSON>
    traces_table_json_mapping Paramètre facultatif. Le mappage des tables par défaut est défini lors de la création des tables en fonction des attributs des traces OTeL. Le mappage par défaut peut être modifié en utilisant ce paramètre. <mappage de traces_table_name JSON>
    traces Services : composants de traces à activer récepteurs : [otlp]
    processeurs : [batch]
    exportateurs : [azuredataexplorer]
    Mesures Services : composants de métriques à activer récepteurs : [otlp]
    processeurs : [batch]
    exportateurs : [azuredataexplorer]
    logs Services : composants de journaux à activer récepteurs : [otlp]
    processeurs : [batch]
    exportateurs : [ azuredataexplorer]

  2. Utilisez l’indicateur « --config » pour exécuter l’exportateur Azure Data Explorer.

Voici un exemple de configuration pour l’exportateur Azure Data Explorer :

---
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
processors:
  batch:
exporters:
  azuredataexplorer:
    cluster_uri: "https://<cluster>.kusto.windows.net"
    application_id: "<application id>"
    application_key: "<application key>"
    tenant_id: "<application tenant>"
    db_name: "oteldb"
    metrics_table_name: "OTELMetrics"
    logs_table_name: "OTELLogs"
    traces_table_name: "OTELTraces"
    ingestion_type : "managed"
    metrics_table_json_mapping : "<json metrics_table_name mapping>"
    logs_table_json_mapping  : "<json logs_table_name mapping>"
    traces_table_json_mapping  : "<json traces_table_name mapping>"
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [azuredataexplorer]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [azuredataexplorer]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [azuredataexplorer]

Collecter des données avec un exemple d’application

Maintenant que le collecteur est configuré, vous devez envoyer des données à ingérer. Dans cet exemple, Vous utilisez l’exemple d’application spring pet clinic avec l’agent collecteur OTeL Java.

  1. Téléchargez l’agent collecteur ici : Agent collecteur de télémétrie Open.

  2. Pour activer Open Telemetry pour l’exemple d’application, définissez les variables d’environnement suivantes. open-telemetry-collector-host fait référence à l’hôte où l’exportateur Azure Data Explorer est configuré et en cours d’exécution.

    $env:OTEL_SERVICE_NAME="pet-clinic-service"
$env:OTEL_TRACES_EXPORTER="otlp"
$env:OTEL_LOGS_EXPORTER="otlp "                   
$env:OTEL_EXPORTER_OTLP_ENDPOINT="http://<open-telemetry-collector-host>:4317"

  3. Exécutez l’exemple d’application spring-boot avec les arguments de ligne de commande suivants :

    java -javaagent:./opentelemetry-javaagent.jar -jar spring-petclinic-<version>-SNAPSHOT.jar

Interroger les données entrantes

Une fois que l’exemple d’application a été exécuté, vos données ont été ingérées dans les tables définies dans Azure Data Explorer. Ces tables ont été créées dans une base de données qui a été définie dans la configuration du collecteur OTel, nommée oteldb. Les tables que vous avez créées ont été définies dans la configuration du collecteur OTel. Dans cet exemple, vous avez créé trois tables : OTELMetrics, OTELLogs et OTELTraces. Dans cette section, vous allez interroger chaque table séparément pour obtenir une petite sélection des données disponibles.

  1. Accédez à Interface utilisateur web Azure Data Explorer.

  2. Sélectionnez Interroger dans le menu de gauche.

  3. Développez le cluster cible dans le volet gauche.

  4. Sélectionnez la base de données oteldb pour donner à vos requêtes le contexte approprié.

  5. Copiez/collez les requêtes suivantes de façon séquentielle pour voir un nombre arbitraire de lignes de chaque table :

    • Métriques

      OTELMetrics
|take 2

      Vous devriez obtenir des résultats similaires, mais pas exactement identiques à ceux de la table suivante :

      Timestamp MetricName MetricType MetricUnit MetricDescription MetricValue Hôte MetricAttributes ResourceAttributes
      2022-07-01T12:55:33Z http.server.active_requests Sum requests Nombre de requêtes HTTP simultanées en cours d’exécution 0 DESKTOP-SFS7RUQ {"http.flavor":"1.1", "http.host":"localhost:8080", "scope.name":"io.opentelemetry.tomcat-7.0", "scope.version":"1.14.0-alpha", "http.method":"GET", "http.scheme":"http"} {"host.name":"DESKTOP-SFS7RUQ", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "host.arch":"amd64", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.auto.version":"1.14.0", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":5980, "service.name":"my-service", "telemetry.sdk.version":"1.14.0"}
      2022-07-01T12:55:33Z http.server.duration_sum Histogramme ms Durée de la requête HTTP entrante (somme du total des exemples) 114.9881 DESKTOP-SFS7RUQ {"http.flavor":"1.1", "http.host":"localhost:8080", "scope.name":"io.opentelemetry.tomcat-7.0", "scope.version":"1.14.0-alpha", "http.method":"GET", "http.scheme":"http", "http.route":"/owners/find", "http.status_code":200} {"host.name":"DESKTOP-SFS7RUQ", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "host.arch":"amd64", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.auto.version":"1.14.0", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":5980, "service.name":"my-service", "telemetry.sdk.version":"1.14.0"}

    • Journaux d’activité

      OTELLogs
|take 2

      Vous devriez obtenir des résultats similaires, mais pas exactement identiques à ceux de la table suivante :

      Timestamp TraceId SpanId SeverityText SeverityNumber Corps ResourceAttributes LogsAttributes
      2022-07-01T13:00:39Z INFO 9 Starting PetClinicApplication v2.7.0-SNAPSHOT using Java 18.0.1.1 on DESKTOP-SFS7RUQ with PID 37280 (C:\Users\adxuser\Documents\Repos\spring-petclinic\target\spring-petclinic-2.7.0-SNAPSHOT.jar started by adxuser in C:\Users\adxuser\Documents\Repos\spring-petclinic) {"host.name":"DESKTOP-SFS7RUQ", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":37280, "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "telemetry.sdk.version":"1.14.0", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "os.description":"Windows 11 10.0", "service.name":"my-service", "telemetry.auto.version":"1.14.0", "host.arch":"amd64"} {"scope.name":"org.springframework.samples.petclinic.PetClinicApplication"}
      2022-07-01T13:00:39Z INFO 9 No active profile set, falling back to 1 default profile: "default" {"host.name":"DESKTOP-SFS7RUQ", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.pid":37280, "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.name":"opentelemetry", "os.type":"windows", "process.runtime.version":"18.0.1.1+2-6", "telemetry.sdk.language":"java", "telemetry.sdk.version":"1.14.0", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "os.description":"Windows 11 10.0", "service.name":"my-service", "telemetry.auto.version":"1.14.0", "host.arch":"amd64"} {"scope.name":"org.springframework.samples.petclinic.PetClinicApplication"}

    • Traces

      OTELTraces
|take 2

      Vous devriez obtenir des résultats similaires, mais pas exactement identiques à ceux de la table suivante :

      TraceId SpanId ParentId SpanName SpanStatus SpanKind StartTime EndTime ResourceAttributes TraceAttributes Événements Liens
      573c0e4e002a9f7281f6d63eafe4ef87 dab70d0ba8902c5e 87d003d6-02c1-4f3d-8972-683243c35642 STATUS_CODE_UNSET SPAN_KIND_CLIENT 2022-07-01T13:17:59Z 2022-07-01T13:17:59Z {"telemetry.auto.version":"1.14.0", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "service.name":"my-service", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.language":"java", "telemetry.sdk.name":"opentelemetry", "host.arch":"amd64", "host.name":"DESKTOP-SFS7RUQ", "process.pid":34316, "process.runtime.version":"18.0.1.1+2-6", "os.type":"windows", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "telemetry.sdk.version":"1.14.0"} {"db.user":"sa", "thread.id":1, "db.name":"87d003d6-02c1-4f3d-8972-683243c35642", "thread.name":"main", "db.system":"h2", "scope.name":"io.opentelemetry.jdbc", "scope.version":"1.14.0-alpha", "db.connection_string":"h2:mem:", "db.statement":"DROP TABLE vet_specialties IF EXISTS"} [] []
      84a9a8c4009d91476da02dfa40746c13 3cd4c0e91717969a 87d003d6-02c1-4f3d-8972-683243c35642 STATUS_CODE_UNSET SPAN_KIND_CLIENT 2022-07-01T13:17:59Z 2022-07-01T13:17:59Z {"telemetry.auto.version":"1.14.0", "os.description":"Windows 11 10.0", "process.executable.path":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe", "process.runtime.description":"Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 18.0.1.1+2-6", "service.name":"my-service", "process.runtime.name":"Java(TM) SE Runtime Environment", "telemetry.sdk.language":"java", "telemetry.sdk.name":"opentelemetry", "host.arch":"amd64", "host.name":"DESKTOP-SFS7RUQ", "process.pid":34316, "process.runtime.version":"18.0.1.1+2-6", "os.type":"windows", "process.command_line":"C:\Program Files\Java\jdk-18.0.1.1;bin;java.exe -javaagent:./opentelemetry-javaagent.jar", "telemetry.sdk.version":"1.14.0"} {"db.user":"sa", "thread.id":1, "db.name":"87d003d6-02c1-4f3d-8972-683243c35642", "thread.name":"main", "db.system":"h2", "scope.name":"io.opentelemetry.jdbc", "scope.version":"1.14.0-alpha", "db.connection_string":"h2:mem:", "db.statement":"DROP TABLE vets IF EXISTS"} [] []

Traitement supplémentaire des données

En utilisant des stratégies de mise à jour, les données collectées peuvent être traitées plus avant en fonction des besoins de l’application. Pour plus d’informations, consultez Vue d’ensemble des stratégies de mise à jour.

  1. L’exemple suivant exporte les métriques d’histogramme vers une table histo-specific avec des compartiments et des agrégats. Exécutez la commande suivante dans le volet de requête de l’interface utilisateur web d’Azure Data Explorer :

    .create table HistoBucketData (Timestamp: datetime, MetricName: string , MetricType: string , Value: double, LE: double, Host: string , ResourceAttributes: dynamic, MetricAttributes: dynamic )

.create function 
with ( docstring = "Histo bucket processing function", folder = "UpdatePolicyFunctions") ExtractHistoColumns()
{
    OTELMetrics
    | where MetricType == 'Histogram' and MetricName has "_bucket"
    | extend f=parse_json(MetricAttributes)
    | extend le=todouble(f.le)
    | extend M_name=replace_string(MetricName, '_bucket','')
    | project Timestamp, MetricName=M_name, MetricType, MetricValue, LE=le, Host, ResourceAttributes, MetricAttributes
}

.alter table HistoBucketData policy update 
@'[{ "IsEnabled": true, "Source": "OTELMetrics","Query": "ExtractHistoColumns()", "IsTransactional": false, "PropagateIngestionProperties": false}]'

  2. Les commandes suivantes créent une table qui contient seulement le nombre et la somme des valeurs du type de métrique Histogramme et attache une stratégie de mise à jour. Exécutez la commande suivante dans le volet de requête de l’interface utilisateur web d’Azure Data Explorer :

     .create table HistoData (Timestamp: datetime, MetricName: string , MetricType: string , Count: double, Sum: double, Host: string , ResourceAttributes: dynamic, MetricAttributes: dynamic)

 .create function 
with ( docstring = "Histo sum count processing function", folder = "UpdatePolicyFunctions") ExtractHistoCountColumns()
{
   OTELMetrics
    | where MetricType =='Histogram'
    | where MetricName has "_count"
    | extend Count=MetricValue
    | extend M_name=replace_string(MetricName, '_bucket','')
    | join kind=inner (OTELMetrics
    | where MetricType =='Histogram'
    | where MetricName has "_sum"
    | project Sum = MetricValue , Timestamp)
 on Timestamp | project Timestamp, MetricName=M_name, MetricType, Count, Sum, Host, ResourceAttributes, MetricAttributes
}

.alter table HistoData policy update 
@'[{ "IsEnabled": true, "Source": "RawMetricsData","Query": "ExtractHistoCountColumns()", "IsTransactional": false, "PropagateInge

Contenu connexe