遥测处理器示例 - 适用于 Java 的 Azure Monitor Application Insights
本文提供了 Application Insights for Java 中的遥测处理器示例,例如有关包括和排除配置的示例。 此外,还提供了特性处理器和范围处理器的示例。
包括和排除范围示例
在本部分中,你将了解如何包含和排除范围。 此外,你还将了解如何排除多个范围和应用选择性处理。
包含范围
本部分介绍如何包含特性处理器的范围。 处理器不处理与属性不匹配的范围。
范围名称必须等于 spanA
或 spanB
才能视为匹配。
以下范围与 include
属性匹配,将应用处理器操作:
Span1
名称:“spanA”,属性:{env: dev, test_request: 123, credit_card: 1234}Span2
名称:“spanB”,属性:{env: dev, test_request: false}Span3
名称:“spanA”,属性:{env: 1, test_request: dev, credit_card: 1234}
此范围与 include
属性不匹配,将不应用处理器操作:
Span4
名称:'spanC' 属性:{env: dev, test_request: false}
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"include": {
"matchType": "strict",
"spanNames": [
"spanA",
"spanB"
]
},
"actions": [
{
"key": "credit_card",
"action": "delete"
}
]
}
]
}
}
排除范围
本部分演示如何排除特性处理器的范围。 此处理器不处理与属性匹配的范围。
范围名称必须等于 spanA
或 spanB
才能视为匹配。
以下范围与 exclude
属性匹配,将不应用处理器操作:
Span1
名称:“spanA”,属性:{env: dev, test_request: 123, credit_card: 1234}Span2
名称:“spanB”,属性:{env: dev, test_request: false}Span3
名称:“spanA”,属性:{env: 1, test_request: dev, credit_card: 1234}
此范围与 exclude
属性不匹配,将应用处理器操作:
Span4
名称:'spanC' 属性:{env: dev, test_request: false}
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"exclude": {
"matchType": "strict",
"spanNames": [
"spanA",
"spanB"
]
},
"actions": [
{
"key": "credit_card",
"action": "delete"
}
]
}
]
}
}
使用多个条件来排除范围
本部分演示如何排除特性处理器的范围。 此处理器不处理与属性匹配的范围。
必须满足以下条件才视为匹配:
- 范围中必须存在一个特性(例如值为
dev
的env
)。 - 范围必须具有一个键为
test_request
的特性。
以下范围与 exclude
属性匹配,将不应用处理器操作。
Span1
名称:“spanB”,属性:{env: dev, test_request: 123, credit_card: 1234}Span2
名称:“spanA”,属性:{env: dev, test_request: false}
以下范围与 exclude
属性不匹配,将应用处理器操作:
Span3
名称:“spanB”,属性:{env: 1, test_request: dev, credit_card: 1234}Span4
名称:'spanC' 属性:{env: dev, dev_request: false}
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"exclude": {
"matchType": "strict",
"spanNames": [
"spanA",
"spanB"
],
"attributes": [
{
"key": "env",
"value": "dev"
},
{
"key": "test_request"
}
]
},
"actions": [
{
"key": "credit_card",
"action": "delete"
}
]
}
]
}
}
选择性处理
本部分介绍如何指定范围属性集,用于指示此处理器要应用到的范围。 include
属性指示应处理的范围。 exclude
属性筛选掉不应处理的范围。
在以下配置中,这些范围与属性匹配,将应用处理器操作:
Span1
名称:“spanB”,属性:{env: production, test_request: 123, credit_card: 1234, redact_trace: "false"}Span2
名称:“spanA”,属性:{env: staging, test_request: false, redact_trace: true}
这些范围与 include
属性不匹配,将不应用处理器操作:
Span3
名称:“spanB”,属性:{env: production, test_request: true, credit_card: 1234, redact_trace: false}Span4
名称:'spanC' 属性:{env: dev, test_request: false}
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"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"
}
]
}
]
}
}
特性处理器示例
插入
以下示例将新特性 {"attribute1": "attributeValue1"}
插入到不存在键 attribute1
的范围和日志中。
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attribute1",
"value": "attributeValue1",
"action": "insert"
}
]
}
]
}
}
从另一个键插入
以下示例使用 anotherkey
特性中的值将新特性 {"newKey": "<value from attribute anotherkey>"}
插入到不存在键 newKey
的范围和日志中。 如果特性 anotherkey
不存在,则不会将任何新特性插入到范围和日志中。
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "newKey",
"fromAttribute": "anotherKey",
"action": "insert"
}
]
}
]
}
}
更新
以下示例将特性更新为 {"db.secret": "redacted"}
。 它使用特性 foo
中的值更新特性 boo
。 没有特性 boo
的范围和日志不会更改。
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "db.secret",
"value": "redacted",
"action": "update"
},
{
"key": "boo",
"fromAttribute": "foo",
"action": "update"
}
]
}
]
}
}
删除
以下示例演示如何删除具有键 credit_card
的特性。
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "credit_card",
"action": "delete"
}
]
}
]
}
}
哈希
以下示例演示如何哈希化现有的特性值。
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "user.email",
"action": "hash"
}
]
}
]
}
}
Extract
以下示例演示如何使用正则表达式 (regex) 基于另一个特性的值创建新特性。
例如,在指定 url.path = /path?queryParam1=value1,queryParam2=value2
的情况下,将插入以下特性:
- httpProtocol:
http
- httpDomain:
example.com
- httpPath:
path
- httpQueryParams:
queryParam1=value1,queryParam2=value2
- url.path:无更改
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "url.path",
"pattern": "^(?<httpProtocol>.*):\\/\\/(?<httpDomain>.*)\\/(?<httpPath>.*)(\\?|\\&)(?<httpQueryParams>.*)",
"action": "extract"
}
]
}
]
}
}
Mask
例如,给定 url.path = https://example.com/user/12345622
会更新为 url.path = https://example.com/user/****
并使用以下任一配置。
第一个配置示例:
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "url.path",
"pattern": "user\\/\\d+",
"replace": "user\\/****",
"action": "mask"
}
]
}
]
}
}
具有正则表达式组名称的第二个配置示例:
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "url.path",
"pattern": "^(?<userGroupName>[a-zA-Z.:\/]+)\d+",
"replace": "${userGroupName}**",
"action": "mask"
}
]
}
]
}
}
非字符串类型的属性示例
从 3.4.19 GA 开始,遥测处理器支持非字符串类型的属性:boolean
、double
、long
、boolean-array
、double-array
、long-array
和 string-array
。
json 中未提供 attributes.type
时,它默认为 string
。
以下示例将新属性 {"newAttributeKeyStrict": "newAttributeValueStrict"}
插入到属性与以下示例匹配的范围和日志中:{"longAttributeKey": 1234}
{"booleanAttributeKey": true}
{"doubleArrayAttributeKey": [1.0, 2.0, 3.0, 4.0]}
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"include": {
"matchType": "strict",
"attributes": [
{
"key": "longAttributeKey",
"value": 1234,
"type": "long"
},
{
"key": "booleanAttributeKey",
"value": true,
"type": "boolean"
},
{
"key": "doubleArrayAttributeKey",
"value": [1.0, 2.0, 3.0, 4.0],
"type": "double-array"
}
]
},
"actions": [
{
"key": "newAttributeKeyStrict",
"value": "newAttributeValueStrict",
"action": "insert"
}
],
"id": "attributes/insertNewAttributeKeyStrict"
}
]
}
}
此外,非字符串类型的属性支持 regexp
。
以下示例将新属性 {"newAttributeKeyRegexp": "newAttributeValueRegexp"}
插入到范围和日志中,其中属性 longRegexpAttributeKey
与介于 400
到 499
之间的值匹配。
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
"include": {
"matchType": "regexp",
"attributes": [
{
"key": "longRegexpAttributeKey",
"value": "4[0-9][0-9]",
"type": "long"
}
]
},
"actions": [
{
"key": "newAttributeKeyRegexp",
"value": "newAttributeValueRegexp",
"action": "insert"
}
],
"id": "attributes/insertNewAttributeKeyRegexp"
}
]
}
}
范围处理器示例
为范围命名
以下示例指定特性 db.svc
、operation
和 id
的值。 它按照这种顺序使用这些特性(以值 ::
分隔)构成了范围的新名称。
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "span",
"name": {
"fromAttributes": [
"db.svc",
"operation",
"id"
],
"separator": "::"
}
}
]
}
}
从范围名称中提取特性
假设输入范围名称为 /api/v1/document/12345678/update
。 以下示例将生成输出范围名称 /api/v1/document/{documentId}/update
。 它将新特性 documentId=12345678
添加到范围。
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "span",
"name": {
"toAttributes": {
"rules": [
"^/api/v1/document/(?<documentId>.*)/update$"
]
}
}
}
]
}
}
使用 include 和 exclude 从范围名称中提取特性
以下示例演示如何将范围名称更改为 {operation_website}
。 当范围具有以下属性时,此示例将添加键为 operation_website
、值为 {oldSpanName}
的特性:
- 范围名称在字符串中的任意位置包含
/
。 - 范围名称不是
donot/change
。
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "span",
"include": {
"matchType": "regexp",
"spanNames": [
"^(.*?)/(.*?)$"
]
},
"exclude": {
"matchType": "strict",
"spanNames": [
"donot/change"
]
},
"name": {
"toAttributes": {
"rules": [
"(?<operation_website>.*?)$"
]
}
}
}
]
}
}
日志处理器示例
从日志消息正文中提取特性
假设输入日志消息正文为“Starting PetClinicApplication on WorkLaptop with PID 27984 (C:\randompath\target\classes started by userx in C:\randompath)
”。 以下示例会生成输出消息正文“Starting PetClinicApplication on WorkLaptop with PID {PIDVALUE} (C:\randompath\target\classes started by userx in C:\randompath)
”。 它将新特性 PIDVALUE=27984
添加到日志。
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "log",
"body": {
"toAttributes": {
"rules": [
"^Starting PetClinicApplication on WorkLaptop with PID (?<PIDVALUE>\\d+) .*"
]
}
}
}
]
}
}
屏蔽日志消息中的敏感数据
以下示例演示如何使用日志处理器和特性处理器屏蔽日志消息正文中的敏感数据。
假设输入日志消息正文为“User account with userId 123456xx failed to login
”。 日志处理器会将输出消息正文更新为“User account with userId {redactedUserId} failed to login
”,特性处理器会删除在上一步添加的新特性 redactedUserId
。
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "log",
"body": {
"toAttributes": {
"rules": [
"userId (?<redactedUserId>[0-9a-zA-Z]+)"
]
}
}
},
{
"type": "attribute",
"actions": [
{
"key": "redactedUserId",
"action": "delete"
}
]
}
]
}
}
常见问题解答
日志处理器为何不使用 TelemetryClient.trackTrace() 来处理日志文件?
TelemetryClient.trackTrace() 是 Application Insights 经典 SDK 网桥的一部分,日志处理器仅适用于新的基于 OpenTelemetry 的检测。