將數據從Telegraf內嵌到 Azure Data Explorer

發行項
01/10/2024

重要

此連接器可用於 Microsoft Fabric 中的即時分析。使用本文中的指示，但有下列例外狀況：

如有需要，請使用建立 KQL 資料庫中的指示來建立資料庫。
如有需要，請使用建立空白數據表中的指示來建立數據表。
使用複製 URI 中的指示取得查詢或擷取 URI。
在 KQL 查詢集中執行查詢。

Azure Data Explorer 支援從 Telegraf 擷取數據。 Telegraf 是開放原始碼、輕量、最小記憶體腳印代理程式，用於收集、處理和寫入遙測數據，包括記錄、計量和IoT數據。 Telegraf 支援數百個輸入和輸出外掛程式。它受到開放原始碼社群廣泛使用且受到妥善支援。 Azure Data Explorer 輸出外掛程式可作為 Telegraf 的連接器，並支援將數據從許多類型的輸入外掛程式擷取至 Azure Data Explorer。

必要條件

Azure 訂用帳戶。建立 Azure 免費帳戶。
Azure 資料總管叢集和資料庫。建立叢集和資料庫。
Telegraf。在虛擬機中裝載Telegraf (VM) 或容器。 Telegraf 可以在本機裝載受監視的應用程式或服務部署，或在專用監視計算/容器上從遠端進行裝載。

支援的驗證方法

外掛程式支援下列驗證方法：

Microsoft Entra 應用程式金鑰或憑證的應用程式。
- 如需如何在 Microsoft Entra標識碼中建立和註冊應用程式的資訊，請參閱註冊應用程式。
- 如需服務主體的相關信息，請參閱 Microsoft Entra標識碼中的應用程式和服務主體物件。
Microsoft Entra 使用者令牌
- 允許外掛程式像用戶一樣進行驗證。我們僅建議針對開發目的使用這個方法。
Azure 受控服務識別 (MSI) 令牌
- 如果您是在支援的 Azure 環境中執行 Telegraf，例如 Azure 虛擬機器，這是慣用的驗證方法。

無論您使用哪一種方法，指定的主體都必須在 Azure Data Explorer 中指派資料庫使用者角色。此角色可讓外掛程式建立擷取數據所需的數據表。如果外掛程式設定為 create_tables=false，則指定的主體至少必須具有 資料庫擷取器 角色。

設定驗證方法

外掛程式會檢查環境變數的特定組態，以判斷要使用的驗證方法。設定會依照指定的順序進行評估，並使用第一個偵測到的組態。如果未偵測到有效的組態，外掛程式將無法進行驗證。

若要設定外掛程式的驗證，請為您選擇的驗證方法設定適當的環境變數：

用戶端認證 (Microsoft Entra 應用程式令牌) ：Microsoft Entra 應用程式標識碼和秘密。
- AZURE_TENANT_ID：用於驗證的 Microsoft Entra 租用戶標識碼。
- AZURE_CLIENT_ID：租用戶中應用程式註冊的用戶端標識碼。
- AZURE_CLIENT_SECRET：為應用程式註冊產生的客戶端密碼。
用戶端憑證 (Microsoft Entra 應用程式令牌) ：Microsoft Entra 應用程式識別碼和 X.509 憑證。
- AZURE_TENANT_ID：用於驗證的 Microsoft Entra 租用戶標識碼。
- AZURE_CERTIFICATE_PATH:P EM 或 PFX 格式的憑證和私鑰組路徑，可驗證應用程式註冊。
- AZURE_CERTIFICATE_PASSWORD：為憑證設定的密碼。
資源擁有者密碼 (Microsoft Entra 使用者令牌) ：Microsoft Entra 用戶和密碼。不建議使用此授與類型。如果您需要互動式登錄，請使用裝置登入。
- AZURE_TENANT_ID：用於驗證的 Microsoft Entra 租用戶標識碼。
- AZURE_CLIENT_ID：租用戶中應用程式註冊的用戶端標識碼。
- AZURE_USERNAME：Microsoft Entra 用戶帳戶的用戶名稱也稱為 upn。
- AZURE_PASSWORD：Microsoft Entra 用戶帳戶的密碼。請注意，這不支持啟用 MFA 的帳戶。
Azure 受控服務識別：將認證管理委派給平臺。此方法會要求在 Azure 中執行程式代碼，例如 VM。所有設定都是由 Azure 處理。如需詳細資訊，請參閱 Azure 受控服務識別。只有在使用 Azure Resource Manager 時，才能使用這個方法。

設定Telegraf

Telerg要是組態驅動代理程式。若要開始使用，您必須安裝 Telegraf 並設定必要的輸入和輸出外掛程式。組態檔的預設位置如下所示：

針對 Windows ：C：\Program Files\Telegraf\telegraf.conf
針對 Linux： etc/telegraf/telegraf.conf

若要啟用 Azure Data Explorer 輸出外掛程式，您必須取消批注自動產生的組態檔中的下一節：

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

支援的擷取類型

外掛程式支援受控 (串流) 和佇列 (批處理) 擷取。默認擷取類型已 排入佇列。

重要

若要使用受控擷取，您必須在叢集上啟用串流擷取。

若要設定外掛程式的擷取類型，請修改自動產生的組態檔，如下所示：

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

查詢擷取的數據

以下是使用 SQL 和 syslog 輸入外掛程式所收集的數據範例，以及 Azure Data Explorer 輸出外掛程式。針對每個輸入法，有一個如何在 Azure Data Explorer 中使用數據轉換和查詢的範例。

SQL 輸入外掛程式

下表顯示 SQL 輸入外掛程式所收集的範例計量資料：

NAME	tags	timestamp	fields
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}

由於所收集的計量對像是複雜類型， 因此欄位 和標記數據行會儲存為動態數據類型。有許多方式可以查詢此數據，例如：

直接查詢 JSON 屬性：您可以以原始格式查詢 JSON 數據，而不進行剖析。

範例 1
```
Tablename
| where name == "sqlserver_azure_db_resource_stats" and todouble(fields.avg_cpu_percent) > 7
```
範例 2
```
Tablename
| distinct tostring(tags.database_name)
```
注意

使用大量數據時，這種方法可能會影響效能。在這種情況下，請使用更新原則方法。

使用更新原則：使用更新原則轉換動態數據類型數據行。我們建議使用此方法來查詢大量數據。

// 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 輸入外掛程式

下表顯示 Syslog 輸入外掛程式所收集的範例計量資料：

NAME	tags	timestamp	fields
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 無法連線到 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) ： (uid=0) ”，“procid”：“26446”，“severity_code”：“6，”timestamp“：”1632148621120781000“，”version“：1}

使用 extend 運算符或 bag_unpack () 外掛程式，有多種方式可將動態數據行壓平合併。您可以在更新原則 Transform_TargetTableName () 函式中使用其中一個。

使用擴充運算符：我們建議使用此方法，因為此方法更快且強固。即使架構變更，也不會中斷查詢或儀錶板。

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

使用 bag_unpack () 外掛程式：此方法會自動解壓縮動態類型數據行。變更來源架構可能會導致動態展開數據行時發生問題。
```
Tablename
| evaluate bag_unpack(tags, columnsConflict='replace_source')
| evaluate bag_unpack(fields, columnsConflict='replace_source')
```

共用方式為