Freigeben über

Erfassen von Daten aus OpenTelemetry in Azure Data Explorer

  • Artikel

Wichtig

Dieser Connector kann in Echtzeitintelligenz in Microsoft Fabric verwendet werden. Verwenden Sie die Anweisungen in diesem Artikel mit den folgenden Ausnahmen:

OpenTelemetry (OTel) ist ein offenes Framework für Einblicke in Anwendungen. Die Instrumentierung wird von der CNCF (Cloud Native Computing Foundation) gehostet, die Standardschnittstellen für Einblicksdaten bereitstellt, u. a. Metriken, Protokolle und Ablaufverfolgungen. Der OTel-Collector besteht aus den folgenden drei Komponenten: Empfänger befassen sich mit dem Abrufen von Daten in den Collector, Prozessoren bestimmen, wie die empfangenen Daten verwendet werden, und Exporter sind dafür verantwortlich, wohin die empfangenen Daten gesendet werden sollen.

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

Hinweis

In diesem Artikel werden folgende Vorgehensweisen behandelt:

  • Erstellen Ihrer Umgebung
  • Konfigurieren des Azure Data Explorer-Exporters
  • Ausführen der Beispielanwendung
  • Abfragen eingehender Daten

Voraussetzungen

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 wird für Anwendungen verwendet, die ohne benutzerseitigen Eingriff auf Azure Data Explorer zugreifen müssen. Um Daten mithilfe des OTel-Exporters zu erfassen, müssen Sie einen Microsoft Entra-Dienstprinzipal erstellen und registrieren und dann diesen Prinzipal zum Erfassen von Daten in einer Azure Data Explorer-Datenbank autorisieren.

  1. Führen Sie mit Ihrem Azure Data Explorer-Cluster die Schritte 1 bis 7 unter Erstellen einer Microsoft Entra-Anwendungsregistrierung in Azure Data Explorer aus.
  2. Speichern Sie die folgenden Werte, die in späteren Schritten verwendet werden sollen:
    • Anwendungs-ID (Client)
    • Verzeichnis-ID (Mandant)
    • Wert des geheimen Clientschlüssels

Zuweisen der App-Berechtigung für Microsoft

  1. Stellen Sie auf der Registerkarte „Abfrage“ der Webbenutzeroberfläche eine Verbindung mit Ihrem Cluster her. Weitere 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 Namen der Zieldatenbank und ApplicationID durch den zuvor gespeicherten Wert. Dieser Befehl gewährt der App die Rolle Datenbankingestor. Weitere Informationen finden Sie unter Verwalten von Sicherheitsrollen der Datenbank.

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

  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. Streamingerfassung kann eine gute Wahl für Sie sein, wenn die Protokolle und Ablaufverfolgungen nahezu in Echtzeit zur Verfügung stehen müssen. Streamingerfassung nutzt jedoch mehr Ressourcen als Batcherfassung. Das OTel-Framework selbst fasst Daten in Batches zusammen. Dies sollte beim Auswählen der für die Erfassung zu verwendenden Methode berücksichtigt werden.

Hinweis

Streamingerfassung muss für den Azure Data Explorer-Cluster aktiviert werden, damit die Option managed aktiviert werden kann. Sie können mithilfe des Befehls .show database streaming ingestion policy überprüfen, ob das Streaming aktiviert ist.

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 bereits erstellte Datenbank
    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]
    Exporter: [azuredataexplorer]
    metrics Dienste: zu aktivierende Metrikkomponenten Empfänger: [otlp]
    Prozessoren: [batch]
    Exporter: [azuredataexplorer]
    logs Dienste: zu aktivierende Protokollkomponenten Empfänger: [otlp]
    Prozessoren: [batch]
    Exporter: [azuredataexplorer]

  2. Verwenden Sie das Flag „--config“, um den Azure Data Explorer-Exporter auszuführen.

Im Folgenden sehen Sie 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 Verwenden Sie die Beispielanwendung Spring PetClinic 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.

    $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 wurden in einer Datenbank erstellt, die in der Konfiguration des OTel-Collectors als oteldb definiert wurde. Die von Ihnen erstellten Tabellen wurden in der Konfiguration des OTel-Collectors 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 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

      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

Mithilfe von Updaterichtlinien können die gesammelten Daten je nach Anwendungsbedarf weiter verarbeitet werden. 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