Application Insights 遥测数据模型

项目
07/24/2024

Application Insights 将遥测从 Web 应用程序发送到 Azure 门户，以便分析应用程序的性能和使用情况。标准化遥测模型可以创建不依赖于平台和语言的监测。

Application Insights 收集的数据为典型的应用程序执行模式建模。

使用以下类型的遥测监视应用的执行情况。 Web 应用程序框架中的 Application Insights SDK 会自动收集以下三种类型：

请求：生成该类型的遥测用以记录应用接收的请求。例如，Application Insights Web SDK 会自动为 Web 应用接收到的每个 HTTP 请求生成请求遥测项。

“操作”由处理请求的执行线程组成。还可以编写代码监视其他类型的操作，例如 Web 作业或函数中定期处理数据的“唤醒”操作。每个操作都有一个 ID。此 ID 可用于对应用处理请求时生成的所有遥测进行分组。每个操作无论成功或失败都需要持续一段时间。
异常：通常表示导致操作失败的异常。
依赖项：表示从应用到外部服务或存储（如 REST API 或 SQL）的调用。在 ASP.NET 中，对 SQL 的依赖项调用由 System.Data 定义。对 HTTP 终结点的调用由 System.Net 定义。

Application Insights 为自定义遥测提供了三种数据类型：

跟踪：直接使用或通过适配器使用熟悉的检测框架（如 Log4Net 或 System.Diagnostics）实现诊断日志记录。
事件：通常用于捕获用户与服务的交互，以分析使用模式。
指标：用于报告定期标量度量。

每个遥测项目均可定义上下文信息，如应用程序版本或用户会话 ID。上下文是一组强类型化字段，可解锁某些方案。正确初始化应用程序版本后，Application Insights 可检测应用程序行为中与重新部署相关的新模式。

可以使用会话 ID 计算出现中断或问题对用户造成的影响。错误跟踪或关键异常可计算特定失败依赖项的不同会话 ID 值计数，较好地反映影响。

Application Insights 遥测模型定义了将遥测与它所属的操作进行关联的方式。例如，请求可以发出 SQL 数据库调用并记录诊断信息。可为那些要绑回请求遥测的遥测项设置关联上下文。

架构改进

Application Insights 数据模型采用基本的结构，不过，它能够非常有效地为应用程序遥测建模。我们将努力保持该模型的精简结构，以便支持基本方案，并让用户根据高级用途扩展架构。

若要报告数据模型或架构问题以及建议，请使用 GitHub 存储库。

请求

Application Insights 中的请求遥测项表示由应用程序的外部请求触发的执行的逻辑序列。每个请求执行均由包含所有执行参数的唯一 id 和 url 标识。

可以按逻辑 name 将请求分组，并定义此请求的 source。代码执行的结果可能是 success 或 fail，并且具有特定的 duration。可以通过使用 resultCode 对成功和失败执行进一步分步。请求遥测的开始时间在信封级别定义。

请求遥测使用自定义的 properties 和 measurements 支持标准可扩展性模型。

注意

对检测密钥引入的支持将于 2025 年 3 月 31 日结束。检测密钥引入功能将会继续工作，但我们将不再为该功能提供更新或支持。转换为连接字符串，以利用新功能。

名称

此字段为请求的名称，它表示用于处理该请求的代码路径。较小的基数值对请求分组更有利。对于 HTTP 请求，该名称表示 HTTP 方法和 URL 路径模板，例如，不带实际 id 值的 GET /values/{id}。

对于字母大小写，Application Insights Web SDK 会“按原样”发送请求名称。 UI 上的分组区分大小写，因此 GET /Home/Index 被视为不同于 GET /home/INDEX，即使两者通常生成相同的控制器和操作执行。原因在于，URL 往往区分大小写。你可能想要确定所有 404 错误是否都发生在以大写形式键入的 URL 上。可在博客文章中详细了解 ASP.Net Web SDK 如何处理请求名称集合。

最大长度：1,024 个字符

ID

ID 是请求调用实例的标识符。它用于在请求与其他遥测项之间建立关联。 ID 应该全局唯一。有关详细信息，请参阅 Application Insights 中的遥测关联。

最大长度：128 个字符

URL

URL 是包含所有查询字符串参数的请求 URL。

最大长度：2,048 个字符

源

源是请求的源。示例包括调用方的检测密钥或调用方的 IP 地址。有关详细信息，请参阅 Application Insights 中的遥测关联。

最大长度：1,024 个字符

持续时间

请求持续时间的格式为 DD.HH:MM:SS.MMMMMM。它必须是正数且小于 1000 天。此字段是必填字段，因为请求遥测表示具有开始和结束时间的操作。

响应代码

响应代码是请求执行的结果。它是 HTTP 请求的 HTTP 状态代码。对于其他请求类型，它可能是 HRESULT 值或异常类型。

最大长度：1,024 个字符

成功

成功指示调用是成功还是失败。此字段为必需字段。如果请求未显式设置为 false，将它将视为成功。如果操作被异常中断或者返回错误结果代码，请将此值设置为 false。

对于 Web 应用程序，如果响应代码小于 400 或等于 401，则 Application Insights 会将请求定义为成功。但是，在某些情况下，此默认映射与应用程序的语义不匹配。

响应代码 404 可能指示“无记录”，这可能是常规流的一部分。它也可能指示链接断开。对于断开的链接，可以实现更高级的逻辑。仅当通过分析 URL 引用站点确定这些断开的链接位于同一站点时，才可以将这些链接标记为失败。或者，在从公司的移动应用程序访问这些链接时，可将它们标记为失败。同样，在从不支持重定向的客户端访问这些链接时，301 和 302 将指示失败。

部分接受的内容 206 可能指示整个请求失败。例如，Application Insights 终结点可能以单个请求的形式接收一批遥测项。未成功处理该批中的某些项时，它将返回 206。 206 比率提高指示出现了需要调查的问题。类似的逻辑适用于 207 多状态，其中的成功结果可能是不同响应代码的最差结果。

自定义属性

自定义属性的名称-值集合：该集合用于通过自定义维度来扩展标准遥测。示例为部署槽位，该槽位生成特定于遥测或遥测项的属性，例如订单号。

最大密钥长度：150
最大值长度：8,192

自定义度量值

自定义度量值集合：使用此集合报告与遥测项关联的命名度量值。典型用例如下：

依赖项遥测有效负载的大小。
由请求遥测处理的队列项数。
客户完成事件遥测的向导步骤所花费的时间。

可以在 Application Analytics 中查询自定义度量值：

customEvents
| where customMeasurements != ""
| summarize avg(todouble(customMeasurements["Completion Time"]) * itemCount)

注意

与所属遥测项关联的自定义度量值。它们受到包含这些度量值的遥测项的采样的影响。使用指标遥测跟踪其值独立于其他遥测类型的度量值。
不要对自定义度量使用字符串值。仅支持数值。

最大密钥长度：150

依赖项

Application Insights 中的依赖项遥测表示受监视组件与远程组件（如 SQL 或 HTTP 终结点）的交互。

名称

此字段为通过此依赖项调用启动的命令的名称。它的基数值低。示例包括存储过程名称和 URL 路径模板。

ID

ID 是依赖项调用实例的标识符。它是用于与此依赖项调用所对应的请求遥测项关联。有关详细信息，请参阅 Application Insights 中的遥测关联。

数据

此字段是此依赖项调用启动的命令。示例包括使用所有查询参数的 SQL 语句和 HTTP URL。

类型

此字段是依赖项类型名称。低基数值，用于对依赖项进行逻辑分组和解释 commandName 和 resultCode 等其他字段。示例包括 SQL、Azure 表和 HTTP。

目标

此字段是依赖项调用的目标站点。示例包括服务器名称和主机地址。有关详细信息，请参阅 Application Insights 中的遥测关联。

持续时间

请求持续时间的格式为 DD.HH:MM:SS.MMMMMM。此值必须小于 1000 天。

结果代码

此字段是依赖项调用的结果代码。示例包括 SQL 错误代码和 HTTP 状态代码。

成功

此字段用于指示调用成功或失败。

自定义属性

自定义属性的名称-值集合：该集合用于通过自定义维度来扩展标准遥测。示例为部署槽位，该槽位生成特定于遥测或遥测项的属性，例如订单号。

最大密钥长度：150
最大值长度：8,192

自定义度量值

自定义度量值集合：使用此集合报告与遥测项关联的命名度量值。典型用例如下：

依赖项遥测有效负载的大小。
由请求遥测处理的队列项数。
客户完成事件遥测的向导步骤所花费的时间。

可以在 Application Analytics 中查询自定义度量值：

customEvents
| where customMeasurements != ""
| summarize avg(todouble(customMeasurements["Completion Time"]) * itemCount)

注意

与所属遥测项关联的自定义度量值。它们受到包含这些度量值的遥测项的采样的影响。使用指标遥测跟踪其值独立于其他遥测类型的度量值。
不要对自定义度量使用字符串值。仅支持数值。

最大密钥长度：150

异常

在 Application Insights 中，异常实例表示在受监视应用程序的执行过程中出现的已处理或未经处理的异常。

问题 ID

问题 ID 用于标识代码中引发异常的位置。它用于对异常进行分组。通常为异常类型和调用堆栈中某个函数的组合。

最大长度：1,024 个字符

严重性级别

此字段是跟踪严重性级别。该值可以是 Verbose、Information、Warning、Error 或 Critical。

异常详细信息

（将进行扩展）

自定义属性

自定义属性的名称-值集合：该集合用于通过自定义维度来扩展标准遥测。示例为部署槽位，该槽位生成特定于遥测或遥测项的属性，例如订单号。

最大密钥长度：150
最大值长度：8,192

自定义度量值

自定义度量值集合：使用此集合报告与遥测项关联的命名度量值。典型用例如下：

依赖项遥测有效负载的大小。
由请求遥测处理的队列项数。
客户完成事件遥测的向导步骤所花费的时间。

可以在 Application Analytics 中查询自定义度量值：

customEvents
| where customMeasurements != ""
| summarize avg(todouble(customMeasurements["Completion Time"]) * itemCount)

注意

与所属遥测项关联的自定义度量值。它们受到包含这些度量值的遥测项的采样的影响。使用指标遥测跟踪其值独立于其他遥测类型的度量值。
不要对自定义度量使用字符串值。仅支持数值。

最大密钥长度：150

跟踪

Application Insights 中的跟踪遥测表示 printf 样式的文本搜索跟踪语句。 Log4Net、NLog 和其他基于文本的日志文件条目将转换成此类型的实例。跟踪没有作为扩展性的度量。

Message

跟踪消息。

最大长度：32,768 个字符

严重性级别

跟踪严重性级别。

值：Verbose、Information、Warning、Error 和 Critical

自定义属性

自定义属性的名称-值集合：该集合用于通过自定义维度来扩展标准遥测。示例为部署槽位，该槽位生成特定于遥测或遥测项的属性，例如订单号。

最大密钥长度：150
最大值长度：8,192

事件

可以在 Application Insights 中创建事件遥测项，表示应用程序中发生的事件。通常它是用户交互，如按钮单击或订单结账。它还可以是应用程序生命周期事件，如初始化或配置更新。

事件在语义上不一定与请求关联。如果使用得当，事件遥测比请求或跟踪更重要。事件表示业务遥测，应该受到单独的、较少侵入性的采样。

名称

事件名称：若要允许适当的分组和有用的指标，请限制应用程序，使其生成少量单独的事件名称。例如，不要为事件中每个生成的实例使用单独的名称。

最大长度：512 个字符

自定义属性

自定义属性的名称-值集合：该集合用于通过自定义维度来扩展标准遥测。示例为部署槽位，该槽位生成特定于遥测或遥测项的属性，例如订单号。

最大密钥长度：150
最大值长度：8,192

自定义度量值

自定义度量值集合：使用此集合报告与遥测项关联的命名度量值。典型用例如下：

依赖项遥测有效负载的大小。
由请求遥测处理的队列项数。
客户完成事件遥测的向导步骤所花费的时间。

可以在 Application Analytics 中查询自定义度量值：

customEvents
| where customMeasurements != ""
| summarize avg(todouble(customMeasurements["Completion Time"]) * itemCount)

注意

与所属遥测项关联的自定义度量值。它们受到包含这些度量值的遥测项的采样的影响。使用指标遥测跟踪其值独立于其他遥测类型的度量值。
不要对自定义度量使用字符串值。仅支持数值。

最大密钥长度：150

指标

Application Insights 支持两种类型的指标遥测：单个度量和预聚合指标。单个度量只是一个名称和值。预聚合指标指定在聚合时间间隔内指标的最小和最大值，以及它的标准偏差。

预聚合指标遥测假定聚合期间为一分钟。

Application Insights 支持多个已知的指标名称。这些指标置于 performanceCounters 表中。

下表显示了表示系统和进程计数器的指标。

.NET 名称	与平台无关的名称	说明
`\Processor(_Total)\% Processor Time`	工作正在进行...	总计算机 CPU 百分比。
`\Memory\Available Bytes`	工作正在进行...	显示可用于计算机上运行的进程的物理内存量（以字节为单位）。通过对清零、可用和备用内存列表上的空间量进行求和来进行计算。可用内存可供使用。归零内存由零填充的内存页面组成，用于防止后续进程看到前一个进程使用的数据。备用内存是指已从进程的工作集（其物理内存）中删除并路由到磁盘的内存，路由到磁盘，但仍可供召回。请参阅内存对象。
`\Process(??APP_WIN32_PROC??)\% Processor Time`	工作正在进行...	托管应用程序的进程的 CPU 百分比。
`\Process(??APP_WIN32_PROC??)\Private Bytes`	工作正在进行...	托管应用程序的进程所占用的内存量。
`\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec`	工作正在进行...	托管应用程序的进程运行的 I/O 操作速率。
`\ASP.NET Applications(??APP_W3SVC_PROC??)\Requests/Sec`	工作正在进行...	应用程序处理的请求速率。
`\.NET CLR Exceptions(??APP_CLR_PROC??)\# of Exceps Thrown / sec`	工作正在进行...	应用程序引发的异常速率。
`\ASP.NET Applications(??APP_W3SVC_PROC??)\Request Execution Time`	工作正在进行...	平均请求执行时间。
`\ASP.NET Applications(??APP_W3SVC_PROC??)\Requests In Application Queue`	工作正在进行...	队列中等待处理的请求数。

有关指标 REST API 的详细信息，请参阅指标 - 获取。

名称

此字段是指想要在 Application Insights 门户和 UI 中看到的指标的名称。

值

此字段是单个度量值。它是要聚合的各个度量值的总和。

计数

此字段是指聚合指标的指标权重。不应为度量设置。

Min

此字段是聚合指标的最小值。不应为度量设置。

Max

此字段是聚合指标的最大值。不应为度量设置。

标准偏差

此字段是聚合指标的标准偏差。不应为度量设置。

自定义属性

如果指标的自定义属性 CustomPerfCounter 设置为 true，则表明该指标表示 Windows 性能计数器。这些指标放置在 performanceCounters 表中，而不是放置在 customMetrics 中。此外还分析此指标的名称，以提取类别、计数器和实例名称。

自定义属性的名称-值集合：该集合用于通过自定义维度来扩展标准遥测。示例为部署槽位，该槽位生成特定于遥测或遥测项的属性，例如订单号。

最大密钥长度：150
最大值长度：8,192

页面视图

当应用程序用户打开受监视应用程序的新页面时，会记录 PageView 遥测数据（在 Application Insights 中）。此上下文中的 Page 是由开发人员定义为应用程序选项卡或屏幕的逻辑单元，不一定与浏览器网页加载或刷新操作相关联。可以在单页应用程序 (SPA) 的上下文中进一步理解这种差别，其中页面之间的切换与浏览器页面操作不相关。 pageViews.duration 是应用程序将页面呈现给用户所花费的时间。

注意

默认情况下，Application Insights SDK 会针对每个浏览器网页加载操作记录单个 PageView 事件，其中的 pageViews.duration 由浏览器计时填充。开发人员可以使用 trackPageView API 调用来扩展 PageView 事件的进一步跟踪。
默认日志保持期为 30 天。如果要查看较长时间的 PageView 统计信息，则必须调整设置。

在 Application Insights 中度量 browserTiming

新式浏览器使用 Performance API 公开页面加载操作的度量。 Application Insights 通过将相关计时合并到以下处理时间定义所定义的标准浏览器指标来简化这些度量：

客户端 <--> DNS：客户端访问 DNS 来解析网站主机名，DNS 用 IP 地址做出响应。
客户端 <--> Web 服务器：客户端创建 TCP，然后与 Web 服务器进行 TLS 握手。
客户端 <--> Web 服务器：客户端发送请求有效负载，等待服务器执行请求，然后接收第一个响应数据包。
客户端 <-- Web 服务器：客户端从 Web 服务器接收余下的响应有效负载字节。
客户端：客户端现在收到了完整的响应有效负载，必须在浏览器中呈现内容并加载 DOM。
browserTimings/networkDuration = #1 + #2
browserTimings/sendDuration = #3
browserTimings/receiveDuration = #4
browserTimings/processingDuration = #5
browsertimings/totalDuration = #1 + #2 + #3 + #4 + #5
pageViews/duration
- PageView 持续时间来自浏览器的性能计时接口 PerformanceNavigationTiming.duration。
- 如果 PerformanceNavigationTiming 可用，则使用该持续时间。
  
  如果不是，使用已弃用的 PerformanceTiming 接口，并计算 NavigationStart 和 LoadEventEnd 之间的增量。
- 开发人员在使用 trackPageView API 调用记录自定义 PageView 事件时指定持续时间值。

上下文

每个遥测项可能都有一个强类型化上下文字段。每个字段均会启用特定监视方案。使用自定义属性集合存储自定义或特定于应用程序的上下文信息。

应用程序版本

应用程序上下文字段中的信息总是与发送遥测的应用程序有关。应用程序版本用于分析应用程序行为的趋势变化及其与部署的关联。

最大长度：1024

客户端 IP 地址

此字段是客户端设备的 IP 地址。支持 IPV4 和 IPV6。从服务发送遥测数据时，位置上下文与在服务中发起操作的用户有关。 Application Insights 从客户端 IP 中提取地理位置信息，然后将其截断。无法将客户端 IP 本身用作用户的可识别信息。

最大长度：46

设备类型

最初，该字段用于指示应用程序的用户使用的设备类型。现在，其主要用于区分设备类型为 Browser 的 JavaScript 遥测与设备类型为 PC 的服务器端遥测。

最大长度：64

Operation ID

此字段是根操作的唯一标识符。此标识符允许跨多个组件对遥测分组。有关详细信息，请参阅遥测关联。操作 ID 由请求或页面视图创建。其他所有遥测将此字段设置为包含请求或页面视图的值。

最大长度：128

父操作 ID

此字段是遥测项的直接父级的唯一标识符。有关详细信息，请参阅遥测关联。

最大长度：128

操作名称

此字段是操作的的名称（组）。操作名称由请求或页面视图创建。其他所有遥测项将此字段设置为包含请求或页面视图的值。操作名称用于查找一组操作的所有遥测项（例如，GET Home/Index）。此上下文属性用于回答“此页面的典型异常有哪些？”等问题。

最大长度：1024

操作的综合源

此字段是合成源的名称。来自应用程序的一些遥测可能代表综合流量。可能是索引网站的 Web 爬网程序、站点可用性测试或来自诊断库（如 Application Insights SDK 本身）的跟踪。

最大长度：1024

会话 ID

会话 ID 是用户与应用交互的实例。会话上下文字段中的信息总是与用户有关。从服务发送遥测时，会话上下文与在服务中启用操作的用户有关。

最大长度：64

匿名用户 ID

匿名用户 ID (User.Id) 代表应用程序的用户。从服务发送遥测时，用户上下文与在服务中启用操作的用户有关。

采样是最小化遥测收集量的一种技术。采样算法尝试在所有相关遥测内部或外部采样。匿名用户 ID 用于采样分数生成，因此匿名用户 ID 应该是一个足够随机的值。

注意

匿名用户 ID 的计数与唯一应用程序用户的数量不同。匿名用户 ID 的计数通常更高，因为每当用户在不同的设备或浏览器中打开你的应用时或清理浏览器 Cookie 时，都会分配一个新的唯一匿名用户 ID。此计算可能会导致多次统计相同的实际用户。

用户 ID 可以与会话 ID 交叉进行引用，以提供唯一的遥测维度，并在会话持续时间内建立用户活动。

使用匿名用户 ID 存储用户名是字段误用。使用已经过身份验证的用户 ID。

最大长度：128

已经过身份验证的用户 ID

经过身份验证的用户 ID 与匿名用户 ID 相反。此字段表示具有易记名称的用户。默认情况下，仅使用 ASP.NET Framework SDK 的 AuthenticatedUserIdTelemetryInitializer 收集此 ID。

使用 Application Insights SDK 初始化经过身份验证的用户 ID，该 ID 具有跨浏览器和设备永久标识用户的值。通过这种方式，所有遥测项都归属于该唯一 ID。使用此 ID 可以查询针对特定用户收集的所有遥测数据（根据采样配置和遥测数据筛选）。

用户 ID 可以与会话 ID 交叉进行引用，以提供唯一的遥测维度，并在会话持续时间内建立用户活动。

最大长度：1024

帐户 ID

在多租户应用程序中，帐户 ID 是用户使用的租户帐户 ID 或名称。当用户 ID 和已经过身份验证的用户 ID 不足时，它用于进一步的用户细分。例如，Azure 门户的订阅 ID 或博客平台的博客名称。

最大长度：1024

云角色

此字段是应用程序所属的角色的名称。它直接映射到 Azure 中的角色名称。也可用于区分单个应用程序包含的微服务。

最大长度：256

云角色实例

此字段是正在运行应用程序的实例的名称。例如，它是本地的计算机名称或 Azure 的实例名称。

最大长度：256

内部：SDK 版本

有关详细信息，请参阅 SDK 版本。

最大长度：64

内部：节点名称

此字段表示用于计费的节点名称。使用该字段替代节点的标准检测。

最大长度：256

常见问题

本部分提供常见问题的解答。

如何衡量监视活动的影响？

PageView 遥测包括 URL，你可以使用 Kusto 中的正则表达式函数分析 UTM 参数。

如果用户或企业禁止在浏览器设置中发送用户代理，则此数据偶尔可能会缺失或不准确。用户代理分析程序正则表达式可能未包含所有设备信息。或者 Application Insights 可能未采用最新更新。

为什么自定义度量会成功且没有错误，但没有显示日志？

如果使用字符串值，可能会发生这种情况。自定义度量只能使用数值。

后续步骤

了解如何使用用于处理自定义事件和指标的 Application Insights API，包括：

为此项设置依赖项跟踪：

.NET
Java

若要了解详细信息，请访问以下链接：

查看 Application Insights 支持的平台。
查看标准上下文属性集合配置。
浏览 Application Insights 中的 .NET 跟踪日志。
浏览 Application Insights 中的 Java 跟踪日志。
了解 Azure Functions 与 Application Insights 的内置集成来监视函数执行。
了解如何使用 Application Insights 配置 ASP.NET Core 应用程序。
了解如何使用 Application Insights 诊断 Web 应用中的异常。
了解如何扩展和筛选遥测。
使用采样基于数据模型最小化遥测量。

通过

Application Insights 遥测数据模型

架构改进

请求

名称

ID

URL

源

持续时间

响应代码

成功

自定义属性

自定义度量值

依赖项

名称

ID

数据

类型

目标

持续时间

结果代码

成功

自定义属性

自定义度量值

异常

问题 ID

严重性级别

异常详细信息

自定义属性

自定义度量值

跟踪

Message

严重性级别

自定义属性

事件

名称

自定义属性

自定义度量值

指标

名称

值

计数

Min

Max

标准偏差

自定义属性

页面视图

在 Application Insights 中度量 browserTiming

上下文

应用程序版本

客户端 IP 地址

设备类型

Operation ID

父操作 ID

操作名称

操作的综合源

会话 ID

匿名用户 ID

已经过身份验证的用户 ID

帐户 ID

云角色

云角色实例

内部：SDK 版本

内部：节点名称

常见问题

如何衡量监视活动的影响？

为什么自定义度量会成功且没有错误，但没有显示日志？

后续步骤

其他资源