Freigeben über

Erfassen von Daten aus Telegraf 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:

Azure Data Explorer unterstützt die Datenerfassung aus Telegraf. Telegraf ist ein leicht, minimaler Open Source-Speicherfußdruck-Agent zum Sammeln, Verarbeiten und Schreiben von Telemetriedaten, einschließlich Protokollen, Metriken und IoT-Daten. Telegraf unterstützt Hunderte von Eingabe- und Ausgabe-Plugins. Es wird von der Open Source Community häufig verwendet und gut unterstützt. Das Azure Data Explorer Ausgabe-Plug-In dient als Connector von Telegraf und unterstützt die Aufnahme von Daten aus vielen Arten von Eingabe-Plugins in Azure Data Explorer.

Voraussetzungen

  • Ein Azure-Abonnement. Erstellen Sie ein kostenloses Azure-Konto.
  • Schnellstart: Erstellen eines Azure Data Explorer-Clusters und einer Datenbank. Erstellen eines Clusters und einer Datenbank
  • Telegraf. Hosten Sie Telegraf auf einer VM oder einem Container. Telegraf kann lokal gehostet werden, wo die überwachte App oder der Dienst bereitgestellt wird, oder remote auf einem dedizierten Überwachungs-Compute/Container.

Unterstützte Authentifizierungsmethoden

Das Plugin unterstützt die folgenden Authentifizierungsmethoden:

  • Microsoft Entra-Anwendungen mit App-Schlüsseln oder Zertifikaten.

  • Microsoft Entra-Benutzertoken

    • Ermöglicht dem Plug-In die Authentifizierung wie ein Benutzer. Wir empfehlen nur die Verwendung dieser Methode für Entwicklungszwecke.

  • Token für verwaltete Dienstidentität (Managed Service Identity, MSI) in Azure

    • Dies ist die bevorzugte Authentifizierungsmethode, wenn Sie Telegraf in einer unterstützenden Azure-Umgebung ausführen, z. B. Azure Virtual Machines.

Je nachdem, welche Methode Sie verwenden, muss dem angegebenen Prinzipal die Rolle Datenbankbenutzer in Azure Data Explorer zugewiesen werden. Mit dieser Rolle kann das Plug-In die Tabellen erstellen, die für die Aufnahme von Daten erforderlich sind. Wenn das Plug-In mit create_tables=false konfiguriert ist, muss der angegebene Prinzipal mindestens über die Rolle Datenbankingestor verfügen.

Methode zum Konfigurieren der Authentifizierung

Das Plug-In sucht nach bestimmten Konfigurationen von Umgebungsvariablen, um zu bestimmen, welche Authentifizierungsmethode verwendet werden soll. Die Konfigurationen werden in der angegebenen Reihenfolge bewertet, und die erste Konfiguration, die erkannt wurde, wird verwendet. Wenn eine gültige Konfiguration nicht erkannt wird, schlägt die Authentifizierung mit dem Plug-In fehl.

Um die Authentifizierung für das Plug-In zu konfigurieren, legen Sie die entsprechenden Umgebungsvariablen für Ihre ausgewählte Authentifizierungsmethode fest:

  • Clientanmeldeinformationen (Microsoft Entra-Anwendungstoken): Microsoft Entra-Anwendungs-ID und Geheimnis.

    • AZURE_TENANT_ID: Die für die Authentifizierung verwendete Microsoft Entra-Mandanten-ID.
    • AZURE_CLIENT_ID: Die Client-ID einer App-Registrierung im Mandanten.
    • AZURE_CLIENT_SECRET: Ein Clientgeheimnis, das für die App-Registrierung generiert wurde.

  • Clientzertifikat (Microsoft Entra-Anwendungstoken): Microsoft Entra-Anwendungs-ID und ein X.509-Zertifikat.

    • AZURE_TENANT_ID: Die für die Authentifizierung verwendete Microsoft Entra-Mandanten-ID.
    • AZURE_CERTIFICATE_PATH: Ein Pfad zum Zertifikat und zum privaten Schlüsselpaar im PEM- oder PFX-Format für die Authentifizierung der App-Registrierung
    • AZURE_CERTIFICATE_PASSWORD: Das Kennwort, das für das Zertifikat festgelegt wurde.

  • Kennwort des Ressourcenbesitzers (Microsoft Entra-Benutzertoken):Microsoft Entra-Benutzer und -Kennwort. Die Verwendung dieses Gewährungstyps wird nicht empfohlen. Wenn Sie eine interaktive Anmeldung benötigen, verwenden Sie die Geräteanmeldung.

    • AZURE_TENANT_ID: Die für die Authentifizierung verwendete Microsoft Entra-Mandanten-ID.
    • AZURE_CLIENT_ID: Die Client-ID einer App-Registrierung im Mandanten.
    • AZURE_USERNAME: Der Benutzername, der auch als UPN bezeichnet wird, eines Microsoft Entra-Benutzerkontos.
    • AZURE_PASSWORD: Das Kennwort des Microsoft Entra-Benutzerkontos. Beachten Sie, dass Konten mit aktivierter MFA nicht unterstützt werden.

  • Azure Managed Service Identity: Delegieren der Anmeldeinformationenverwaltung an die Plattform. Diese Methode erfordert, dass Code in Azure ausgeführt wird, z. B. VM. Alle Konfigurationen werden von Azure behandelt. Weitere Informationen finden Sie unter Verwaltete Azure-Dienstidentität. Diese Methode ist nur bei Verwendung von Azure Resource Manager verfügbar.

Telegraf konfigurieren

Telergraf ist ein konfigurationsgesteuerter Agent. Um zu beginnen, müssen Sie Telegraf installieren und die erforderlichen Eingabe- und Ausgabe-Plug-Ins konfigurieren. Der Standardspeicherort der Konfigurationsdatei lautet wie folgt:

  • Für Windows: C:\Programme\Telegraf\telegraf.conf
  • Für Linux: etc/telegraf/telegraf.conf

Um das Azure Data Explorer Ausgabe-Plug-In zu aktivieren, müssen Sie den folgenden Abschnitt in der automatisch generierten Konfigurationsdatei aufheben:

[[outputs.azure_data_explorer]]
  ## The URI property of the Azure Data Explorer resource on Azure
  ## ex: https://myadxresource.australiasoutheast.kusto.windows.net
  # endpoint_url = ""

  ## The Azure Data Explorer database that the metrics will be ingested into.
  ## The plugin will NOT generate this database automatically, it's expected that this database already exists before ingestion.
  ## ex: "exampledatabase"
  # database = ""

  ## Timeout for Azure Data Explorer operations, default value is 20 seconds
  # timeout = "20s"

  ## Type of metrics grouping used when ingesting to Azure Data Explorer
  ## Default value is "TablePerMetric" which means there will be one table for each metric
  # metrics_grouping_type = "TablePerMetric"

  ## Name of the single table to store all the metrics (Only needed if metrics_grouping_type is "SingleTable").
  # table_name = ""

  ## Creates tables and relevant mapping if set to true(default).
  ## Skips table and mapping creation if set to false, this is useful for running telegraf with the least possible access permissions i.e. table ingestor role.
  # create_tables = true

Unterstützte Erfassungstypen

Das Plug-In unterstützt verwaltete Erfassung (Streamingerfassung) und Erfassung aus der Warteschlange (Batcherfassung). Der Standardtyp ist Erfassung aus der Warteschlange.

Wichtig

Um verwaltete Erfassung zu verwenden, müssen Sie die Streamingerfassung in Ihrem Cluster aktivieren.

Um den Erfassungstyp für das Plug-In zu konfigurieren, ändern Sie die automatisch generierte Konfigurationsdatei wie folgt:

  ##  Ingestion method to use.
  ##  Available options are
  ##    - managed  --  streaming ingestion with fallback to batched ingestion or the "queued" method below
  ##    - queued   --  queue up metrics data and process sequentially
  # ingestion_type = "queued"

Erfasste Daten abfragen

Nachfolgend sehen Sie Beispiele für Daten, die mithilfe der SQL- und Syslog-Eingabe-Plug-Ins zusammen mit dem Azure Data Explorer Ausgabe-Plug-In gesammelt werden. Für jede Eingabemethode gibt es ein Beispiel für die Verwendung von Datentransformationen und Abfragen in Azure Data Explorer.

SQL Eingabe-Plug-In

In der folgenden Tabelle sind Beispielmetriken aufgeführt, die von SQL Eingabe-Plug-In gesammelt werden:

name Tags Zeitstempel felder
sqlserver_database_io {"database_name":"azure-sql-db2","file_type":"DATA","host":"adx-vm","logical_filename":"tempdev","measurement_db_type":"AzureSQLDB","physical_filename":"tempdb.mdf","replica_updateability":"READ_WRITE","sql_instance":"adx-sql-server"} 2021-09-09T13:51:20Z {"current_size_mb":16,"database_id":2,"file_id":1,"read_bytes":2965504,"read_latency_ms":68,"reads":47,"rg_read_stall_ms":42,"rg_write_stall_ms":0,"space_used_mb":0,"write_bytes":1220608,"write_latency_ms":103,"writes":149}
sqlserver_waitstats {"database_name":"azure-sql-db2","host":"adx-vm","measurement_db_type":"AzureSQLDB","replica_updateability":"READ_WRITE","sql_instance":"adx-sql-server","wait_category":"Worker Thread","wait_type":"THREADPOOL"} 2021-09-09T13:51:20Z {"max_wait_time_ms":15,"resource_wait_ms":4469,"signal_wait_time_ms":0,"wait_time_ms":4469,"waiting_tasks_count":1464}

Da das gesammelte Metrikobjekt ein komplexer Typ ist, werden die Spalten Felder und Tags als dynamische Datentypen gespeichert. Es gibt viele Möglichkeiten, diese Daten abzufragen, z. B.:

  • Abfragen von JSON-Attributen direkt: Sie können JSON-Daten im rohen Format abfragen, ohne sie zu analysieren.

    Beispiel 1

    Tablename
| where name == "sqlserver_azure_db_resource_stats" and todouble(fields.avg_cpu_percent) > 7

    Beispiel 2

    Tablename
| distinct tostring(tags.database_name)

    Hinweis

    Dieser Ansatz könnte sich auf die Leistung auswirken, wenn große Datenmengen verwendet werden. Verwenden Sie in solchen Fällen den Updaterichtlinienansatz.

  • Verwenden Sie eine Updaterichtlinie: Transformieren dynamischer Datentypspalten mithilfe einer Updaterichtlinie. Wir empfehlen diesen Ansatz zum Abfragen großer Datenmengen.

    // Function to transform data
.create-or-alter function Transform_TargetTableName() {
  SourceTableName
  | mv-apply fields on (extend key = tostring(bag_keys(fields)[0]))
  | project fieldname=key, value=todouble(fields[key]), name, tags, timestamp
}

// Create destination table with above query's results schema (if it doesn't exist already)
.set-or-append TargetTableName <| Transform_TargetTableName() | take 0

// Apply update policy on destination table
.alter table TargetTableName policy update
@'[{"IsEnabled": true, "Source": "SourceTableName", "Query": "Transform_TargetTableName()", "IsTransactional": true, "PropagateIngestionProperties": false}]'

Syslog-Eingabe-Plug-In

In der folgenden Tabelle sind Beispielmetriken aufgeführt, die von Syslog Eingabe-Plug-In gesammelt werden:

name Tags Zeitstempel felder
syslog {"appname":"azsecmond","facility":"user","host":"adx-linux-vm","hostname":"adx-linux-vm","severity":"info"} 2021-09-20T14:36:44Z {"facility_code":1,"message":" 2021/09/20 14:36:44.890110 Failed to connect to mdsd: dial unix /var/run/mdsd/default_djson.socket: connect: no such file or directory","procid":"2184","severity_code":6,"timestamp":"1632148604890477000","version":1}
syslog {"appname":"CRON","facility":"authpriv","host":"adx-linux-vm","hostname":"adx-linux-vm","severity":"info"} 2021-09-20T14:37:01Z {"facility_code":10,"message":" pam_unix(cron:session): session opened for user root by (uid=0)","procid":"26446","severity_code":6,"timestamp":"1632148621120781000","version":1}

Es gibt mehrere Möglichkeiten, dynamische Spalten mit dem Erweiterungsoperator oder bag_unpack() Plug-In zu flachen. Sie können eine der beiden in der Funktion Transform_TargetTableName() der Updaterichtlinie verwenden.

  • Verwenden Sie den Erweiterungsoperator: Wir empfehlen, diesen Ansatz zu verwenden, da es schneller und robuster ist. Selbst wenn sich das Schema ändert, wird es keine Abfragen oder Dashboards unterbrechen.

    Tablename
| extend facility_code=toint(fields.facility_code), message=tostring(fields.message), procid= tolong(fields.procid), severity_code=toint(fields.severity_code),
SysLogTimestamp=unixtime_nanoseconds_todatetime(tolong(fields.timestamp)), version= todouble(fields.version),
appname= tostring(tags.appname), facility= tostring(tags.facility),host= tostring(tags.host), hostname=tostring(tags.hostname), severity=tostring(tags.severity)
| project-away fields, tags

  • Verwenden Sie bag_unpack() Plug-In: Dieser Ansatz entpackt automatisch dynamische Typspalten. Das Ändern des Quellschemas kann Probleme beim dynamischen Erweitern von Spalten verursachen.

    Tablename
| evaluate bag_unpack(tags, columnsConflict='replace_source')
| evaluate bag_unpack(fields, columnsConflict='replace_source')