遥测处理器（预览版）- 适用于 Java 的 Azure Monitor Application Insights

项目
04/16/2024

注意

遥测处理器功能指定为预览版，因为由于属性语义约定的试验状态，无法保证各版本之间的向后兼容性。但是，该功能已经过测试，在生产环境中受支持。

Application Insights Java 3.x 可以在导出遥测数据之前处理该数据。

下面是一些用例：

屏蔽敏感数据。
有条件地添加自定义维度。
更新用于在 Azure 门户中聚合类似遥测数据的范围名称。
删除范围属性以控制数据引入成本。
筛选出某些指标以控制引入成本。

注意

如果希望删除特定（整体）范围来控制引入成本，请参阅采样替代。

术语

在了解遥测处理器之前，你应当理解术语“跨度”和“日志”。

跨度是一种遥测类型，它代表的是：

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

日志是代表以下内容的遥测类型：

从 Log4j、Logback 和 java.util.logging 捕获的日志数据

对于遥测处理器而言，以下跨度/日志组件非常重要：

名称
正文
特性

范围名称是 Azure 门户中的请求和依赖项的主显示名称。范围属性表示给定请求或依赖项的标准属性和自定义属性。

跟踪消息或正文是 Azure 门户中日志的主要显示。日志特性表示给定日志的标准属性和自定义属性。

遥测处理器类型

目前有四种类型的遥测处理器，分别是

属性处理器
范围处理器
日志处理器
指标筛选器

属性处理器可以插入、更新、删除或摘要遥测项（span 或 log）的属性。它还可以使用正则表达式从现有属性中提取一个或多个新属性。

跨度处理器可以更新请求和依赖项的遥测名称。它还可以使用正则表达式从范围名称中提取一个或多个新属性。

日志处理器可以更新日志的遥测名称。它还可以使用正则表达式从日志名称中提取一个或多个新属性。

指标筛选器可以筛选出指标，以帮助控制引入成本。

注意

目前，遥测处理器仅处理字符串类型的属性，不处理布尔或数字类型的属性。

入门

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

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        ...
      },
      {
        "type": "attribute",
        ...
      },
      {
        "type": "span",
        ...
      },
      {
        "type": "log",
        ...
      },
      {
        "type": "metric-filter",
        ...
      }
    ]
  }
}

属性处理器

属性处理器修改 span 或 log 的属性。它可以支持包括或排除 span 或 log 的功能。它接受一个操作列表，这些操作按配置文件指定的顺序执行。处理器支持以下操作：

insert
update
delete
hash
extract
mask

`insert`

insert 操作在遥测项中插入一个新属性（如果 key 尚不存在）。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "value1",
        "action": "insert"
      }
    ]
  }
]

insert 操作需要以下设置：

key
value 或 fromAttribute
action: insert

`update`

update 操作更新遥测项中的属性（如果 key 已经存在）。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "newValue",
        "action": "update"
      }
    ]
  }
]

update 操作需要以下设置：

key
value 或 fromAttribute
action: update

`delete`

delete 操作从遥测项中删除属性。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "delete"
      }
    ]
  }
]

delete 操作需要以下设置：

key
action: delete

`hash`

hash 操作哈希化 (SHA1) 现有属性值。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "hash"
      }
    ]
  }
]

hash 操作需要以下设置：

key
action: hash

`extract`

注意

只有 3.0.2 及更高版本中提供了 extract 功能。

extract 操作使用正则表达式规则将值从输入键提取到规则指定的目标键。如果目标键已存在，extract操作会替代目标键。此操作的行为类似于范围处理器 toAttributes 设置，其中，现有属性是源。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "pattern": "<regular pattern with named matchers>",
        "action": "extract"
      }
    ]
  }
]

extract 操作需要以下设置：

key
pattern
action: extract

`mask`

注意

只有 3.2.5 及更高版本中提供了 mask 功能。

mask 操作通过使用 pattern 和 replace 中指定的正则表达式规则来掩码属性值。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attributeName",
        "pattern": "<regular expression pattern>",
        "replace": "<replacement value>",
        "action": "mask"
      }
    ]
  }
]

mask 操作需要以下设置：

key
pattern
replace
action: mask

pattern 可以包含位于 ?< 和 >: 之间的一个命名组。示例：(?<userGroupName>[a-zA-Z.:\/]+)\d+？该组是 (?<userGroupName>[a-zA-Z.:\/]+)，而 userGroupName 是该组的名称。然后，pattern 可以包含同名组，该同名组放置在后跟掩码的 ${ 和 } 之间。掩码位置示例为 **：${userGroupName}**。

请参阅遥测处理器示例，查看掩码示例。

包括条件和排除条件

属性处理器支持可选的 include 和 exclude 条件。特性处理器仅应用于与其include条件（如果可用）匹配且与其exclude条件（如果可用）不匹配的遥测数据。

若要配置此选项，请在 include 和/或 exclude 下指定至少一个 matchType 以及 spanNames 或 attributes。允许在include或exclude配置中使用多个指定的条件。所有指定条件的评估结果都必须为 true 才会被视为匹配。

必填字段：
- matchType控制如何解释spanNames数组和attributes数组中的项。可能值为 regexp 和 strict。正则表达式匹配是针对整个属性值执行的，因此如果要匹配其中任何位置包含 abc 的值，则需要使用 .*abc.*。
可选字段：
- spanNames 必须至少与一个项匹配。
- attributes 指定要匹配的属性的列表。所有这些属性必须完全匹配才会被视为匹配。

注意

如果同时指定了 include 和 exclude，则会在检查 exclude 属性之前检查 include 属性。

注意

如果 include 或 exclude 配置未指定 spanNames，则将匹配条件应用于 spans 和 logs。

示例用法

"processors": [
  {
    "type": "attribute",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "redact_trace",
          "value": "false"
        }
      ]
    },
    "actions": [
      {
        "key": "credit_card",
        "action": "delete"
      },
      {
        "key": "duplicate_key",
        "action": "delete"
      }
    ]
  }
]

有关详细信息，请参阅遥测处理器示例。

范围处理器

范围处理器修改范围名称或根据范围名称修改范围的属性。它可以支持包括或排除范围的功能。

为范围命名

name 节需要 fromAttributes 设置。这些属性中的值用于创建新名称，并按配置指定的顺序进行连接。仅当范围中存在所有这些特性时，处理器才会更改范围名称。

separator 设置是可选的。此设置是字符串，可以使用拆分值。

注意

如果重命名依赖于属性处理器来修改属性，请确保在管道规范中的属性处理器之后指定范围处理器。

"processors": [
  {
    "type": "span",
    "name": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
]

从范围名称中提取属性

toAttributes 节列出了要根据其来匹配范围名称的正则表达式。它基于子表达式提取属性。

rules 设置是必需的。此设置列出了用于从范围名称中提取属性值的规则。

提取的特性名称会替换范围名称中的值。列表中的每个规则都是一个正则表达式 (regex) 模式字符串。

下面演示了提取的特性名称如何替换值：

依据正则表达式来检查范围名称。
如果正则表达式匹配，则该正则表达式的所有命名子表达式都将提取为特性。
提取的属性被添加到范围中。
每个子表达式名称成为一个属性名称。
子表达式匹配部分成为属性值。
提取的特性名称会替换范围名称中的匹配部分。如果属性已存在于范围中，则会被覆盖。

将按指定顺序针对所有规则重复此过程。每个后续规则都应用于处理上一规则后输出的范围名称。

"processors": [
  {
    "type": "span",
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

常见范围属性

本部分列出了遥测处理器可以使用的一些常见范围属性。

HTTP 范围

属性	类型	描述
`http.request.method`（曾经为 `http.method`）	string	HTTP 请求方法。
`url.full`（客户端范围）或 `url.path`（服务器范围）（曾经为 `http.url`）	string	完整的 HTTP 请求 URL（采用 `scheme://host[:port]/path?query[#fragment]` 格式）。片段通常不会通过 HTTP 传输。但如果片段是已知的，则应将其包含在内。
`http.response.status_code`（曾经为 `http.status_code`）	数字	HTTP 响应状态代码。
`network.protocol.version`（曾经为 `http.flavor`）	string	HTTP 协议的类型。
`user_agent.original`（曾经为 `http.user_agent`）	string	客户端发送的 HTTP User-Agent 标头的值。

Java Database Connectivity 范围

下表介绍了可在 JJava Database Connectivity (JDBC) 范围中使用的特性：

属性	类型	说明
`db.system`	字符串	正在使用的数据库管理系统 (DBMS) 产品的标识符。请参阅数据库操作的语义约定。
`db.connection_string`	string	用于连接到数据库的连接字符串。建议删除嵌入的凭据。
`db.user`	string	用于访问数据库的用户名。
`db.name`	string	用于报告正在访问的数据库的名称的字符串。对于用于切换数据库的命令，应当将此字符串设置为目标数据库（即使该命令失败）。
`db.statement`	字符串	正在运行的数据库语句。

包括条件和排除条件

跨度处理器支持可选的 include 和 exclude 条件。范围处理器仅应用于与其include条件（如果可用）匹配且与其exclude条件（如果可用）不匹配的遥测数据。

若要配置此选项，请在 include 和/或 exclude 下指定至少一个 matchType 以及 spanNames 或范围 attributes。允许在include或exclude配置中使用多个指定的条件。所有指定条件的评估结果都必须为 true 才会被视为匹配。

必填字段：
- matchType控制如何解释spanNames数组和attributes数组中的项。可能值为 regexp 和 strict。正则表达式匹配是针对整个属性值执行的，因此如果要匹配其中任何位置包含 abc 的值，则需要使用 .*abc.*。
可选字段：
- spanNames 必须至少与一个项匹配。
- attributes 指定要匹配的属性的列表。所有这些属性必须完全匹配才会被视为匹配。

注意

如果同时指定了 include 和 exclude，则会在检查 exclude 属性之前检查 include 属性。

示例用法

"processors": [
  {
    "type": "span",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "attributeValue1"
        }
      ]
    },
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

有关详细信息，请参阅遥测处理器示例。

日志处理器

注意

从版本 3.1.1 开始提供日志处理器。

日志处理器根据日志消息正文修改日志消息正文或日志属性。它可以支持包括或排除日志的功能。

更新日志消息正文

body 节需要 fromAttributes 设置。利用这些属性中的值来创建新的正文，并按配置指定的顺序进行连接。仅当所有这些属性都存在于日志中时，处理器才会更改日志正文。

separator 设置是可选的。此设置是一个字符串。可以指定它以拆分值。

注意

如果重命名依赖于属性处理器来修改属性，请确保在管道规范中的属性处理器之后指定日志处理器。

"processors": [
  {
    "type": "log",
    "body": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
]

从日志消息正文中提取属性

toAttributes 部分列出了匹配日志消息正文的正则表达式。它基于子表达式提取属性。

rules 设置是必需的。此设置列出了用于从正文中提取属性值的规则。

提取的特性名称会替换日志消息正文中的值。列表中的每个规则都是一个正则表达式 (regex) 模式字符串。

下面演示了提取的特性名称如何替换值：

根据 regex 检查日志消息正文。
如果正则表达式匹配，则该正则表达式的所有命名子表达式都将提取为特性。
提取的属性被添加到日志中。
每个子表达式名称成为一个属性名称。
子表达式匹配部分成为属性值。
提取的特性名称会替换日志名称中的匹配部分。如果属性已存在于日志中，则会被覆盖。

将按指定顺序针对所有规则重复此过程。每个后续规则都应用于处理上一规则后输出的日志名称。

"processors": [
  {
    "type": "log",
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

包括条件和排除条件

日志处理器支持可选的 include 和 exclude 条件。日志处理器仅应用于与其include条件（如果可用）匹配且与其exclude条件（如果可用）不匹配的遥测数据。

若要配置此选项，请在 include 和/或 exclude 下指定 matchType 和 attributes。允许在include或exclude配置中使用多个指定的条件。所有指定条件的评估结果都必须为 true 才会被视为匹配。

必填字段：
- matchType 控制如何解释 attributes 阵列中的项。可能值为 regexp 和 strict。正则表达式匹配是针对整个属性值执行的，因此如果要匹配其中任何位置包含 abc 的值，则需要使用 .*abc.*。
- attributes 指定要匹配的属性的列表。所有这些属性必须完全匹配才会被视为匹配。

注意

如果同时指定了 include 和 exclude，则会在检查 exclude 属性之前检查 include 属性。

注意

日志处理器不支持 spanNames。

示例用法

"processors": [
  {
    "type": "log",
    "include": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "value1"
        }
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute2",
          "value": "value2"
        }
      ]
    },
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

有关详细信息，请参阅遥测处理器示例。

指标筛选器

注意

从版本 3.1.1 开始，可以使用指标筛选器。

指标筛选器用于排除某些指标，以帮助控制引入成本。

指标筛选器仅支持 exclude 条件。与它的exclude条件匹配的指标不会导出。

若要配置此选项，在 exclude 下指定 matchType 一个或多个 metricNames。

必填字段：
- matchType 控制如何匹配 metricNames 中的项。可能值为 regexp 和 strict。正则表达式匹配是针对整个属性值执行的，因此如果要匹配其中任何位置包含 abc 的值，则需要使用 .*abc.*。
- metricNames 必须至少与一个项匹配。

示例用法

以下示例演示了如何排除名称为“metricA”和“metricB”的指标：

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "strict",
      "metricNames": [
        "metricA",
        "metricB"
      ]
    }
  }
]

以下示例演示如何关闭所有指标，包括默认自动收集的性能指标，例如 cpu 和内存。

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "regexp",
      "metricNames": [
        ".*"
      ]
    }
  }
]

Java 代理捕获的默认指标

指标名称	指标类型	说明	可筛选
`Current Thread Count`	自定义指标	请参阅 ThreadMXBean.getThreadCount()。	是
`Loaded Class Count`	自定义指标	请参阅 ClassLoadingMXBean.getLoadedClassCount()。	是
`GC Total Count`	自定义指标	所有 GarbageCollectorMXBean 实例的计数总和（自上次报告以来的差异）。请参阅 GarbageCollectorMXBean.getCollectionCount()。	是
`GC Total Time`	自定义指标	所有 GarbageCollectorMXBean 实例的时间总和（自上次报告以来的差异）。请参阅 GarbageCollectorMXBean.getCollectionTime()。	是
`Heap Memory Used (MB)`	自定义指标	请参阅 MemoryMXBean.getHeapMemoryUsage().getUsed()。	是
`% Of Max Heap Memory Used`	自定义指标	java.lang:type=Memory /最大内存量（以字节为单位）。请参阅 MemoryUsage	是
`\Processor(_Total)\% Processor Time`	默认指标	系统范围内 CPU 负载滴答计数器（仅限用户和系统）的差值除以给定时间间隔内的逻辑处理器计数	否
`\Process(??APP_WIN32_PROC??)\% Processor Time`	默认指标	请参阅 OperatingSystemMXBean.getProcessCpuTime()（自上次报告以来的差值，按时间和 CPU 数量进行标准化）。	否
`\Process(??APP_WIN32_PROC??)\Private Bytes`	默认指标	MemoryMXBean.getHeapMemoryUsage() 和 MemoryMXBean.getNonHeapMemoryUsage() 的总和。	否
`\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec`	默认指标	`/proc/[pid]/io` 进程读取和写入的字节总和（自上次报告以来的差值）。请参阅 proc(5)。	否
`\Memory\Available Bytes`	默认指标	请参阅 OperatingSystemMXBean.getFreePhysicalMemorySize()。	否

常见问题解答

日志处理器为何不使用 TelemetryClient.trackTrace() 来处理日志文件？

TelemetryClient.trackTrace() 是 Application Insights 经典 SDK 网桥的一部分，日志处理器仅适用于新的基于 OpenTelemetry 的检测。

通过

遥测处理器（预览版）- 适用于 Java 的 Azure Monitor Application Insights

术语

遥测处理器类型

入门

属性处理器

insert

update

delete

hash

extract

mask

包括条件和排除条件

示例用法

范围处理器

为范围命名

从范围名称中提取属性

常见范围属性

HTTP 范围

Java Database Connectivity 范围

包括条件和排除条件

示例用法

日志处理器

更新日志消息正文

从日志消息正文中提取属性

包括条件和排除条件

示例用法

指标筛选器

示例用法

Java 代理捕获的默认指标

常见问题解答

日志处理器为何不使用 TelemetryClient.trackTrace() 来处理日志文件？

其他资源

`insert`

`update`

`delete`

`hash`

`extract`

`mask`