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

發行項
03/15/2024

本文提供 Application Insights for Java 中遙測處理器的範例，包括包含和排除組態的範例。它也包含屬性處理器和範圍處理器的範例。

包含和排除Span範例

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

包含範圍

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

比對需要範圍名稱等於 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 不存在的spans和logs中。

{
  "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"}。它會使用來自屬性的值來更新屬性boofoo。沒有屬性 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-arraylong-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"} 插入 spans 和 logs 中，其中屬性 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"
      }
    ]
  }
}

範圍處理器範例

為範圍命名

下列範例會指定、 operation和id屬性db.svc的值。它會使用以該值分隔 ::的屬性來形成範圍的新名稱。

{
  "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 型檢測搭配使用。

共用方式為

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

包含和排除Span範例

包含範圍

排除範圍

使用多個準則排除範圍

選擇性處理

屬性處理器範例

插入

從另一個索引鍵插入

更新

刪除

雜湊

擷取

遮罩

非字串型別屬性範例

範圍處理器範例

為範圍命名

從範圍名稱擷取屬性

使用 include 和 exclude 從範圍名稱擷取屬性

記錄處理器範例

從記錄訊息本文擷取屬性

遮罩記錄訊息中的敏感數據

常見問題集

為何記錄處理器不會使用 TelemetryClient.trackTrace（）來處理記錄檔？

意見反應

意見反應

其他資源

共用方式為

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

包含和排除Span範例

包含範圍

排除範圍

使用多個準則排除範圍

選擇性處理

屬性處理器範例

插入​​

從另一個索引鍵插入

更新

刪除

雜湊

擷取

遮罩

非字串型別屬性範例

範圍處理器範例

為範圍命名

從範圍名稱擷取屬性

使用 include 和 exclude 從範圍名稱擷取屬性

記錄處理器範例

從記錄訊息本文擷取屬性

遮罩記錄訊息中的敏感數據

常見問題集

為何記錄處理器不會使用 TelemetryClient.trackTrace（）來處理記錄檔？

意見反應

意見反應

其他資源

插入