遙測處理器 (預覽) - 適用於 Java 的 Azure 監視器 Application Insights
注意
遙測處理器功能會指定為預覽,因為我們無法保證由於屬性 語意慣例的實驗狀態,從發行到發行的回溯相容性。 不過,此功能已經過測試,並在生產環境中受到支援。
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 型檢測搭配使用。
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應