将数据从 OpenTelemetry 引入 Azure 数据资源管理器

项目
09/09/2024

重要

此连接器可用于 Microsoft Fabric 中的实时智能。使用本文中的说明时，请注意以下例外情况：

如果需要，请按照创建 KQL 数据库中的说明创建数据库。
如果需要，请按照创建空表中的说明创建表。
使用复制 URI 中的说明获取查询或引入 URI。
运行在 KQL 查询集中的查询。

OpenTelemetry (OTel) 是一个实现应用程序可观测性的开放式框架。该检测由云原生计算基金会 (CNCF) 托管，该基金会为可观测性数据（包括指标、日志和跟踪）提供标准接口。 OTel 收集器由以下三个组件组成：接收器，负责将数据放入收集器；处理器，决定如何处理接收到的数据；导出器，负责将接收到的数据发送到特定位置。

Azure 数据资源管理器导出器支持将多个接收器的数据引入 Azure 数据资源管理器。

注意

自述文档中汇总了配置设置。
有关导出器源代码，请参阅 Azure 数据资源管理器导出器。

在本文中，学习如何：

设置你的环境
配置 Azure 数据资源管理器导出器
运行示例应用程序
查询传入数据

先决条件

Azure 订阅。创建 Azure 帐户
群集和数据库：快速入门：创建 Azure 数据资源管理器群集和数据库

设置你的环境

在本部分，我们进行环境准备，以使用 OTel 导出器。

创建 Microsoft Entra 应用注册

对于需要在未创建用户的情况下访问 Azure 数据资源管理器的应用程序，将使用 Microsoft Entra 应用程序身份验证。若要使用 OTel 导出器引入数据，需要创建并注册一个 Microsoft Entra 服务主体，然后授权此主体，使其将数据引入 Azure 数据资源管理器数据库。

使用 Azure 数据资源管理器群集，按照在 Azure 数据资源管理器中创建 Microsoft Entra 应用程序注册中的步骤 1-7 进行操作。
保存以下值以便在后续步骤中使用：
- 应用程序（客户端）ID
- 目录（租户）ID
- 客户端机密密钥值

授予 Microsoft Entra 应用权限

在 Web UI 的查询选项卡中连接到你的群集。有关如何进行连接的详细信息，请参阅添加群集。
浏览到要在其中引入数据的数据库。
运行以下管理命令并替换占位符。将 DatabaseName 替换为目标数据库的名称，将 ApplicationID 替换为之前保存的值。此命令为应用授予数据库引入者角色。有关详细信息，请参阅管理数据库安全角色。
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'Azure Data Explorer App Registration'
```
注意

最后一个参数是字符串，当查询与数据库关联的角色时，该字符串会显示为注释。有关详细信息，请参阅查看现有安全角色。

创建目标表

浏览到 Azure 数据资源管理器 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 数据资源管理器有两种主要的引入类型：批量和流式。有关详细信息，请参阅批量引入与流式引入。流式处理方法在 Azure 数据资源管理器导出器配置中称为“托管”。如果需要近乎实时地获取日志和跟踪，流式引入可能是一个不错的选择。但与批量引入相比，流式引入使用更多资源。 OTel 框架本身会批量处理数据，在选择引入方法时应考虑这一点。

注意

必须在 Azure 数据资源管理器群集上启用流式引入才能启用 managed 选项。可使用 .show database streaming ingestion policy 命令检查是否已启用流式引入。

对这三个表中的每个表运行以下命令来启用流式引入：

.alter table <Table-Name> policy streamingingestion enable

配置 Azure 数据资源管理器导出器

要将 OpenTelemetry 数据引入 Azure 数据资源管理器，需要使用以下 Azure 数据资源管理器导出器配置来部署并运行 OpenTelemetry 发行版。

使用以下字段配置 Azure 数据资源管理器导出器：

字段	说明	建议的设置
导出工具	导出器类型	Azure 数据资源管理器
cluster_uri	包含数据库和表的 Azure 数据资源管理器群集的 URI	https:// <cluster>.kusto.chinacloudapi.cn
application_id	客户端 ID	<应用程序 ID>
application_key	客户端机密	<应用程序密钥>
tenant_id	租户	<应用程序租户>
db_name	接收日志的数据库	oteldb 或已创建的其他数据库
metrics_table_name	数据库 db_name 中存储导出的指标数据的目标表。	OTELMetrics
logs_table_name	数据库 db_name 中存储导出的日志数据的目标表。	OTELLogs
traces_table_name	数据库 db_name 中存储导出的跟踪数据的目标表。	OTELTraces
ingestion_type	引入类型：托管（流式）或批量	managed
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]
指标	服务：要启用的指标组件	接收方：[otlp] 处理器：[batch] 导出器：[azuredataexplorer]
日志	服务：要启用的日志组件	接收方：[otlp] 处理器：[batch] 导出器：[ azuredataexplorer]

使用“--config”标志运行 Azure 数据资源管理器导出器。

下面是 Azure 数据资源管理器导出器的示例配置：

---
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
processors:
  batch:
exporters:
  azuredataexplorer:
    cluster_uri: "https://<cluster>.kusto.chinacloudapi.cn"
    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]

使用示例应用程序收集数据

现已配置收集器，你需要发送要引入的数据。在本例中，你将示例 spring pet clinic 应用程序与 java OTeL 收集器代理配合使用。

在此处下载收集器代理：开放式遥测收集器代理。

若要为示例应用程序启用开放式遥测，请设置以下环境变量。 open-telemetry-collector-host 引用在其中配置并运行 Azure 数据资源管理器导出器的主机。

命令行
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 数据资源管理器中定义的表中。这些表是在 OTel 收集器配置中定义的数据库（即 oteldb）中创建的。你创建的表是在 OTel 收集器配置中定义的。在本例中，你已创建三个表：OTELMetrics、OTELLogs 和 OTELTraces。在本部分，你将分别查询每个表以获取少量可用数据。

浏览到 Azure 数据资源管理器 Web UI。
从左侧菜单中选择“查询”。
在左窗格中展开目标群集。
选择 oteldb 数据库，为查询提供正确的上下文。

按顺序复制/粘贴以下查询，以查看每个表中任意数量的行：

指标

OTELMetrics
|take 2

你应该会获得类似但不完全相同的结果，如下表所示：

时间戳	MetricName	MetricType	MetricUnit	MetricDescription	MetricValue	主机	MetricAttributes	ResourceAttributes
2022-07-01T12:55:33Z	http.server.active_requests	Sum	请求	当前正在进行的并发 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-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	直方图	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-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"}

日志

OTELLogs
|take 2

你应该会获得类似但不完全相同的结果，如下表所示：

时间戳	TraceId	SpanId	SeverityText	SeverityNumber	正文	ResourceAttributes	LogsAttributes
2022-07-01T13:00:39Z			INFO	9	在 DESKTOP-SFS7RUQ 上使用 Java 18.0.1.1 通过 PID 37280 启动 PetClinicApplication v2.7.0-SNAPSHOT (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	未设置有效配置文件，回退到 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-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"}

跟踪

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-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"}	[]	[]

进一步处理数据

使用更新策略，可根据应用程序需求进一步处理收集的数据。有关详细信息，请参阅更新策略概述。

以下示例将直方图指标导出到包含存储桶和聚合的特定于直方图的表中。在 Azure 数据资源管理器 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 数据资源管理器 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 数据资源管理器

先决条件

设置你的环境

创建 Microsoft Entra 应用注册

授予 Microsoft Entra 应用权限

创建目标表

设置流式引入

配置 Azure 数据资源管理器导出器

使用示例应用程序收集数据

查询传入数据

进一步处理数据

相关内容

其他资源