你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

项目
10/15/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() 来处理日志文件？

反馈

其他资源