你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

配置 OpenTelemetry 数据流终结点（预览版）

2025-08-12

重要

本页包含使用 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 epoch 时间戳（以纳秒为单位）
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 epoch 时间戳（以纳秒为单位）
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_gaugef64_gauge - 时间点值
直方图： f64_histogram， u64_histogram - 值的分布

支持的日志级别

支持以下日志级别：

trace
debug
info
warn
error
fatal

创建 OpenTelemetry 终结点

可以使用 Bicep 或 Kubernetes 创建 OpenTelemetry 数据流终结点。

肱二头肌
库伯内特斯 (Kubernetes)

创建包含以下内容的 Bicep .bicep 文件。根据需要更新设置，并将占位符值 <AIO_INSTANCE_NAME> 替换为值。

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param endpointName string = '<ENDPOINT_NAME>'
param collectorHost string = '<COLLECTOR_HOST>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource openTelemetryEndpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-11-01' = {
  parent: aioInstance
  name: endpointName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    endpointType: 'OpenTelemetry'
    openTelemetrySettings: {
      host: collectorHost
      authentication: {
        method: 'ServiceAccountToken'
        serviceAccountTokenSettings: {
          audience: '<OTEL_AUDIENCE>'
        }
      }
      tls: {
        mode: 'Enabled'
        trustedCaCertificateConfigMapRef: '<CA_CONFIGMAP_NAME>'
      }
      batching: {
        latencySeconds: 5
        maxMessages: 100
      }
    }
  }
}

通过运行以下 Azure CLI 命令部署文件：

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

创建包含以下内容的 Kubernetes 清单 .yaml 文件：

apiVersion: connectivity.iotoperations.azure.com/v1beta1
kind: DataflowEndpoint
metadata:
  name: <ENDPOINT_NAME>
  namespace: azure-iot-operations
spec:
  endpointType: OpenTelemetry
  openTelemetrySettings:
    host: <COLLECTOR_HOST>
    authentication:
      method: ServiceAccountToken
      serviceAccountTokenSettings:
        audience: <OTEL_AUDIENCE>
    tls:
      mode: Enabled
      trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>
    batching:
      latencySeconds: 5
      maxMessages: 100

将清单文件应用到 Kubernetes 群集：

kubectl apply -f <FILE>.yaml

配置选项

本部分介绍 OpenTelemetry 数据流终结点的配置选项。

主机

该 host 属性指定 OpenTelemetry 收集器终结点 URL。包括协议（http:// 或 https://）和端口号。

例子：

https://otel-collector.monitoring.svc.cluster.local:4317
http://localhost:4317
https://otel-collector:4317

身份验证

OpenTelemetry 终结点支持多种身份验证方法，以便安全地连接到收集器。

服务帐户令牌（SAT）

服务帐户令牌（SAT）身份验证使用 Kubernetes 服务帐户令牌通过 OpenTelemetry 收集器进行身份验证。

替换为 <OTEL_AUDIENCE> OpenTelemetry 收集器配置的受众值。此值必须与收集器上的预期受众匹配。

肱二头肌
库伯内特斯 (Kubernetes)

authentication: {
  method: 'ServiceAccountToken'
  serviceAccountTokenSettings: {
    audience: '<OTEL_AUDIENCE>'
  }
}

authentication:
  method: ServiceAccountToken
  serviceAccountTokenSettings:
    audience: <OTEL_AUDIENCE>

X.509 证书

X.509 证书身份验证使用客户端证书进行相互 TLS 身份验证。

肱二头肌
库伯内特斯 (Kubernetes)

authentication: {
  method: 'X509Certificate'
  x509CertificateSettings: {
    secretRef: '<X509_SECRET_NAME>'
  }
}

authentication:
  method: X509Certificate
  x509CertificateSettings:
    secretRef: <X509_SECRET_NAME>

在使用 X.509 证书身份验证之前，请使用客户端证书创建 Kubernetes 机密：

kubectl create secret tls <X509_SECRET_NAME> \
  --cert=client.crt \
  --key=client.key \
  -n azure-iot-operations

匿名身份验证

OpenTelemetry 收集器不需要身份验证时，将使用匿名身份验证。

肱二头肌
库伯内特斯 (Kubernetes)

authentication: {
  method: 'Anonymous'
  anonymousSettings: {}
}

authentication:
  method: Anonymous
  anonymousSettings: {}

TLS 配置

配置传输层安全性（TLS）设置，以便与 OpenTelemetry 收集器进行安全通信。

tls: {
  mode: 'Enabled'
  trustedCaCertificateConfigMapRef: '<CA_CONFIGMAP_NAME>'
}

tls:
  mode: Enabled
  trustedCaCertificateConfigMapRef: <CA_CONFIGMAP_NAME>

禁用的 TLS

肱二头肌
库伯内特斯 (Kubernetes)

tls: {
  mode: 'Disabled'
}

tls:
  mode: Disabled

批处理

配置批处理设置，以便通过在发送到收集器之前对多个消息进行分组来优化性能。

肱二头肌
库伯内特斯 (Kubernetes)

batching: {
  latencySeconds: 5
  maxMessages: 100
}

batching:
  latencySeconds: 5
  maxMessages: 100

资产	DESCRIPTION	违约
`latencySeconds`	发送批之前要等待的最长时间。	60 秒
`maxMessages`	批中的最大消息数。	100000 条消息

错误处理和故障排除

消息验证

OpenTelemetry 终结点根据所需的架构验证传入消息。删除无效消息并确认以防止数据流管道中的消息丢失。

常见验证错误：

缺少必填字段（name、type指标value、valuelevel日志）
无效的指标类型或日志级别
指标 value 字段中的非数值
格式不正确的时间戳值

交付保证

OpenTelemetry 终结点向收集器本身提供传递保证，但不能提供给收集器可以将数据转发到的上游服务。数据到达收集器后，Azure IoT作无法查看它是否到达最终目标。