Azure Monitor Application Insights 中的 SDK 统计信息

Application Insights 提供 SDK 统计自定义指标，可帮助监视和排除丢失或意外的遥测行为。 当遥测未到达引入终结点时，SDK 统计信息可帮助识别发生了什么以及下一步该做什么。

SDK统计信息指标包括项目成功、掉落和重试的计数。 SDK 统计信息指标还包括 删除代码 和 重试代码 ，用于解释原因和指导后续步骤。

SDK 统计信息工作簿中提供了可视化效果。

满足先决条件

使用以下 SDK 或代理之一通过 OpenTelemetry 对应用程序进行监控：

SDK 统计信息概述

SDK 统计信息是 Application Insights SDK 和代理作为自定义指标发出的每进程计数器。 这些指标汇总了导出程序成功发送的遥测项数量、丢弃的项数量，以及被安排重试的项数量。

SDK 发布三个指标：

• Item_Success_Count
• Item_Dropped_Count
• Item_Retry_Count

审查维度

这些指标包括 customDimensions 中的维度和用于切片的标准 Application Insights 维度：

每个指标行表示导出间隔的聚合计数。 在时间切片中尝试的总次数等于 Item_Success_Count + Item_Dropped_Count。

配置 SDK 统计信息

SDK 统计信息默认处于启用状态。 使用环境变量禁用 SDK 统计信息或配置导出间隔。 更改环境变量后重启应用程序。

禁用 SDK 统计信息

在应用程序进程环境中设置环境变量 APPLICATIONINSIGHTS_SDKSTATS_DISABLED=true ，然后重启应用程序。

设置导出间隔

• 使用默认导出间隔 15 分钟。
• 使用APPLICATIONINSIGHTS_SDKSTATS_EXPORT_INTERVAL以秒为单位设置不同的间隔。

无需部署任何工作簿资源。 SDK 统计信息模板显示在 Application Insights 资源下的工作簿库中。 工作簿在 SDK 发出这些自定义指标之前会显示“无数据”。

打开 SDK 统计信息工作簿

打开 Application Insights 资源，然后打开 工作簿 并选择 SDK 统计信息。该体验使用具有简化的视觉对象集的单个工作簿。

使用筛选器

使用工作簿顶部的筛选器来限定视图的范围：

• 时间范围：按时间窗口和箱大小筛选。
• SDK 版本：按 sdkVersion 字段筛选。
• 遥测类型：按 telemetry_type 维度筛选。
• 删除原因和删除代码：按 drop.reason 和 drop.code 筛选。

查看工作簿视觉对象

该工作簿专注于一组简明的图表，以在上下文中呈现结果：

• 删除率。 显示所选时间粒度的 dropped / (dropped + success)。
• 随时间推移的请求和依赖关系分析。 按应用程序中项 success 的值拆分请求和依赖项遥测，然后显示 “已发送 ”与 “已删除” 在单独的条形图中：
  • 成功并发送和已删除。 此图表显示应用程序成功记录的请求项和依赖项。 图表将导出程序发送到 Application Insights 的项目与导出程序删除的项进行比较。
  • 失败并发送与已删除。 比较应用程序记录为失败的项目，以及导出程序发送的项目与导出程序删除的同一类别中的项目。 已失败，已删除中的峰值通常表示暂时性服务问题、限制或配置问题。
  • 使用删除原因、删除代码和 SDK 版本筛选器来隔离原因。 例如，如果“失败、删除”增加，请查看 429 限制或 401 和 403 身份验证问题。
• 时间桶向下钻取。 选择一个存储桶将打开一个细分视图，其中包含该期间的主要删除原因和代码。
• 一段时间内导出结果。 绘制成功次数、重试次数和丢弃次数。

排查意外遥测行为问题

使用代码确定发生了什么以及接下来要执行的操作。 工作簿标注指示首先查找的位置。

诊断删除代码

导出程序为无法交付的项目设置 drop.code 。 使用以下指南。

查看客户端删除代码

查看引入终结点 HTTP 状态代码

诊断重试代码

导出程序会为计划稍后发送的项目设置 retry.code。 重试表示投递尝试尚未成功，而非最终删除。

理解重试机制

每当导出程序计划再次发送遥测时，计数器 Item_Retry_Count 就会增加。 它反映了尝试，而不是最终结果。 计数器永远不会减少。 若要了解交付健康状况，请将此指标与成功和丢弃的系列结合使用。

解释趋势

• 将上升的重试行本身视为信号，而不是数据丢失。 项稍后即可成功发送。
• 将重试次数与成功进行比较。 如果在重试次数激增后成功恢复，则此问题是暂时性的。
• 将重试次数与已删除进行比较。 如果重试次数上升，而丢包保持接近零，则导出器会进行缓冲并恢复。
• 调查持续高重试，但成功率或下降。 此模式表示阻塞问题。 使用 恢复成功。

按代码调查

按 retry.code 拆分重试指标以确定重试的原因。

还原成功

如果重试次数继续增加且成功无法恢复，请转向查看失败代码以找到阻塞原因。 从配置和配额问题开始，例如 402（每日上限）、401 或 403（身份验证或权限），以及客户端存储问题，例如 CLIENT_PERSISTENCE_CAPACITY、CLIENT_READONLY 或 CLIENT_STORAGE_DISABLED。 修复根本原因，然后确认丢包率降为零，并在接下来的时间间隔内成功率上升。

估算成本和数据量

SDK 统计数据发送汇总的 customMetrics 记录。 工作负载发布的是计数器而不是每个遥测项，因此相对于应用程序遥测，数据量保持较低。 这些记录将作为 customMetrics 的标准 Application Insights 数据提取进行计费，并遵循保留设置。 导出程序会通过现有的引入渠道发送计数器。

使用规划公式

Estimated records per hour per instance ≈
  (#metrics emitted per interval)
  × (3600 / interval_seconds)
  × (distinct dimension combinations you use)

默认间隔为 15 分钟 ()interval_seconds = 900。 请使用 APPLICATIONINSIGHTS_SDKSTATS_EXPORT_INTERVAL 配置其他间隔。

在默认工作簿之外使用 SDK 统计数据

可以将 SDK 统计信息自定义指标与其他Azure Monitor功能一起使用。

• Azure Data Explorer
• Log Analytics 通过 customMetrics 表来实现
• 警报
• Power BI
• 指标探索器

Azure Data Explorer中的查询

以下是 Kusto 查询语言 (KQL) 参考示例。

导出结果与时间

let g = 15m; // align with export interval for clearer charts
customMetrics
| where name in ("Item_Success_Count", "Item_Dropped_Count", "Item_Retry_Count")
| summarize
    success = sumif(todouble(value), name == "Item_Success_Count"),
    dropped = sumif(todouble(value), name == "Item_Dropped_Count"),
    retry   = sumif(todouble(value), name == "Item_Retry_Count")
    by bin(timestamp, g)

随时间推移的比率

let g = 15m;
customMetrics
| where name in ("Item_Success_Count", "Item_Dropped_Count", "Item_Retry_Count")
| summarize
    success = sumif(todouble(value), name == "Item_Success_Count"),
    dropped = sumif(todouble(value), name == "Item_Dropped_Count"),
    retry   = sumif(todouble(value), name == "Item_Retry_Count")
    by bin(timestamp, g)
| extend drop_rate = dropped / iff((success + dropped) == 0.0, 1.0, (success + dropped))
| extend retry_to_attempt_ratio = retry / iff((success + dropped) == 0.0, 1.0, (success + dropped))
| project timestamp, drop_rate, retry_to_attempt_ratio

随时间推移的请求和依赖关系分析（复制堆叠条形图）

let g = 15m;
// Successful request or dependency telemetry: sent vs dropped
let sent_success = (requests
| where success == true
| summarize c = count() by bin(timestamp, g)
| union (dependencies | where success == true | summarize c = count() by bin(timestamp, g))
| summarize sent = sum(c) by timestamp);
let dropped_success = (customMetrics
| where name == "Item_Dropped_Count"
| extend telemetry_type = tostring(customDimensions["telemetry_type"]),
        telemetry_success = tostring(customDimensions["telemetry_success"])
| where telemetry_type in ("REQUEST","DEPENDENCY") and telemetry_success == "true"
| summarize dropped = sum(todouble(value)) by bin(timestamp, g));
sent_success
| join kind=fullouter dropped_success on timestamp
| project timestamp, ["Successful - Sent"] = todouble(sent), ["Successful - Dropped"] = todouble(dropped)
| order by timestamp asc;

// Failed request or dependency telemetry: sent vs dropped
let sent_failed = (requests
| where success == false
| summarize c = count() by bin(timestamp, g)
| union (dependencies | where success == false | summarize c = count() by bin(timestamp, g))
| summarize sent = sum(c) by timestamp);
let dropped_failed = (customMetrics
| where name == "Item_Dropped_Count"
| extend telemetry_type = tostring(customDimensions["telemetry_type"]),
        telemetry_success = tostring(customDimensions["telemetry_success"])
| where telemetry_type in ("REQUEST","DEPENDENCY") and telemetry_success == "false"
| summarize dropped = sum(todouble(value)) by bin(timestamp, g));
sent_failed
| join kind=fullouter dropped_failed on timestamp
| project timestamp, ["Failed - Sent"] = todouble(sent), ["Failed - Dropped"] = todouble(dropped)
| order by timestamp asc

使用代码删除原因摘要

customMetrics
| where name == "Item_Dropped_Count"
| extend drop_reason = tostring(customDimensions["drop.reason"]),
        drop_code   = tostring(customDimensions["drop.code"])
| summarize total_dropped = sum(todouble(value)) by drop_reason, drop_code
| order by total_dropped desc

创建警报

创建用于监视比率或特定代码的日志警报。

// Drop rate over 5 minutes
let window = 5m;
customMetrics
| where timestamp >= ago(window)
| where name in ("Item_Success_Count", "Item_Dropped_Count")
| summarize
    success = sumif(todouble(value), name == "Item_Success_Count"),
    dropped = sumif(todouble(value), name == "Item_Dropped_Count")
| extend drop_rate = dropped / iff((success + dropped) == 0.0, 1.0, (success + dropped))
| project drop_rate

// Over-quota daily cap (HTTP 402) in the last 10 minutes
let window = 10m;
customMetrics
| where timestamp >= ago(window)
| where name == "Item_Dropped_Count"
| extend drop_code = tostring(customDimensions["drop.code"])
| summarize dropped_402 = sum(todouble(value)) by drop_code
| where drop_code == "402" and dropped_402 > 0
| project dropped_402

使用Power BI

使用 Azure Monitor Logs 连接器将这些指标引入 Power BI。

// Drop and retry ratios by hour
let window = 14d;
let g = 1h;
customMetrics
| where timestamp >= ago(window)
| where name in ("Item_Success_Count", "Item_Dropped_Count", "Item_Retry_Count")
| summarize
    success = sumif(todouble(value), name == "Item_Success_Count"),
    dropped = sumif(todouble(value), name == "Item_Dropped_Count"),
    retry   = sumif(todouble(value), name == "Item_Retry_Count")
    by bin(timestamp, g)
| extend drop_rate = dropped / iff((success + dropped) == 0.0, 1.0, (success + dropped))
| extend retry_to_attempt_ratio = retry / iff((success + dropped) == 0.0, 1.0, (success + dropped))
| order by timestamp asc

// Dropped items by reason
let window = 14d;
let g = 1h;
customMetrics
| where timestamp >= ago(window)
| where name == "Item_Dropped_Count"
| extend drop_reason = tostring(customDimensions["drop.reason"])
| summarize dropped = sum(todouble(value)) by bin(timestamp, g), drop_reason
| order by timestamp asc

使用指标浏览器

在指标中绘制这些 SDK 统计信息图表。

1. 打开 Application Insights 资源。
2. 打开“指标”。
3. 对于“指标命名空间”，请选择“基于日志的指标”。
4. 对于 指标，请选择以下项之一：
   • Item_Success_Count
   • Item_Dropped_Count
   • Item_Retry_Count
5. （可选）将 聚合 设置为 和 以计算时间粒度总计。
6. 使用拆分依据进行调查。 常见拆分：
   • drop.reason、drop.code
   • telemetry_type、sdkVersion
   • cloud_RoleName、cloud_RoleInstance

将 SDK 统计信息计数与日志进行比较

不要期望这些计数器的值与 requests 或 dependencies 等表中的项目计数相等。 出现差异的原因如下：

• 汇总时间。 统计数据按间隔和批次进行汇总。 日志存储的是单个项目，因此跨不同时段粒度的计数可能会发生漂移。
• 采样和处理器。 SDK 应用采样和任何丢弃或修改遥测的处理器后，统计计数项目。 日志反映引入终结点接受的内容。
• 部分成功。 引入终结点可以接受批次中的一部分，并拒绝其余部分。 导出器会在同一个时间区间内，将被接受的项记录为成功，而将被拒绝的项记录为删除。
• 本地缓冲。 当导出程序进行重试时，它可以在稍后发送已缓冲的项。 统计信息所分配的删除、重试或成功计数的时间，并不总是与原始遥测数据的事件时间相匹配。
• 超过配额或每日上限。 当资源超过其每日上限时，引入终结点将返回错误，系统会删除导出程序记录。 在上限窗口中，相应的应用程序遥测不会显示在日志中。
• 范围。 统计信息涵盖导出程序行为。 日志涵盖端到端遥测数据，包括不影响导出程序成功的字段。

从预览版 SDK 数据升级

如果在预览版期间测试了 SDK 统计信息，请升级到正式版 （GA） SDK 版本时更新环境变量、查询、警报和仪表板。

更新环境变量

• 删除环境变量 APPLICATIONINSIGHTS_SDKSTATS_ENABLED_PREVIEW。
• 将 APPLICATIONINSIGHTS_SDKSTATS_DISABLED=true 设置为停止发送 SDK 指标数据。
• 如果同时设置了APPLICATIONINSIGHTS_SDKSTATS_DISABLED和APPLICATIONINSIGHTS_SDKSTATS_DISABLED，则预期APPLICATIONINSIGHTS_SDKSTATS_ENABLED_PREVIEW优先。

更新指标名称

预览版 SDK 会发出不同的指标名称。 更新引用预览指标名称的日志查询、警报、仪表板和图表。

SDK 统计信息工作簿汇总预览和 GA 指标名称。

在升级期间使用混合版本查询

如果环境同时包含预览版和 GA SDK 版本，请使用聚合两个名称集的查询。 升级所有实例后，从查询和警报中删除预览指标名称。

let g = 15m;
customMetrics
| where name in (
    "Item_Success_Count", "Item_Dropped_Count", "Item_Retry_Count",
    "preview.item.success.count", "preview.item.dropped.count", "preview.item.retry.count"
  )
| summarize
    success = sumif(todouble(value), name in ("Item_Success_Count", "preview.item.success.count")),
    dropped = sumif(todouble(value), name in ("Item_Dropped_Count", "preview.item.dropped.count")),
    retry   = sumif(todouble(value), name in ("Item_Retry_Count", "preview.item.retry.count"))
    by bin(timestamp, g)