你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
重要
本页包含使用 Kubernetes 部署清单（目前为预览版）管理 Azure IoT 操作组件的说明。 此功能提供 多个限制，不应用于生产工作负荷。
有关适用于 Beta 版、预览版或尚未正式发布的 Azure 功能的法律条款，请参阅 适用于 Microsoft azure 预览版的补充使用条款 。
OpenTelemetry 数据流终结点用于将指标和日志发送到 OpenTelemetry 收集器，然后可将数据转发到 Grafana 仪表板和 Azure Monitor 等可观测性平台。 可以配置终结点设置、身份验证、传输层安全性 (TLS) 和批处理选项。
先决条件
- Azure IoT 操作的实例
- 已部署且可从 Azure IoT 操作群集访问的 OpenTelemetry 收集器
OpenTelemetry 终结点概述
通过 OpenTelemetry 终结点，可以使用 OpenTelemetry 协议 (OTLP) 将遥测数据从 Azure IoT 操作数据流导出到 OpenTelemetry 收集器。 这样，就可以将设备和系统遥测数据集成到现有的可观测性基础结构中。
常见应用场景
- 设备诊断：将温度、压力和其他传感器读数导出为用于监视设备运行状况的指标
- 工厂监视：将生产线遥测数据发送到 Grafana 仪表板，以获取作可见性
- 系统可观测性：将应用程序日志和指标转发到 Azure Monitor 进行集中监视
- 自定义指标：向指标添加上下文属性（如工厂 ID 或位置）以更好地筛选和分析
数据格式要求
OpenTelemetry 终结点要求数据符合具有 metrics 数组和/或 logs 数组的特定 JSON 架构。 不符合此架构的消息会被删除并返回确认，以防止消息丢失。
JSON 有效负载必须使用此顶级结构：
{
"metrics": [ /* array of metric objects */ ],
"logs": [ /* array of log objects */ ]
}
必须至少存在一个 metrics 或 logs。
所有传入消息都根据所需的架构进行验证。 验证失败的消息会被删除，向代理返回确认信息，并记录日志以进行故障排除。 常见的验证失败包括缺少必填字段、数据类型无效、指标类型或日志级别不受支持，以及时间戳格式不正确。 如果 MQTT 消息包含过期时间戳，则处理前会筛选出过期的消息。
指标格式
metrics 数组中的每个指标对象都必须包含以下字段：
必填字段：
-
name（字符串）：指标名称 -
type（字符串）：指标类型（请参阅支持的指标类型） -
value（数字）：指标的数值
可选字段：
-
description（字符串）：指标的用户可读说明 -
timestamp（数字）：记录指标时 Unix 纪元时间戳（以纳秒为单位） -
attributes（数组）：指标标记和筛选的键值对
{
"metrics": [
{
"name": "temperature",
"description": "The temperature reading from sensor",
"type": "f64_gauge",
"value": 72.5,
"timestamp": 1754851200000000000,
"attributes": [
{
"key": "factoryId",
"value": "factory1"
},
{
"key": "location",
"value": "warehouse"
}
]
}
]
}
attributes 数组中的每个属性都必须具有：
-
key（字符串）：属性名称 -
value（字符串）：属性值（必须是字符串）
日志格式
logs 数组中的每个日志对象都必须包含以下字段：
必填字段：
-
value（字符串）：记录消息内容 -
level（字符串）：日志级别（请参阅支持的日志级别）
可选字段：
-
timestamp（数字）：记录日志时的 Unix 纪元时间戳（以纳秒为单位） -
attributes（数组）：用于日志上下文和筛选的键值对
{
"logs": [
{
"value": "Device temperature sensor initialized",
"level": "info",
"timestamp": 1754851200000000000,
"attributes": [
{
"key": "deviceId",
"value": "sensor001"
},
{
"key": "component",
"value": "temperature-sensor"
}
]
}
]
}
attributes 数组中的每个属性都必须具有：
-
key（字符串）：属性名称 -
value（字符串）：属性值（必须是字符串）
支持的指标类型
支持以下 OpenTelemetry 指标类型：
- 计数器：
u64_counter、f64_counter- 单调递增值 - 向上/向下计数器：
i64_up_down_counter、f64_up_down_counter- 可增加或减少的值 - 仪表：
u64_gauge、i64_gauge、f64_gauge- 时间点值 - 直方图：
f64_histogram、u64_histogram- 值的分布
支持的日志级别
支持以下日志级别：
tracedebuginfowarnerrorfatal
创建 OpenTelemetry 终结点
可以使用运维体验、Bicep 或 Kubernetes 来创建 OpenTelemetry 数据流终结点。
若要在 运营体验中创建 OpenTelemetry 数据流，请转到 数据流终端。
在数据流终结点页中，标识 “打开遥测 ”并选择“ + 新建”。
在“ 创建新数据流终结点：打开遥测 ”窗格中，选择“ 基本 配置”选项卡并提供以下信息：
- 名称：终结点的唯一名称。
-
主机：
<host>:<port>格式的 OpenTelemetry 收集器终结点，例如otel-collector.monitoring.svc.cluster.local:4317。 -
身份验证方法：选择以下身份验证方法之一：
- Kubernetes 服务帐户令牌：使用 Kubernetes 服务帐户令牌通过 OpenTelemetry collector 进行身份验证。 为 OpenTelemetry 收集器配置提供受众值。 有关更多详细信息 ，请参阅服务帐户令牌（SAT ）。
- 匿名：当 OpenTelemetry 收集器不需要身份验证时使用。
- X509 证书：使用客户端证书进行相互 TLS 身份验证。 提供包含客户端证书的 Kubernetes 机密的名称。 有关更多详细信息，请参阅 X.509 证书 。
选择 “高级 配置”选项卡并提供以下信息：
- 批处理延迟（以秒为单位）：发送批处理之前等待的最大时间。 默认值为 5 秒。
- 消息计数：批中消息的最大数量。 默认值为 100000 条消息。
-
TLS 模式：选择以下 TLS 模式之一：
- 已启用：启用 TLS 以便与 OpenTelemetry 收集器进行安全通信。 提供包含受信任 CA 证书的 Kubernetes ConfigMap 的名称。
- 已禁用：禁用 TLS。
- 受信任的 CA 证书配置映射名称：包含受信任 CA 证书的 Kubernetes ConfigMap 的名称。
选择 “应用” 以创建 OpenTelemetry 终结点。
配置选项
本部分介绍 OpenTelemetry 数据流终结点的配置选项。
主机
host 属性指定 OpenTelemetry 收集器终结点 URL。 包括协议（http:// 或 https://）和端口号。
例子：
https://otel-collector.monitoring.svc.cluster.local:4317http://localhost:4317https://otel-collector:4317
身份验证
OpenTelemetry 终结点支持多种身份验证方法，以便安全地连接到收集器。
服务帐户令牌 (SAT)
服务帐户令牌 (SAT) 身份验证使用 Kubernetes 服务帐户令牌向 OpenTelemetry 收集器进行身份验证。
将 <OTEL_AUDIENCE> 替换为 OpenTelemetry 收集器配置的受众值。 此值必须与收集器上的预期受众匹配。
在“ 创建新数据流终结点：打开遥测 ”窗格的“ 基本 配置”选项卡下，选择 Kubernetes 服务帐户令牌 作为身份验证方法。
为 OpenTelemetry 收集器配置提供 服务受众 值。
重要
只能在创建新的 OpenTelemetry 数据流终结点时选择身份验证方法。 创建 OpenTelemetry 数据流终结点后，无法更改身份验证方法。 如果要更改现有数据流的身份验证方法，请删除原始数据流，并使用新的身份验证方法创建新的数据流。
X.509 证书
X.509 证书身份验证使用客户端证书进行相互 TLS 身份验证。
在“ 创建新数据流终结点：打开遥测 ”窗格的“ 基本 配置”选项卡下，选择 X509 证书 作为身份验证方法。
从 Azure Key Vault 提供以下信息：
- 同步的机密名称：包含客户端证书的 Kubernetes 机密的名称。
- X509 客户端证书：客户端证书。
- X509 客户端密钥：客户端证书的私钥。
- X509 中间证书：客户端证书链的中间证书。
在使用 X.509 证书身份验证之前，请使用客户端证书创建 Kubernetes 机密：
kubectl create secret tls <X509_SECRET_NAME> \
--cert=client.crt \
--key=client.key \
-n azure-iot-operations
匿名身份验证
OpenTelemetry 收集器不需要身份验证时，将使用匿名身份验证。
在“ 创建新数据流终结点：打开遥测 ”窗格的“ 基本 配置”选项卡下，选择“ 匿名 ”作为身份验证方法。 无需其他设置。
TLS 配置
配置传输层安全性 (TLS) 设置，以便与 OpenTelemetry 收集器进行安全通信。
已启用具有受信任 CA 的 TLS
- 在“ 创建新数据流终结点：打开遥测 ”窗格的“ 高级 配置”选项卡下，选择“ 已启用” 作为 TLS 模式。
- 在 受信任的 CA 证书配置映射名称 中，提供包含受信任 CA 证书的 Kubernetes ConfigMap 的名称。
禁用的 TLS
在“ 创建新数据流终结点：打开遥测 ”窗格的“ 高级 配置”选项卡下，选择 “已禁用” 作为 TLS 模式。
批处理
配置批处理设置，以便通过在发送到收集器之前对多个消息进行分组来优化性能。
在“ 创建新数据流终结点：打开遥测 ”窗格的“ 高级 配置”选项卡下，提供以下批处理设置：
- 批处理延迟（以秒为单位）：发送批处理之前等待的最大时间。 默认值为 5 秒。
- 消息计数：批中消息的最大数量。 默认值为 100000 条消息。
错误处理和故障排除
消息验证
OpenTelemetry 终结点根据所需的架构验证传入消息。 无效消息会被删除并确认，以防止数据流管道中的消息丢失。
常见验证错误：
- 缺少必填字段（对于指标来说缺少
name、type、value；对于日志来说缺少value、level） - 指标类型或日志级别无效
- 指标
value字段中的非数值 - 时间戳值格式不正确
传递保证
OpenTelemetry 终结点向收集器本身提供传递保证，但不向收集器可将数据转发到的上游服务提供传递保证。 数据到达收集器后，Azure IoT 操作无法查看它是否到达最终目标。