遙測處理器（預覽） - 適用於 Java 的 Azure 監視器 Application Insights

發行項
03/15/2024

注意

遙測處理器功能會指定為預覽，因為我們無法保證由於屬性語意慣例的實驗狀態，從發行到發行的回溯相容性。不過，此功能已經過測試，並在生產環境中受到支援。

Application Insights Java 3.x 可以在匯出數據之前處理遙測數據。

某些使用案例：

遮罩敏感數據。
有條件地新增自定義維度。
更新範圍名稱，用來匯總 Azure 入口網站中的類似遙測。
卸除特定的範圍屬性，以控制擷取成本。
篩選掉一些計量，以控制擷取成本。

注意

如果您想要卸除控制擷取成本的特定（完整）範圍，請參閱取樣覆寫。

詞彙

在了解遙測處理器之前，您應該先瞭解詞彙範圍和記錄。

範圍是一種遙測類型，代表下列其中一種：

傳入要求。
傳出相依性（例如，對另一個服務的遠端呼叫）。
同進程相依性（例如，由服務的子元件完成的工作）。

記錄是代表下列項目的遙測類型：

從 Log4j、Logback 和 java.util.logging 擷取的記錄數據

對於遙測處理器，這些範圍/記錄元件很重要：

名稱
Body
屬性

範圍名稱是 Azure 入口網站中要求和相依性的主要顯示。 Span 屬性代表指定要求或相依性的標準和自定義屬性。

追蹤訊息或本文是 Azure 入口網站中記錄的主要顯示。記錄屬性代表指定記錄檔的標準和自定義屬性。

遙測處理器類型

目前，遙測處理器的四種類型為

屬性處理器
Span 處理器
記錄處理器
計量篩選條件

屬性處理器可以插入、更新、刪除或哈希遙測專案（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",
        ...
      }
    ]
  }
}

屬性處理器

屬性處理器會修改或log的屬性span。它可以支援包含或排除 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`

注意

此功能 extract 僅適用於 3.0.2 版和更新版本。

動作會 extract 使用正則表示式規則，從輸入索引鍵擷取值，以擷取規則所指定的目標索引鍵。如果目標索引鍵已經存在，動作會 extract 覆寫目標索引鍵。此動作的行為就像範圍處理器toAttributes 設定，其中現有的屬性是來源。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "pattern": "<regular pattern with named matchers>",
        "action": "extract"
      }
    ]
  }
]

動作 extract 需要下列設定：

key
pattern
action: extract

`mask`

注意

此功能 mask 僅適用於 3.2.5 版和更新版本。

動作mask會使用和 replace中指定的pattern正則表達式規則來遮罩屬性值。

"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 準則（如果有的話）。

若要設定這個選項，請在或 exclude （或兩者）下include指定至少一個 matchType 和 spanNames 或。attributes 或 exclude 組include態允許一個以上的指定條件。所有指定的條件都必須評估為 true，才能產生相符專案。

必要欄位：
- matchType控制數位和attributes陣列中的spanNames專案如何解譯。可能的值是 regexp 和 strict。正規表示式比對會針對整個屬性值執行，因此如果您想要比對包含 abc 其中任何位置的值，則需要使用 .*abc.*。
選擇性欄位：
- spanNames 必須至少符合其中一個專案。
- attributes 指定要比對的屬性清單。所有這些屬性必須完全相符，才能產生相符專案。

注意

如果同時 include 指定和 exclude ，則會 include 在檢查屬性之前 exclude 檢查屬性。

注意

如果未指定或 exclude 組include態spanNames，則會在和logs上套用比對spans準則。

範例用法

"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"
      }
    ]
  }
]

如需詳細資訊，請參閱遙測處理器範例。

Span 處理器

範圍處理器會根據範圍名稱修改範圍的名稱或範圍的屬性。它可以支援包含或排除範圍的能力。

為範圍命名

區 name 段需要 fromAttributes 設定。這些屬性的值可用來建立新的名稱，並依照組態指定的順序串連。只有在範圍上存在所有這些屬性時，處理器才會變更範圍名稱。

此 separator 設定是選擇性的。此設定是字串，您可以使用分割值。

注意

如果重新命名依賴屬性處理器來修改屬性，請確定在管線規格中的屬性處理器之後指定範圍處理器。

"processors": [
  {
    "type": "span",
    "name": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
]

從範圍名稱擷取屬性

區 toAttributes 段會列出要與範圍名稱相符的正則表達式。它會根據子表達式擷取屬性。

需要 rules 此設定。此設定會列出用來從範圍名稱擷取屬性值的規則。

擷取的屬性名稱會取代範圍名稱中的值。清單中的每個規則都是正則表示式（regex）模式字串。

以下是擷取的屬性名稱如何取代值：

範圍名稱會針對 regex 進行檢查。
如果 regex 相符，則會將 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	格式 `scheme://host[:port]/path?query[#fragment]`的完整 HTTP 要求 URL。片段通常不會透過 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 連線 ivity 範圍

下表描述您可以在 Java Database 連線 ivity （JDBC）範圍中使用的屬性：

屬性	類型	描述
`db.system`	string	使用之資料庫管理系統（DBMS）產品的識別碼。請參閱資料庫作業的語意慣例。
`db.connection_string`	string	用來連接到資料庫的連線字串。建議您移除內嵌認證。
`db.user`	string	存取資料庫的用戶名稱。
`db.name`	string	用來報告所存取資料庫名稱的字串。對於切換資料庫的命令，即使命令失敗，此字串也應該設定為目標資料庫。
`db.statement`	string	正在執行的資料庫語句。

包含準則和排除準則

範圍處理器支持選擇性 include 和 exclude 準則。範圍處理器只會套用至符合其 include 準則的遙測（如果有的話），且不符合其 exclude 準則（如果有的話）。

若要設定此選項，請在或（或兩者）下include指定至少一個 matchType 和 spanNames 或範圍attributes。exclude 或 exclude 組include態允許一個以上的指定條件。所有指定的條件都必須評估為 true，才能產生相符專案。

必要欄位：
- matchType控制數位和attributes陣列中的spanNames專案如何解譯。可能的值是 regexp 和 strict。正規表示式比對會針對整個屬性值執行，因此如果您想要比對包含 abc 其中任何位置的值，則需要使用 .*abc.*。
選擇性欄位：
- spanNames 必須至少符合其中一個專案。
- attributes 指定要比對的屬性清單。所有這些屬性必須完全相符，才能產生相符專案。

注意

如果同時 include 指定和 exclude ，則會 include 在檢查屬性之前 exclude 檢查屬性。

範例用法

"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 進行檢查。
如果 regex 相符，則會將 regex 的所有具名子運算式擷取為屬性。
擷取的屬性會新增至記錄檔。
每個子表達式名稱都會變成屬性名稱。
子表達式比對部分會變成屬性值。
擷取的屬性名稱會取代記錄檔名稱中的相符部分。如果記錄檔中已經有屬性，則會覆寫這些屬性。

此程式會依指定的順序重複執行所有規則。每個後續規則都會在記錄檔名稱上運作，這是上一個規則的輸出。

"processors": [
  {
    "type": "log",
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

包含準則和排除準則

記錄處理器支持選擇性 include 和 exclude 準則。記錄處理器只會套用至符合其 include 準則的遙測（如果有的話），且不符合其 exclude 準則（如果有的話）。

若要設定這個選項，請在或 exclude （或兩者）下include指定 matchType 和 attributes。或 exclude 組include態允許一個以上的指定條件。所有指定的條件都必須評估為 true，才能產生相符專案。

必要欄位：
- matchType 控制數位中的 attributes 項目解譯方式。可能的值是 regexp 和 strict。正規表示式比對會針對整個屬性值執行，因此如果您想要比對包含 abc 其中任何位置的值，則需要使用 .*abc.*。
- attributes 指定要比對的屬性清單。所有這些屬性必須完全相符，才能產生相符專案。

注意

如果同時 include 指定和 exclude ，則會 include 在檢查屬性之前 exclude 檢查屬性。

注意

記錄處理器不支援 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（）（自上次報告以來的 diff，依時間和 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 監視器 Application Insights

詞彙

遙測處理器類型

開始使用

屬性處理器

insert

update

delete

hash

extract

mask

包含準則和排除準則

範例用法

Span 處理器

為範圍命名

從範圍名稱擷取屬性

一般範圍屬性

HTTP 範圍

Java Database 連線 ivity 範圍

包含準則和排除準則

範例用法

記錄處理器

更新記錄訊息本文

從記錄訊息本文擷取屬性

包含準則和排除準則

範例用法

計量篩選

範例用法

Java 代理程式擷取的預設計量

常見問題集

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

其他資源

遙測處理器（預覽） - 適用於 Java 的 Azure 監視器 Application Insights

`insert`

`update`

`delete`

`hash`

`extract`

`mask`