Erfassen von Daten aus OpenTelemetry in Azure Data Explorer

OpenTelemetry (OTel) ist ein offenes Framework für Einblicke in Anwendungen. Die Instrumentierung wird von der Cloud Native Computing Foundation (CNCF) gehostet. Es stellt Standardschnittstellen für Observability-Daten bereit, einschließlich Metriken, Protokollen und Ablaufverfolgungen. Der OTel Collector umfasst drei Komponenten: Empfänger, die Daten in den Collector übertragen; Verarbeiter, die bestimmen, was mit den empfangenen Daten zu tun ist; und Exporteure, die die empfangenen Daten an ein Ziel senden.

Der Azure Data Explorer-Exporter unterstützt die Erfassung von Daten über viele Empfänger in Azure Data Explorer.

In diesem Artikel werden folgende Vorgehensweisen behandelt:

Voraussetzungen

• Ein Azure-Abonnement. Erstellen Sie ein kostenloses Azure-Konto.
• Ein Cluster und eine Datenbank. Erfahren Sie, wie Sie einen Azure Data Explorer-Cluster und eine Datenbank erstellen.

Erstellen Ihrer Umgebung

In diesem Abschnitt bereiten Sie Ihre Umgebung auf die Verwendung des OTel-Exporters vor.

Erstellen einer Microsoft Entra-App-Registrierung

Die Microsoft Entra-Anwendungsauthentifizierung ermöglicht Anwendungen den Zugriff auf Azure Data Explorer, ohne dass ein Benutzer anwesend ist. Um Daten mithilfe des OTel-Exporters aufzunehmen, erstellen und registrieren Sie einen Microsoft Entra-Dienstprinzipal, und autorisieren Sie diesen Prinzipal, Daten in eine Azure Data Explorer-Datenbank aufzunehmen.

1. Führen Sie auf Ihrem Azure Data Explorer-Cluster die Schritte 1 bis 7 unter Erstellen einer Microsoft Entra-Anwendungsregistrierung im Azure Data Explorer aus.
2. Speichern Sie die folgenden Werte für spätere Schritte:

Zuweisen der App-Berechtigung für Microsoft

1. Stellen Sie auf der Registerkarte „Abfrage“ der Webbenutzeroberfläche eine Verbindung mit Ihrem Cluster her. Informationen zum Herstellen einer Verbindung finden Sie unter Hinzufügen von Clustern.

2. Navigieren Sie zu der Datenbank, in der Sie Daten erfassen möchten.

3. Führen Sie den folgenden Verwaltungsbefehl aus, und ersetzen Sie die Platzhalter. Ersetzen Sie "DatabaseName" durch den Zieldatenbanknamen und " ApplicationID " durch den gespeicherten Wert.

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

   Hinweis

   Der letzte Parameter ist eine Zeichenfolge, die als Notizen angezeigt wird, wenn Sie die einer Datenbank zugeordneten Rollen abfragen. Weitere Informationen finden Sie unter Vorhandene Sicherheitsrollen anzeigen.

Erstellen von Zieltabellen

1. Navigieren Sie zur Azure Data Explorer-Webbenutzeroberfläche.

2. Wählen Sie im linken Menü Abfragen aus.

3. Erweitern Sie den Zielcluster im linken Bereich.

4. Wählen Sie die Zieldatenbank aus, um Ihren Abfragen den richtigen Kontext zu verleihen.

5. Führen Sie die folgenden Befehle aus, um Tabellen und Schemazuordnungen für die eingehenden Daten zu erstellen:

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

Einrichten der Streamingerfassung

Azure Data Explorer beinhaltet zwei Haupttypen der Erfassung: Batching und Streaming. Weitere Informationen finden Sie unter Batcherfassung und Streamingerfassung. Die Streamingmethode wird in der Azure Data Explorer-Exporterkonfiguration als verwaltet bezeichnet. Streaming-Ingestion kann eine gute Wahl sein, wenn Sie Protokolle und Ablaufverfolgungen in nahezu Echtzeit benötigen. Streamingerfassung nutzt jedoch mehr Ressourcen als Batcherfassung. Das OTel-Framework bündelt Daten, was Sie bei der Auswahl einer Erfassungsmethode berücksichtigen sollten.

Führen Sie den folgenden Befehl für alle drei Tabellen aus, um die Streamingerfassung zu aktivieren:

.alter table <Table-Name> policy streamingingestion enable

Konfigurieren des Azure Data Explorer-Exporters

Zum Erfassen Ihrer OpenTelemetry-Daten in Azure Data Explorer müssen Sie die OpenTelemetry-Verteilung mit der folgenden Azure Data Explorer-Exporterkonfiguration bereitstellen und ausführen.

1. Konfigurieren Sie den Azure Data Explorer-Exporter mithilfe der folgenden Felder:

   Feld	Beschreibung	Empfohlene Einstellung
   exporters	Typ des Exporters	Azure-Daten-Explorer
   cluster_uri	URI des Azure Data Explorer-Clusters, der die Datenbank und Tabellen enthält	https:// <Cluster>.kusto.windows.net
   application_id	Client-ID	<Anwendungs-ID>
   application_key	Geheimer Clientschlüssel	<Anwendungsschlüssel>
   tenant_id	Mandant	<Anwendungsmandant>
   db_name	Datenbank, die die Protokolle empfängt	oteldb oder eine andere Datenbank, die Sie erstellt haben.
   metrics_table_name	Die Zieltabelle in der Datenbank „db_name“, die exportierte Metrikdaten speichert	OTELMetrics
   logs_table_name	Die Zieltabelle in der Datenbank „db_name“, die exportierte Protokolldaten speichert	OTELLogs
   traces_table_name	Die Zieltabelle in der Datenbank „db_name“, die exportierte Ablaufverfolgungsdaten speichert	OTELTraces
   ingestion_type	Erfassungstyp: verwaltete Erfassung (Streaming) oder Batcherfassung	verwaltet
   metrics_table_json_mapping	Optionaler Parameter. Die Standardtabellenzuordnung wird während der Tabellenerstellung basierend auf OTel-Metrikattributen definiert. Die Standardzuordnung kann mithilfe dieses Parameters geändert werden.	<JSON-Zuordnung von metrics_table_name>
   logs_table_json_mapping	Optionaler Parameter. Die Standardtabellenzuordnung wird während der Tabellenerstellung basierend auf OTel-Protokollattributen definiert. Die Standardzuordnung kann mithilfe dieses Parameters geändert werden.	<JSON-Zuordnung von logs_table_name>
   traces_table_json_mapping	Optionaler Parameter. Die Standardtabellenzuordnung wird während der Tabellenerstellung basierend auf OTel-Ablaufverfolgungsattributen definiert. Die Standardzuordnung kann mithilfe dieses Parameters geändert werden.	<JSON-Zuordnung von traces_table_name>
   traces	Dienste: zu aktivierende Ablaufverfolgungskomponenten	Empfänger: [otlp] Prozessoren: [batch] Exporteure: [azuredataexplorer]
   metrics	Dienste: zu aktivierende Metrikkomponenten	Empfänger: [otlp] Prozessoren: [batch] Exporteure: [azuredataexplorer]
   logs	Dienste: zu aktivierende Protokollkomponenten	Empfänger: [otlp] Prozessoren: [batch] Exporter: [azuredataexplorer]

2. Verwenden Sie zum Ausführen des Azure Data Explorer-Exporters das Flag "--config".

Dies ist eine Beispielkonfiguration für den Azure Data Explorer-Exporter:

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

Sammeln von Daten mit einer Beispielanwendung

Nach dem Konfigurieren des Collectors müssen Sie nun Daten senden, die erfasst werden sollen. In diesem Beispiel Sie verwenden die Spring Pet Clinic-Beispielanwendung zusammen mit dem Java OTel Collector Agent.

1. Laden Sie den Collector-Agent hier herunter: OpenTelemetry-Collector-Agent.

2. Um OpenTelemetry für die Beispielanwendung zu aktivieren, legen Sie die folgenden Umgebungsvariablen fest. „open-telemetry-collector-host“ verweist auf den Host, auf dem der Azure Data Explorer-Exporter konfiguriert ist und ausgeführt wird.

   • Befehlszeile
   • 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"
   

3. Führen Sie die Beispielanwendung „spring-boot“ mit den folgenden Befehlszeilenargumenten aus:

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

Abfragen eingehender Daten

Nachdem die Beispiel-App ausgeführt wurde, wurden Ihre Daten in den definierten Tabellen in Azure Data Explorer erfasst. Diese Tabellen werden in einer Datenbank erstellt, die in der OTel-Sammelkonfiguration als oteldb definiert wurde. Die von Ihnen erstellten Tabellen werden in der OTel-Sammelkonfiguration definiert. In diesem Beispiel haben Sie drei Tabellen erstellt: OTELMetrics, OTELLogs und OTELTraces. In diesem Abschnitt fragen Sie jede Tabelle separat ab, um eine kleine Auswahl der verfügbaren Daten zu erhalten.

1. Navigieren Sie zur Azure Data Explorer-Webbenutzeroberfläche.

2. Wählen Sie im linken Menü Abfragen aus.

3. Erweitern Sie den Zielcluster im linken Bereich.

4. Wählen Sie die Datenbank oteldb aus, damit Ihre Abfragen im richtigen Kontext ausgeführt werden.

5. Kopieren Sie nacheinander die der folgenden Abfragen, und fügen Sie sie ein, um eine beliebige Anzahl von Zeilen aus jeder Tabelle anzuzeigen:

   • Metriken

     OTELMetrics
     |take 2
     

     Sie sollten Ergebnisse erhalten, die den Ergebnissen in der folgenden Tabelle ähneln, aber nicht mit ihnen identisch sind:

     Timestamp	MetricName	MetricType	MetricUnit	MetricDescription	MetricValue	Host	MetricAttributes	ResourceAttributes
     2022-07-01T12:55:33Z	http.server.active_requests	Sum	requests	Die Anzahl gleichzeitiger HTTP-Anforderungen, die derzeit aktiv sind	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	Histogramm	ms	Die Dauer der eingehenden HTTP-Anforderung (Summe der Stichproben)	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"}

   • Protokolle

     OTELLogs
     |take 2
     

     Sie sollten Ergebnisse erhalten, die den Ergebnissen in der folgenden Tabelle ähneln, aber nicht mit ihnen identisch sind:

     Timestamp	TraceId	SpanId	SeverityText	SeverityNumber	Text	ResourceAttributes	LogsAttributes
     2022-07-01T13:00:39Z			INFO	9	Starten der PetClinicApplication v2.7.0-SNAPSHOT mit Java 18.0.1.1 auf DESKTOP-SFS7RUQ mit PID 37280 (C:\Users\adxuser\Documents\Repos\spring-petclinic\target\spring-petclinic-2.7.0-SNAPSHOT.jar gestartet von 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	Kein aktiver Profilsatz, zurück auf 1 Standardprofil: "Standard"	{"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
     

     Sie sollten Ergebnisse erhalten, die den Ergebnissen in der folgenden Tabelle ähneln, aber nicht mit ihnen identisch sind:

     TraceId	SpanId	ParentId	SpanName	SpanStatus	SpanKind	StartTime	EndTime	ResourceAttributes	TraceAttributes	Ereignisse	Verknüpfungen
     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"}	[]	[]

Weitere Datenverarbeitung

Verwenden Sie Updaterichtlinien, um die gesammelten Daten gemäß Anwendungsbedarf weiter zu verarbeiten. Weitere Informationen finden Sie unter Übersicht über die Updaterichtlinie.

1. Im folgenden Beispiel werden Histogrammmetriken in eine histospezifische Tabelle mit Buckets und Aggregaten exportiert. Führen Sie den folgenden Befehl im Abfragebereich der Azure Data Explorer-Webbenutzeroberfläche aus:

   .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. Die folgenden Befehle erstellen eine Tabelle, die nur Anzahl- und Summenwerte des Histogrammmetriktyps enthält und eine Aktualisierungsrichtlinie anfügt. Führen Sie den folgenden Befehl im Abfragebereich der Azure Data Explorer-Webbenutzeroberfläche aus:

    .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
   

Zugehöriger Inhalt

• KQL-Kurzübersicht
• Kusto Query Language (KQL) – Übersicht