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

Article
07/23/2024

Important

Ce connecteur peut être utilisé dans Real-Time Intelligence dans Microsoft Fabric. Utilisez les instructions contenues dans cet article, à l’exception des points suivants :

Si nécessaire, créez des bases de données en suivant les instructions fournies dans Créer une base de données KQL.
Si nécessaire, créez des tables en suivant les instructions fournies dans Créer une table vide.
Obtenez les URI de requête ou d’ingestion en suivant les instructions fournies dans Copier l’URI.
Exécutez des requêtes dans un ensemble de requêtes KQL.

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

Les paramètres de configuration sont résumés dans la documentation du fichier readme (lisezmoi).
Pour le code source de l’exportateur, consultez Exportateur Azure Data Explorer.

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

Un abonnement Azure. Créer un compte Azure gratuit
Un cluster et une base de données : Démarrage rapide : Créer un cluster et une base de données Azure Data Explorer

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.

À 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.
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

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.
Accédez à la base de données dans laquelle vous souhaitez ingérer des données.
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

Accédez à Interface utilisateur web Azure Data Explorer.
Sélectionnez Interroger dans le menu de gauche.
Développez le cluster cible dans le volet gauche.
Sélectionnez la base de données cible pour donner à vos requêtes le contexte approprié.

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.

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]

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.

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

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.

Ligne de commande
Bash

$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"

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

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.

Accédez à Interface utilisateur web Azure Data Explorer.
Sélectionnez Interroger dans le menu de gauche.
Développez le cluster cible dans le volet gauche.
Sélectionnez la base de données oteldb pour donner à vos requêtes le contexte approprié.

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.

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}]'

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

Partager via

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

Prérequis

Paramétrer votre environnement

Créer une inscription d’application Microsoft Entra

Accordez les autorisations d’application Microsoft Entra

Créer des tables cibles

Configurer l’ingestion en streaming

Configurer l’exportateur Azure Data Explorer

Collecter des données avec un exemple d’application

Interroger les données entrantes

Traitement supplémentaire des données

Commentaires

Ressources supplémentaires

Partager via

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

Prérequis

Paramétrer votre environnement

Créer une inscription d’application Microsoft Entra

Accordez les autorisations d’application Microsoft Entra

Créer des tables cibles

Configurer l’ingestion en streaming

Configurer l’exportateur Azure Data Explorer

Collecter des données avec un exemple d’application

Interroger les données entrantes

Traitement supplémentaire des données

Contenu connexe

Commentaires

Ressources supplémentaires