遙測處理器 (預覽) - 適用於 JAVA 的 Azure 監視器 Application Insights

發行項
10/15/2024

注意

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

Application Insights JAVA 3.x 可以在匯出遙測資料之前處理資料。

一些使用案例：

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

注意

如果您要卸除特定 (整個) 範圍以控制擷取成本，請參閱取樣覆寫。

詞彙

了解遙測處理器之前，請先了解「範圍」和「記錄」這兩個詞彙。

範圍是代表下列其中一項的一種遙測資料：

傳入要求。
傳出相依性 (例如，遠端呼叫另一個服務)。
內含式相依性 (例如，由服務的子元件完成的工作)。

記錄是代表下列項目的一種遙測資料：

從 Log4j、Logback 和 java.util.logging 擷取的記錄資料

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

名稱
本文
屬性

範圍名稱主要呈現 Azure 入口網站中的要求和相依性。範圍屬性代表特定要求或相依性的標準和自訂內容。

追蹤訊息或內文主要呈現 Azure 入口網站中的記錄。記錄屬性代表特定記錄的標準和自訂內容。

遙測處理器類型

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

屬性處理器
範圍處理器
記錄處理器
計量篩選

屬性處理器可以插入、更新、刪除或雜湊遙測項目 (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",
        ...
      }
    ]
  }
}

屬性處理器

屬性處理器會修改 span 或 log 的屬性。支援併入或排除 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`

注意

僅 3.0.2 版和更新版本中才有 extract 功能可用。

extract 動作使用規則運算式規則，將輸入索引鍵中的值擷取到規則指定的目標索引鍵。如果目標索引鍵已存在，則 extract 動作會覆寫該目標索引鍵。此動作的行為就像跨度處理器 toAttributes 設定一樣，現有的屬性就是來源。

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

extract 動作需要下列設定︰

key
pattern
action: extract

`mask`

注意

僅 3.2.5 版和更新版本中才有 mask 功能可用。

mask 動作會使用 pattern 和 replace 中指定的規則運算式規則對屬性值使用遮罩。

"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 準則 (如果有的話) 的遙測資料。

若要設定此選項，請在 include 或 exclude (或兩者) 下，至少指定一個 matchType 及 spanNames 或 attributes。 include 或 exclude 設定允許一個以上的指定條件。所有指定的條件都必須評估為 true，結果才相符。

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

注意

如果 include 和 exclude 都指定，則會先檢查 include 屬性，再檢查 exclude 屬性。

注意

如果 include 或 exclude 設定未指定 spanNames，則 spans 和 logs 上都套用比對準則。

範例用法

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

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

範圍處理器

範圍處理器會修改範圍名稱，或根據範圍名稱修改範圍的屬性。支援併入或排除範圍。

命名範圍

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`)	字串	HTTP 要求方法。
`url.full` (用戶端跨度) 或 `url.path` (伺服器跨度) (以前是 `http.url`)	字串	`scheme://host[:port]/path?query[#fragment]` 格式的完整 HTTP 要求 URL。片段通常不會透過 HTTP 傳輸。但如果是已知片段，則應該包含該片段。
`http.response.status_code` (以前是 `http.status_code`)	數值	HTTP 回應狀態碼。
`network.protocol.version` (以前是 `http.flavor`)	字串	HTTP 通訊協定的類型。
`user_agent.original` (以前是 `http.user_agent`)	字串	用戶端傳送的 HTTP 使用者代理程式標頭值。

Java 資料庫連線跨度

下表描述您可用於 Java 資料庫連線 (JDBC) 跨度的屬性：

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

併入準則和排除準則

範圍處理器支援選擇性 include 和 exclude 準則。跨度處理器只會套用至符合其 include 準則 (如果有的話) 且不符合其 exclude 準則 (如果有的話) 的遙測資料。

若要設定此選項，請在 include 或 exclude (或兩者) 下，至少指定一個 matchType 及 spanNames 或範圍 attributes。 include 或 exclude 設定允許一個以上的指定條件。所有指定的條件都必須評估為 true，結果才相符。

必要欄位：
- matchType 可控制如何解譯 spanNames 陣列和 attributes 陣列中的項目。可能的值是 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 準則 (如果有的話) 的遙測資料。

若要設定此選項，請在 include 或 exclude (或兩者) 下，指定 matchType 和 attributes。 include 或 exclude 設定允許一個以上的指定條件。所有指定的條件都必須評估為 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=記憶體 / 最大記憶體數量 (以位元組為單位)。請參閱 MemoryUsage	是
`\Processor(_Total)\% Processor Time`	預設計量	在一段指定時間內，系統整體 CPU 負載滴答計數器 (僅限使用者和系統) 除以邏輯處理器計數的差異	否
`\Process(??APP_WIN32_PROC??)\% Processor Time`	預設計量	請參閱 OperatingSystemMXBean.getProcessCpuTime() (自上次報告以來的差異，依時間和 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`

併入準則和排除準則

範例用法

範圍處理器

命名範圍

從範圍名稱擷取屬性

常見範圍屬性

HTTP 範圍

Java 資料庫連線跨度

併入準則和排除準則

範例用法

記錄處理器

更新記錄訊息內文

從記錄訊息內文擷取屬性

併入準則和排除準則

範例用法

計量篩選條件

範例用法

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

常見問題集

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

意見反應

其他資源