將數據從 OpenTelemetry 內嵌至 Azure Data Explorer

發行項
01/10/2024

重要

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

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

OpenTelemetry (OTel) 是應用程式可觀察性的開放架構。檢測是由 Cloud Native Computing Foundation () 裝載，可提供可觀察性數據的標準介面，包括計量、記錄和追蹤。 OTel 收集器是由下列三個元件所組成： 接收者 會處理如何將數據放入收集器、 處理器 決定如何處理接收的數據，而 匯出者 負責傳送接收的數據的位置。

Azure Data Explorer 匯出工具支援將數據從許多接收者擷取到 Azure Data Explorer。

注意

自述檔摘要說明組態設定。
如需匯出工具原始程式碼，請參閱 Azure Data Explorer 匯出工具。

在本文中，您將學會如何：

設定環境
設定 Azure Data Explorer 匯出工具
執行範例應用程式
查詢傳入數據

必要條件

Azure 訂用帳戶。创建免费 Azure 帐户
叢集和資料庫：快速入門：建立 Azure Data Explorer 叢集和資料庫

設定環境

在本節中，您會準備環境以使用 OTel 導出工具。

建立 Microsoft Entra 應用程式註冊

Microsoft Entra 應用程式驗證用於需要存取 Azure Data Explorer 且沒有使用者的應用程式。若要使用 OTel 匯出工具擷取數據，您必須建立並註冊 Microsoft Entra 服務主體，然後授權此主體內嵌 Azure Data Explorer 資料庫的數據。

使用 Azure Data Explorer 叢集，請遵循在 Azure Data Explorer 中建立 Microsoft Entra 應用程式註冊中的步驟 1-7。
儲存下列值，以供後續步驟使用：
- 應用程式 (用戶端) 識別碼
- 目錄 (租用戶) 識別碼
- 用戶端秘密金鑰值

授與 Microsoft Entra 應用程式許可權

在 Web UI 的 [查詢] 索引標籤中，連線到您的叢集。如需如何連線的詳細資訊，請參閱新增叢集。
流覽至您要在其中內嵌數據的資料庫。
執行下列管理命令，取代佔位元。將 DatabaseName 取代為目標資料庫的名稱，並將 ApplicationID 取代為先前儲存的值。此命令會授與應用程式資料庫擷取器角色。如需詳細資訊，請參閱管理資料庫安全性角色。
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'Azure Data Explorer App Registration'
```
注意

最後一個參數是一個字串，當您查詢與資料庫相關聯的角色時，會顯示為附注。如需詳細資訊，請參閱檢視現有的安全性角色。

建立目標資料表

流覽至 Azure Data Explorer Web UI。
從左側功能表中選取 [查詢 ]。
展開左窗格中的目標叢集。
選取目標資料庫，為您的查詢提供正確的內容。

執行下列命令來建立傳入資料的數據表和架構對應：

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

設定串流擷取

Azure Data Explorer 有兩種主要擷取類型：批處理和串流。如需詳細資訊，請參閱批處理與串流擷取。串流方法會在 Azure Data Explorer 匯出工具組態中呼叫受控。如果您需要近乎即時地取得記錄和追蹤，串流擷取可能是不錯的選擇。不過，串流擷取會使用比批次擷取更多的資源。 OTel 架構本身會批處理數據，在選擇要用於擷取的方法時，應考慮這些數據。

注意

必須在 Azure Data Explorer 叢集上啟用串流擷取，才能啟用 managed 選項。您可以使用 .show 資料庫串流擷取原則命令來檢查串流是否已啟用。

針對這三個資料表執行下列命令，以啟用串流擷取：

.alter table <Table-Name> policy streamingingestion enable

設定 Azure Data Explorer 匯出工具

若要將 OpenTelemetry 數據內嵌至 Azure Data Explorer，您需要使用下列 Azure Data Explorer 匯出工具設定來部署並執行 OpenTelemetry 散發套件。

使用下列欄位設定 Azure Data Explorer 匯出工具：

欄位	Description	建議的設定
匯出工具	匯出工具的類型	Azure 資料總管
cluster_uri	保留資料庫和數據表之 Azure Data Explorer 叢集的 URI	https:// <cluster.kusto.windows.net>
application_id	用戶端識別碼	<應用程式識別碼>
application_key	用戶端密碼	<應用程式金鑰>
tenant_id	租用戶	<應用程式租使用者>
db_name	接收記錄的資料庫	db 或其他您已建立的資料庫
metrics_table_name	資料庫中的目標數據表db_name儲存導出計量數據。	METRICS
logs_table_name	資料庫中的目標數據表db_name儲存匯出記錄數據。	LOGs
traces_table_name	資料庫中的目標數據表db_name儲存匯出追蹤數據。	要追蹤
ingestion_type	擷取類型：受控 (串流) 或批處理	受控
metrics_table_json_mapping	選擇性參數。根據 OTeL 計量屬性建立資料表期間，會定義預設數據表對應。您可以使用此參數來變更預設對應。	<json metrics_table_name對應>
logs_table_json_mapping	選擇性參數。根據 OTeL 記錄屬性建立資料表期間，會定義預設數據表對應。您可以使用此參數來變更預設對應。	<json logs_table_name對應>
traces_table_json_mapping	選擇性參數。根據 OTeL 追蹤屬性建立資料表期間，會定義預設數據表對應。您可以使用此參數來變更預設對應。	<json traces_table_name對應>
traces	服務：追蹤要啟用的元件	接收者：[otlp] 處理器：[batch] 導出工具：[azuredataexplorer]
metrics	服務：要啟用的計量元件	接收者：[otlp] 處理器：[batch] 導出工具：[azuredataexplorer]
記錄	服務：記錄要啟用的元件	接收者：[otlp] 處理器：[batch] 導出者：[ azuredataexplorer]

使用「--config」旗標來執行 Azure Data Explorer 導出工具。

以下是 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]

使用範例應用程式收集數據

現在已設定收集器，您必須傳送要擷取的數據。在此範例中，您搭配 java OTeL 收集器代理程式使用範例 spring pet diagnostic 應用程式。

在這裡下載收集器代理程序：開啟遙測收集器代理程式。

若要啟用範例應用程式的開啟遙測，請設定下列環境變數。 open-telemetry-collector-host 會參考 Azure Data Explorer 導出工具設定和執行所在的主機。

命令列
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

使用下列命令行自變數執行範例 spring-boot 應用程式：

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

查詢傳入數據

執行範例應用程式之後，您的數據已內嵌至 Azure Data Explorer 中定義的數據表。這些數據表是在 OTel 收集器組態中定義的資料庫中建立，如 一般。 您已建立的數據表已定義於 OTel 收集器組態中。在此範例中，您已建立三個數據表： METRICS、 Logs 和 一個一個數據表。在本節中，您會個別查詢每個數據表，以取得一小部分的可用數據。

流覽至 Azure Data Explorer Web UI。
從左側功能表中選取 [查詢 ]。
展開左窗格中的目標叢集。
選取 資料庫， 為您的查詢提供正確的內容。

依序複製/貼上下列查詢，以查看每個資料表中任意數目的數據列：

計量

OTELMetrics
|take 2

您應該會得到類似但不完全相同的結果，如下表所示：

時間戳記	MetricName	MetricType	MetricUnit	MetricDescription	MetricValue	Host	MetricAttributes	ResourceAttributes
2022-07-01T12：55：33Z	http.server.active_requests	Sum	requests	目前進行中的並行 HTTP 要求數目	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 位伺服器 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 1110.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	長條圖	ms	輸入 HTTP 要求的持續時間 (範例總和)	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 位伺服器 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 1110.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“}

記錄

OTELLogs
|take 2

您應該會得到類似但不完全相同的結果，如下表所示：

時間戳記	TraceId	SpanID	SeverityText	SeverityNumber	主體	ResourceAttributes	LogsAttributes
2022-07-01T13：00：39Z			INFO	9	透過 PID 37280 (C：\Users\，在 DESKTOP-SFS7RUQ上使用 Java 18.0.1.1-SNAPSHOT 啟動 PetClinicApplication v2.7.0-SNAPSHOT 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 位伺服器 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	未設定作用中的配置檔，回復為1個默認配置檔：“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 位伺服器 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”}

追蹤

OTELTraces
|take 2

您應該會得到類似但不完全相同的結果，如下表所示：

TraceId	SpanID	ParentId	SpanName	SpanStatus	SpanKind	StartTime	EndTime	ResourceAttributes	TraceAttributes	事件	連結
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 位伺服器 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 位伺服器 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”}	[]	[]

進一步數據處理

使用更新原則時，您可以根據應用程式需求進一步處理收集的數據。如需詳細資訊，請參閱更新原則概觀。

下列範例會將直方圖計量導出至具有貯體和匯總的直方特有數據表。在 Azure Data Explorer Web UI 的查詢窗格中執行下列命令：

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

下列命令會建立只包含直方圖計量類型的計數和總和值的數據表，並附加更新原則。在 Azure Data Explorer Web UI 的查詢窗格中執行下列命令：

 .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

共用方式為

將數據從 OpenTelemetry 內嵌至 Azure Data Explorer

必要條件

設定環境

建立 Microsoft Entra 應用程式註冊

授與 Microsoft Entra 應用程式許可權

建立目標資料表

設定串流擷取

設定 Azure Data Explorer 匯出工具

使用範例應用程式收集數據

查詢傳入數據

進一步數據處理

意見反應

意見反應

其他資源

共用方式為

將數據從 OpenTelemetry 內嵌至 Azure Data Explorer

必要條件

設定環境

建立 Microsoft Entra 應用程式註冊

授與 Microsoft Entra 應用程式許可權

建立目標資料表

設定串流擷取

設定 Azure Data Explorer 匯出工具

使用範例應用程式收集數據

查詢傳入數據

進一步數據處理

相關內容

意見反應

意見反應

其他資源