采样替代 - 适用于 Java 的 Azure Monitor Application Insights

项目
07/01/2024

注意

从 3.5.0 开始，提供正式版的采样替代功能。

采样替代允许你替代默认采样百分比，例如：

将采样百分比设置为 0（或某个小值）以检查干扰运行状况。
将采样百分比设置为 0（或一些小值）以调用干扰依赖项。
对于重要的请求类型（例如，/login），将采样百分比设置为 100，即使默认的采样配置为低于此值也是如此。

术语

在了解采样替代之前，应了解术语“范围”。范围是一个表示下列事项的通用术语：

传入请求。
传出依赖项（例如，对另一个服务的远程调用）。
进程内依赖项（例如，由服务的子组件所做的工作）。

对于采样替代，这些范围组件非常重要：

属性

范围属性表示给定请求或依赖项的标准属性和自定义属性。

入门

首先，创建一个名为“applicationinsights.json”的配置文件。将其保存在与“applicationinsights-agent-*.jar”相同的目录中。请使用以下模版。

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10,
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 0
      },
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 100
      }
    ]
  }
}

工作原理

telemetryType (Application Insights 3.4.0 中的 telemetryKind) 必须是 request、dependency、trace (日志) 或 exception。

当范围启动时，将使用范围的类型和当时存在于其上的属性来检查是否有任何采样替代匹配项。

匹配可以是 strict 或 regexp。正则表达式匹配是针对整个属性值执行的，因此如果要匹配其中任何位置包含 abc 的值，则需要使用 .*abc.*。采样替代可以指定多个属性条件，在这种情况下，所有属性条件都必须匹配，才能使采样替代匹配。

如果其中一个采样替代匹配，则使用其采样百分比来确定是否对该范围进行采样。

只使用第一个匹配的采样替代。

如果没有匹配的采样替代：

如果是跟踪中的第一个范围，则使用顶级采样配置。
如果不是跟踪中的第一个范围，则使用父采样决策。

示例：取消收集运行状况检查的遥测数据

这一示例会取消收集所有对 /health-checks 的请求的遥测数据。

这一示例也会取消收集通常在 /health-checks 下收集的任何下游范围（依赖项）。

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/health-check",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

示例：取消收集干扰依赖项调用的遥测数据

这一示例会取消收集所有 GET my-noisy-key redis 调用的遥测数据。

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "db.system",
            "value": "redis",
            "matchType": "strict"
          },
          {
            "key": "db.statement",
            "value": "GET my-noisy-key",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

示例：收集重要请求类型的 100% 遥测数据

这一示例会收集 /login 的全部遥测数据。

由于下游范围（依赖项）遵循父级的采样决策（缺少该下游范围的任何采样替代），因此也会为所有“/login”请求收集这些范围。

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10
  },
  "sampling": {
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/login",
            "matchType": "strict"
          }
        ],
        "percentage": 100
      }
    ]
  }
}

可用于采样的 Span 属性

Span 属性名称基于 OpenTelemetry 语义约定。（HTTP、消息传送、数据库、RPC）

https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md

注意

若要查看 Application Insights Java 为应用程序捕获的确切属性集，请将自诊断级别设置为调试，并查找以文本“导出 Span”开头的调试消息。

注意

只有在范围开始时设置的属性才可用于采样，因此无法通过 OpenTelemetry Java 扩展来筛选稍后捕获的 http.response.status_code 或请求持续时间等属性。下面是一个示例扩展，它根据请求持续时间筛选范围。

故障排除

如果使用了 regexp，而采样替代不起作用，请尝试使用 .* 正则表达式。如果采样现在起作用，则表示第一个正则表达式有问题，请阅读此正则表达式文档。

如果它不适用于 .*，则 application-insights.json file 中可能存在语法问题。请查看 Application Insights 日志，留意是否存在警告消息。

通过