遥测处理器示例 - 适用于 Java 的 Azure Monitor Application Insights

项目
04/09/2024

本文提供了 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 的检测。