遙測處理器範例 - 適用於 JAVA 的 Azure 監視器 Application Insights

發行項
10/15/2024

本文提供適用於 JAVA 的 Application Insights 的遙測處理器範例，包括包含和排除設定的範例。其中也包含屬性處理器和跨處理器的範例。

包含和排除範圍範例

在本節中，了解如何包含和排除跨度。您也會了解如何排除多個跨度並套用選擇性處理。

包含範圍

本節說明如何包含屬性處理器的範圍。處理器不會處理不符合屬性的範圍。

相符項目需要範圍名稱等於 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"
          }
        ]
      }
    ]
  }
}

使用多個準則排除範圍

本節示範如何排除屬性處理器的範圍。此處理器不會處理符合屬性的範圍。

相符項目需要符合下列條件：

屬性 (例如，env 具有值 dev) 必須存在於範圍中。
範圍必須具有包含索引鍵 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"
          }
        ]
      }
    ]
  }
}

擷取

下列範例示範如何使用規則運算式 (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"
          }
        ]
      }
    ]
  }
}

遮罩

例如，假設 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$"
            ]
          }
        }
      }
    ]
  }
}

使用包含和排除從範圍名稱擷取屬性

下列範例示範如何將範圍名稱變更為 {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 型檢測搭配使用。

共用方式為

遙測處理器範例 - 適用於 JAVA 的 Azure 監視器 Application Insights

包含和排除範圍範例

包含範圍

排除範圍

使用多個準則排除範圍

選擇性處理

屬性處理器範例

插入

從另一個索引鍵插入

更新

刪除

雜湊

擷取

遮罩

非字串型別屬性範例

範圍處理器範例

為範圍命名

從範圍名稱擷取屬性

使用包含和排除從範圍名稱擷取屬性

記錄處理器範例

從記錄訊息本文擷取屬性

遮罩處理記錄訊息中的敏感性資料

常見問題集

為何記錄處理器不會使用 TelemetryClient.trackTrace() 處理記錄檔？

意見反應

其他資源

共用方式為

遙測處理器範例 - 適用於 JAVA 的 Azure 監視器 Application Insights

包含和排除範圍範例

包含範圍

排除範圍

使用多個準則排除範圍

選擇性處理

屬性處理器範例

插入​​

從另一個索引鍵插入

更新

刪除

雜湊

擷取

遮罩

非字串型別屬性範例

範圍處理器範例

為範圍命名

從範圍名稱擷取屬性

使用包含和排除從範圍名稱擷取屬性

記錄處理器範例

從記錄訊息本文擷取屬性

遮罩處理記錄訊息中的敏感性資料

常見問題集

為何記錄處理器不會使用 TelemetryClient.trackTrace() 處理記錄檔？

意見反應

其他資源

插入