将 IoT Edge 指标收集器迁移到日志引入

Metrics Collector 2.0 通过日志采集 API 向 Azure Monitor 发送指标。 本指南将现有的直接上传部署升级到版本 2.0.0。

迁移会改变认证、模块配置、目的表和查询范围。 模块升级不会更新保存的练习册或提醒规则。

对于新部署，建议从监控IoT Edge设备开始。

Azure Monitor将于2026年9月14日终止对HTTP Data Collector API的支持。 这个日期并不意味着立即停止数据摄取。 有关退休详情和平台迁移流程，请参见 从 HTTP 数据收集器 API 迁移。

了解变化

本比较采用本指南中的透传自定义表架构。

UploadTarget=IotMessage仍然通过 edgeHub 向 IoT 中心 或 IoT Central 发送指标。 收集器升级不会迁移处理这些消息的下游服务。

准备迁移

1. 对使用遗留指标的设备、部署配置、保存的工作簿和警报规则进行清点。
2. 通过您的安全配置管理流程备份部署配置。
3. 保存每本自定义练习册的未更改副本。
4. 第一次升级时选择一台有代表性的设备。
5. 为你一起升级的每个设备组规划一个UTC切换边界。

保留现有的 InsightsMetrics 历史记录。 新的DCR不会复制或转换这些历史记录。

准备 Azure Monitor 资源

使用 日志导入门户教程 创建自定义表和DCR。 在下一节使用收集器模式，而不是教程中的示例模式。

日志摄取API概述描述了端点选择、区域需求、权限和服务限制。 根据您的网络配置要求，使用 DCR 直连终结点或数据收集终结点（DCE）。

记录这些数值：

• 目标日志分析工作区。
• DCR日志摄取端点或DCE日志摄取端点。
• DCR 的不可变 ID，以 dcr- 开头。
• DCR输入流名称。
• IoT 中心 或 IoT Central 应用程序的 ARM 资源 ID。

在DCR上授予收集者身份Monitoring Metrics Publisher。 让工作簿用户获得目标工作区的查询权限。 这些权限是分开的。

配置收集器模式

请在 DCR 输入流和目标表中使用以下列。 配置 DCR，使这些字段直接传递且不重命名。

本指南和精选工作手册默认使用 IoTEdgeMetrics_CL 。 你可以使用另一个自定义表，列和类型相同。 用工作簿参数 MetricsTableName 选择其名称。

本指南使用 Custom-IoTEdgeMetrics 输入流名称。 催收人不强制执行任何一个名称。 如果你选择了另一个表，请更新DCR目标和示例查询和警报规则中的表引用。

请使用这个 JSON 示例在表格创建向导中定义模式：

[
  {
    "TimeGenerated": "2026-09-11T12:00:00Z",
    "Origin": "iot.azm.ms",
    "Namespace": "metricsmodule",
    "Name": "edgeAgent_total_time_running_correctly_seconds",
    "Value": 300.0,
    "Tags": "{\"edge_device\":\"example-device\",\"module_name\":\"edgeHub\",\"instance_number\":\"example-instance\"}",
    "ResourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Devices/IotHubs/example-hub"
  }
]

保留抓取时间戳和所有指标维度。 关于内置的表功能，请参见 Azure Monitor 表功能支持。

理解资源匹配和查询范围

遗留设备 InsightsMetrics._ResourceId 可以使用与配置中的 ARM ID 不同的外壳。 新的普通 ResourceId 会保留在模块的 ResourceId 配置中指定的大小写。

在筛选或分组之前，先对所选的ARM ID和存储的资源ID应用 tolower() 。 模块配置中保留现有的ARM ID。

该指南在直通架构中将 ResourceId 保留为普通列。 使用此配置，查询Log Analytics工作区并筛选ResourceId目标资源。

Azure Monitor 还支持对在引入时指定资源 ID 的自定义日志进行资源关联。 请参见 Azure Monitor 日志中的标准列。 查询时使用的别名不会更改数据引入时的资源关联关系或访问权限。

配置身份验证

收集者按顺序尝试这些凭证类型：

1. EnvironmentCredential，用于应用证书或客户端秘密。
2. WorkloadIdentityCredential，表示联邦代币。
3. ManagedIdentityCredential，用于主机身份。

收集器不会在主机上使用 Azure CLI、Visual Studio 或 PowerShell 登录。 只配置一种应用凭证方法。 例如，在使用证书时移除 AZURE_CLIENT_SECRET ，这样过时的秘密不会阻止收集者尝试证书或后续凭证类型。

证书身份验证

在租户中使用包含DCR的应用注册。 关于证书注册，请参见 向应用程序添加凭证。

1. 在 DCR 上向应用程序的服务主体授予 Monitoring Metrics Publisher 权限。
2. 通过您的安全证书管理流程传递其证书和私钥。
3. 将证书文件只读挂载在收集器容器内。
4. 允许容器进程读取文件，但不允许其他用户访问。
5. 将这些环境变量添加到模块中：

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<application-client-id>
AZURE_CLIENT_CERTIFICATE_PATH=/run/secrets/metrics-collector/client.pfx

路径指的是容器内部的文件。 使用你的安全秘密传递机制获取证书密码或客户端秘密。 不要把私钥内容放进部署清单。

在证书到期之前规划好证书的续订和分发。 关于凭证配置，请参见 EnvironmentCredential。

客户端秘密认证

在租户中使用包含DCR的应用注册。 在 DCR 上向其服务主体授予 Monitoring Metrics Publisher 角色。 创建一个客户端秘密 ，使用它的 值，而不是它的ID。

在部署清单中设置收集模块的环境变量。 将示例值替换为租户ID、应用客户端ID和客户端秘密值：

"env": {
  "AZURE_TENANT_ID": { "value": "<tenant-id>" },
  "AZURE_CLIENT_ID": { "value": "<application-client-id>" },
  "AZURE_CLIENT_SECRET": { "value": "<client-secret-value>" }
}

在机密过期之前轮换机密。 在用替换机确认摄入后，撤销旧秘密。

托管标识

在Azure虚拟机上，当收集器容器能够到达主机的身份端点时，直接托管身份是最简单的选择。 将 DCR 上的 监控指标发布者 分配给该标识。

• 对于系统分配的标识，请将 AZURE_CLIENT_ID 保持为未设置。
• 对于用户分配的标识，请将 AZURE_CLIENT_ID 设置为其客户端 ID。

IoT Edge 设备身份不是 Azure 管理身份。 请检查 ManagedIdentityCredential 中的主机和容器访问要求。

工作负荷标识联合

收集器通过 WorkloadIdentityCredential 使用来自令牌文件的联合断言。 它不会创建或刷新断言文件。

设置AZURE_TENANT_ID、AZURE_CLIENT_ID和AZURE_FEDERATED_TOKEN_FILE。 向该应用程序的服务主体授予 DCR 上的 Monitoring Metrics Publisher 权限。 令牌文件生成方必须在断言过期前将其刷新，并确保收集器进程可读取该文件。

关于 Azure 虚拟机，请参见“配置应用以信任托管身份”。 关于其他支持的发行机构，请参见 工作负载身份联合。

更新模块

在 IoT Edge 设备上使用 Set 模块来更新现有的收集模块。

1. 将其图像设置为 mcr.microsoft.com/azureiotedge-metrics-collector:2.0.0。

2. 用以下环境变量替换遗留工作区配置。

   环境变量	Value
   UploadTarget	AzureMonitor
   DataCollectionEndpoint	HTTPS 日志摄取基础终结点，而不是 ARM ID 或构造的 API 请求 URL。
   DataCollectionRuleId	DCR 不可变 ID，而不是它的名称或 ARM ID。
   DataCollectionStreamName	输入流的确切名称，如 Custom-IoTEdgeMetrics，而非目标表名称。
   ResourceId	现有 IoT 中心 或 IoT Central 应用的 ARM 资源 ID。
   AzureDomain	azure.com 用于公共 Azure，azure.us 用于 Azure 政府版，或 azure.cn 用于 Azure 中国版。

3. 为你选定的身份添加认证配置。

4. 根据部署要求，保留 MetricsEndpointsCSV、ScrapeFrequencyInSecs、AllowedMetrics 和 BlockedMetrics。

5. 从该模块中移除 LogAnalyticsWorkspaceId 和 LogAnalyticsSharedKey 。

6. 允许访问已配置的数据引入端点以及您的身份验证方法所需的身份验证端点。

7. 将部署应用于第一个设备。

摄取端点必须匹配由 AzureDomain选定的云。 关于代理配置，请参见 代理注意事项。

检查新摄入情况

在目标工作区打开 日志 。 在每个查询中，将示例 ARM ID 替换为你的资源 ID。 如果你用了其他表名，就在示例中替换它。

let SelectedResourceId = tolower("/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Devices/IotHubs/example-hub");
IoTEdgeMetrics_CL
| where TimeGenerated > ago(15m) and Origin == "iot.azm.ms"
| where tolower(ResourceId) == SelectedResourceId
| extend Dimensions = parse_json(Tags)
| summarize Rows = count(), FirstEvent = min(TimeGenerated),
    LastEvent = max(TimeGenerated), MetricNames = dcount(Name),
    Series = dcount(strcat(Name, "|", Tags)),
    NullValues = countif(isnull(Value)),
    MissingDevice = countif(isempty(tostring(Dimensions.edge_device)))

检查模块上传日志、近期事件时间戳、预期指标名称和设备尺寸。 检查内置指标的 NullValues 和 MissingDevice 是否为零。

Metrics Collector 2.0 在直接上传时会省略 NaN 和无限值。 即使汇总的基础样本缺失，有限_sum和_count样本仍可保留。

被接受的上传并不证明每个值都有预期类型。 检查空值、事件时间戳以及上传是否成功。

检查是否有重复的事件激活码：

let SelectedResourceId = tolower("/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Devices/IotHubs/example-hub");
IoTEdgeMetrics_CL
| where TimeGenerated > ago(1h) and Origin == "iot.azm.ms"
| extend ResourceId = tolower(ResourceId)
| where ResourceId == SelectedResourceId
| summarize Copies = count() by TimeGenerated, Name, Tags, ResourceId
| where Copies > 1
| order by Copies desc

没有结果意味着查询在该时间窗口内没有发现重复的组。 上传重试在部分成功后可能产生重复行。 不要假设每次都送货。

将工作簿切换到新数据

1. 在您的 IoT 中心 或 IoT Central 应用中，从监控>工作簿中打开一个精心策划的工作簿。
2. 选择包含你指标的 Metrics Log Analytics 工作区。
3. 选择目标物联网资源和时间范围。
4. 确认指标来源为仅新增。 如果你打开的是较早保存的副本，且其默认设置仍为 仅限旧版，请将其改为 仅限新版。
5. 将 MetricsTableName 设置为目标表，或保留默认的 IoTEdgeMetrics_CL。
6. 查看设备列表和预期的指标图表。

更新后的图库模板默认 仅为新建，只读取所选自定义表，无需切换时间。 如果调用方省略或清除 MetricsTableName，工作簿将使用 IoTEdgeMetrics_CL。 输入无效名称时，会显示错误，并且在你将其更正之前，仍会使用此默认值。 仅限旧版 始终显示为 InsightsMetrics。 现有保存的副本会保留其保存的设置。

要查看两个历史，请选择 “合并遗产”和“新历史”。 该工作簿随后会显示 切换时间 (UTC)。 以 YYYY-MM-DDTHH:mm:ssZ 格式输入实际边界。

合并模式读取边界前的遗留数据，以及边界处或之后的新数据。 它为选定的资源使用一个边界。 如果设备边界不同，使用不同的选择或为每个设备组自定义查询。

关于工作簿视图和已保存的副本，请参见 探索精选可视化内容。

在自定义查询中保留历史

保留 InsightsMetrics 历史记录直到其保留期。 使用实际的事件时间界限，而不是你打开练习册的时间。

替换本例中的示意 2026-09-11T12:00:00Z 边界。 选择包含边界的时间范围。 此查询需要同时满足这两个表。 对于单表工作区，仅使用其对应的分支即可。

let Cutover = datetime(2026-09-11T12:00:00Z);
let SelectedResourceId = tolower("/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Devices/IotHubs/example-hub");
let EdgeMetrics = union
(
    InsightsMetrics
    | where Origin == "iot.azm.ms" and TimeGenerated < Cutover
    | project TimeGenerated, Name, Val, Tags,
        ResourceId = tolower(_ResourceId), SourceTable = "InsightsMetrics"
),
(
    IoTEdgeMetrics_CL
    | where Origin == "iot.azm.ms" and TimeGenerated >= Cutover
    | project TimeGenerated, Name, Val = Value, Tags,
        ResourceId = tolower(ResourceId), SourceTable = "IoTEdgeMetrics_CL"
);
EdgeMetrics
| where TimeGenerated > ago(7d) and ResourceId == SelectedResourceId
| extend Device = tostring(parse_json(Tags).edge_device)
| summarize Rows = count(), FirstEvent = min(TimeGenerated),
    LastEvent = max(TimeGenerated) by ResourceId, Device, SourceTable

这两个分支都显示小写字母 ResourceId 和数字 Val。 将选定的 ID 和两个资源列都转换为小写，可以确保同一资源归入同一组。

边界排除了重叠的历史，但不会移除表中的重试。 保留所有时间序列维度、事件时间顺序、计数器重置处理以及直方图 _sum 和 _count 对。

使用合适的时间箱来合并 edgeAgent 和 edgeHub 的周期。 它们的抓取时间戳在同一收集周期内可能存在差异。

更新无数据检查

仅检查 InsightsMetrics 的查询可能会隐藏新的指标。 更新所有无数据判断和设备选择相关查询，而不只是图表查询。

此示例需要同时使用表，并使用与前述查询相同的替换值：

let Cutover = datetime(2026-09-11T12:00:00Z);
let SelectedResourceId = tolower("/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Devices/IotHubs/example-hub");
print
    LegacyHasData = toscalar(
        InsightsMetrics
        | where Origin == "iot.azm.ms" and TimeGenerated > ago(7d) and TimeGenerated < Cutover
        | where tolower(_ResourceId) == SelectedResourceId
        | take 1 | count) > 0,
    NewHasData = toscalar(
        IoTEdgeMetrics_CL
        | where Origin == "iot.azm.ms" and TimeGenerated > ago(7d) and TimeGenerated >= Cutover
        | where tolower(ResourceId) == SelectedResourceId
        | take 1 | count) > 0
| extend HasData = LegacyHasData or NewHasData,
    TransitionHasData = LegacyHasData and NewHasData

对于单表工作区，省略不存在的表对应的分支。 将查询权限错误与空结果分开处理。

更新已保存的练习册和提醒

公开模板更新不会改变你之前保存或自定义过的活页簿。 在替换保存的练习册之前，先做一份单独的副本。

1. 选择工作区作为度量查询的执行范围。
2. 在每个度量查询、参数查询和无数据检查中对资源ID和值列进行规范化。
3. 保留自定义度量、尺寸、阈值、计数重置逻辑和直方图对。
4. 更新钻孔链接以传递工作区、资源、设备、时间范围、源模式、表名和切换时间。
5. 在替换已保存的副本前，请检查遗留模式、新模式和合并模式。

警报规则是独立的资源。 通过 创建提醒更新查询和工作区范围。 检查设备尺寸、目标资源、阈值、发射、分辨率和通知传递。 在过渡期间避免重复来自旧规则和新规则的通知。

完成部署

1. 检查第一台设备的新数据、工作簿和警报。
2. 扩展部署到下一个设备组。
3. 记录每个组的实际切换分界点。
4. 在所有依赖的消费者迁移后，从部署系统中移除未使用的工作区凭证。

如果导入失败，暂停推送并使用 监控故障排除。 不要认为收集器会重放上传失败的时间间隔中的数据。

如果你恢复了旧版部署，请在查询中将这些恢复后的旧版时间间隔考虑在内。 单个前向切换边界将它们排除在外。 恢复旧配置并不会延长对已退休API的支持。

后续步骤

• 探索精心策划的可视化作品。
• 制定警报规则。
• 添加自定义指标。