本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
用於指標篩選條件、訂閱篩選條件、篩選條件日誌事件和 Live Tail 的篩選條件模式語法
透過 CloudWatch 記錄,您可以使用指標篩選器將記錄資料轉換為可採取動作的指標、訂閱篩選器將記錄事件路由傳送至其他 AWS 服務、篩選記錄事件以搜尋記錄事件,以及 Live Tail 在擷取記錄時以互動方式即時檢視記錄檔。
篩選條件模式構成了指標篩選條件、訂閱篩選條件、篩選條件日誌事件和 Live Tail 用來比對日誌事件中詞彙的語法。詞彙可以是單字、完全相符片語或數值。規則運算式 (regex) 可用於建立獨立的篩選條件模式,或與 JSON 和以空格分隔的篩選條件模式整合。
使用要比對的詞彙建立篩選條件模式。篩選條件模式僅傳回包含您所定義的詞彙的日誌事件。您可以在 CloudWatch 主控台中測試篩選器模式。
支援的規則運算式 (regex) 語法
使用 regex 搜尋和篩選日誌資料時,必須用 %
括住運算式。
包含 regex 的篩選條件模式只能包括下列字元:
英數字元 – 英數字元包含字母 (A 到 Z 或 a 到 z) 或數字 (0 到 9) 字元。
支援的符號字元 – 包括:'_
'、'#
'、'=
'、'@
'、'/
'、';
'、',
' 和 '-
'。例如,由於不支援 '!
',因此 %something!%
會遭拒。
支援的運算子 - 包括:'^
'、'$
'、'?
'、'[
'、']
'、'{
'、'}
'、'|
'、'\
'、'*
'、'+
' 和 '.
'。
不支援運算子 (
和 )
。您不可以使用括號來定義子模式。
不支援多位元組字元。
配額
建立指標篩選條件或訂閱篩選條件時,每個日誌群組最多有 5 個包含 regex 的篩選條件模式。
在為指標篩選條件和訂閱篩選條件建立分隔或 JSON 篩選條件模式,或在篩選條件日誌事件或 Live Tail 時,每個篩選模式限制為 2 個 regex。
受支援運算子的使用
^
:將比對錨定到字串的開頭。例如,%^[hc]at%
比對 "hat" 和 "cat",但只比對字串的開頭。
$
:將比對錨定到字串的結尾。例如,%[hc]at$%
比對 "hat" 和 "cat",但只比對字串的結尾。
?
:符合前述詞彙的零個或多個執行個體。例如,%colou?r%
可同時比對 "color" 和 "colour"。
[]
:定義字元類別。比對包含在括號內的字元清單或字元範圍。例如,%[abc]%
比對 "a"、"b" 或 "c";%[a-z]%
比對從 "a" 到 "z" 的任何小寫字元;以及 %[abcx-z]%
比對 "a"、"b"、"c"、"x"、"y" 或 "z"。
{m, n}
:比對前一個詞彙至少 m 次且不超過 n 次。例如,%a{3,5}%
僅比對 "aaa"、"aaaa" 和 "aaaaa"。
如果您選擇不定義下限或上限,則可省略 m 或 n。
|
:布林值 "Or",比對垂直列任一側的詞彙。例如,%gra|ey%
可比對 "gray" 或 "grey"。
術語是使用下列其中一個運算子的單一字元或重複字元類別:?
、*
、+
或 {n,m}
。
\
:逸出字元,可讓您使用運算子的文字含義,而非其特殊含義。例如,因為括號被逸出,%\[.\]%
比對任何用 "[" 和 "]" 括住的單一字元,例如 "[a]"、"[b]"、"[7]"、"[@]"、"[]]" 和 "[ ]"。
%10\.10\.0\.1%
是建立可比對 IP 地址 10.10.0.1 的 regex 的正確方法。
*
:符合前述詞彙的零個或多個執行個體。例如, %ab*c%
可比對 "ac"、"abc" 和 "abbbc";%ab[0-9]*%
可比對 "ab"、"ab0" 和 "ab129"。
+
:符合前述詞彙的一或多個實例。例如,%ab+c%
可比對 "abc"、"abbc" 和 "abbbc",而非 "ac"。
.
:比對任一個單一字元。例如,%.at%
比對以 "at" 結尾的任意三個字串,包括 "hat"、"cat"、"bat"、"4at"、"#at" 和 "at" (以空格開始)。
建立比對 IP 地址的 regex 時,逸出 .
運算子很重要。例如,%10.10.0.1%
可比對 "10010,051",這可能不是運算式的實際預期用途。
\d
、\D
:比對數字/非數字字元。例如,%\d%
等於 %[0-9]%
,%\D%
等於 %[^0-9]%
。
\s
、\S
:比對空白字元/非空白字元。
大寫運算子表示其對應小寫運算子的反轉。空白字元包括 tab (\t
)、空格 (
) 和換行符 (\n
) 字元。
\w
、\W
:比對英數字元/非英數字元。例如,%\w%
等於 %[a-zA-Z_0-9]%
,%\W%
等於 %[^a-zA-Z_0-9]%
。
\xhh
:比對兩位數十六進位字元的 ASCII 映射。\x
為逸出序列,表示下列字元代表 ASCII 的十六進位值。hh
指定指向 ASCII 資料表中某個字元的兩個十六進位數字 (0-9 和 A-F)。
您可以使用 \xhh
來比對篩選條件模式不支援的符號字元。例如,%\x3A%
比對 :
;%\x28%
比對 (
。
使用篩選條件模式來比對詞彙與規則運算式 (regex)
您可以使用以 %
(regex 模式之前和之後的百分比符號) 括住的 regex 模式來比對日誌事件中的術語。以下程式碼片段為篩選條件模式的範例,其會傳回包含 AUTHORIZED 關鍵字的所有日誌事件。
如需支援的規則運算式清單,請參閱支援的規則運算式。
%AUTHORIZED%
此篩選條件模式會傳回如下日誌事件訊息:
使用篩選條件模式來比對日誌事件中的詞彙
下列程式碼片段範例示範了如何使用篩選條件模式,來比對非結構化日誌事件中的詞彙。
篩選條件模式區分大小寫。將完全相符字詞和包含非英數字元的詞彙括在雙引號 ("") 中。
- Example: Match a single term
-
下方程式碼片段為單一詞彙篩選條件模式的範例,其會傳回所有訊息中包含單字 ERROR (錯誤) 的日誌事件。
ERROR
此篩選條件模式會比對以下日誌事件訊息:
[ERROR 400] BAD REQUEST
[ERROR 401] UNAUTHORIZED REQUEST
[ERROR 419] MISSING ARGUMENTS
[ERROR 420] INVALID ARGUMENTS
- Example: Match multiple terms
-
以下程式碼片段為多項詞彙篩選條件範例,其會傳回所有訊息中包含單字 ERROR (錯誤) 和 ARGUMENTS (引數) 的日誌事件。
ERROR ARGUMENTS
篩選條件會傳回如下的日誌事件訊息:
此篩選條件模式不會傳回以下日誌事件訊息,因為其不包含在篩選條件模式中指定的兩個詞彙。
- Example: Match optional terms
-
您可以使用模式比對,來建立會傳回包含選用詞彙之日誌事件的篩選條件模式。將問號 ("?") 置於想要比對的詞彙之前。下列程式碼片段為篩選條件模式的範例,篩選條件模式會傳回所有訊息中包含單字 ERROR 或單字 ARGUMENTS 的日誌事件。
?ERROR ?ARGUMENTS
此篩選條件模式會比對以下日誌事件訊息:
[ERROR 400] BAD REQUEST
[ERROR 401] UNAUTHORIZED REQUEST
[ERROR 419] MISSING ARGUMENTS
[ERROR 420] INVALID ARGUMENTS
無法結合使用問號 ("?") 和其他篩選模式,例如包含和排除詞彙。如果結合使用 "?" 和其他篩選模式,則將會忽略問號 ("?")。
例如,下列篩選模式會比對包含 REQUEST
字詞的所有事件,但問號 ("?") 篩選條件會被忽略且無效。
?ERROR ?ARGUMENTS REQUEST
日誌事件相符
- Example: Match exact phrases
-
下列程式碼片段為篩選條件的範例,其會傳回訊息中包含完全相符字詞 INTERNAL SERVER ERROR (內部伺服器錯誤) 的日誌事件。
"INTERNAL SERVER ERROR"
此篩選條件模式會傳回以下日誌事件訊息:
- Example: Include and exclude terms
-
您可以建立篩選條件模式,令其傳回訊息中包含某些詞彙,並排除其他詞彙的日誌事件。將減號 ("-") 置於想要排除的詞彙之前。下列程式碼片段為篩選條件模式的範例,其會傳回訊息中包含詞彙 ERROR (錯誤) 並排除詞彙 ARGUMENTS (引數) 的日誌事件。
ERROR -ARGUMENTS
此篩選條件模式會傳回如下日誌事件訊息:
此篩選條件模式不會傳回以下日誌事件訊息,因為其包含單字 ARGUMENTS。
- Example: Match everything
-
您可以用雙引號比對日誌事件中的所有內容。下列程式碼片段為篩選條件模式的範例,其會傳回所有日誌事件。
" "
使用篩選條件模式來比對 JSON 日誌事件中的詞彙
下列範例示範了如何寫入篩選條件模式的語法,來比對包含字串和數值和 JSON 詞彙。
- Writing filter patterns that match strings
-
您可以建立篩選條件模式以比對 JSON 日誌事件中的字串。下列程式碼片段顯示的範例為以字串為基礎的篩選條件模式。
{ PropertySelector
EqualityOperator
String
}
用大括號 ("{}") 括住篩選條件模式。以字串為基礎的篩選條件模式必須包含以下部分:
Property selector (屬性選擇器)
屬性選擇器以後面帶一個句點的貨幣符號 ("$.") 開始。屬性選擇器都是英數字元字串,並支援連字號 ("-") 和底線 ("_") 字元。字串不支援科學符號。屬性選擇器指向 JSON 日誌事件中的值節點。值節點可以是字串或數字。將陣列放在屬性選擇器之後。陣列中的元素依循從零開始的編號系統,意即陣列中的第一個元素是元素 0,第二個元素是元素 1,依此類推。將元素括在中括號內 ("[]")。如果屬性選擇器指向陣列或物件,則篩選條件模式會與日誌格式不相符。如果 JSON 屬性包含句點 ("."
),則可以使用括號標記法來選取該屬性。
萬用字元選取器
您可以使用 JSON 萬用字元來選取任何陣列元素或任何 JSON 物件欄位。
配額
在屬性選取器中,您只能使用最多一個萬用字元選取器。
Equality operator (等式運算子)
等式運算子以下列符號之一開始:等於 ("=") 或不等於 ("!=")。等式運算子傳回布林值 (true 或 false)。
字串
您可以用雙引號 ("") 括住字串。包含除了英數字元和底線符號以外類型的字串必須置於雙引號中。使用星號 ("*") 作為萬用字元來比對文本。
建立篩選條件模式來比對 JSON 日誌事件中的詞彙時,您可以使用任何條件式規則運算式。如需支援的規則運算式清單,請參閱支援的規則運算式。
下列程式碼片段包含一個篩選條件模式範例,示範如何設定篩選條件模式的格式,使用字串來比對 JSON 詞彙。
{ $.eventType = "UpdateTrail" }
- Writing filter patterns that match numeric values
-
您可以建立篩選條件模式以比對 JSON 日誌事件中的數值。下列程式碼片段為與數值相符之篩選條件模式的語法範例。
{ PropertySelector
NumericOperator
Number
}
用大括號 ("{}") 括住篩選條件模式。比對數值的篩選條件模式必須包含以下部分:
Property selector (屬性選擇器)
屬性選擇器以後面帶一個句點的貨幣符號 ("$.") 開始。屬性選擇器都是英數字元字串,並支援連字號 ("-") 和底線 ("_") 字元。字串不支援科學符號。屬性選擇器指向 JSON 日誌事件中的值節點。值節點可以是字串或數字。將陣列放在屬性選擇器之後。陣列中的元素依循從零開始的編號系統,意即陣列中的第一個元素是元素 0,第二個元素是元素 1,依此類推。將元素括在中括號內 ("[]")。如果屬性選擇器指向陣列或物件,則篩選條件模式會與日誌格式不相符。如果 JSON 屬性包含句點 ("."
),則可以使用括號標記法來選取該屬性。
萬用字元選取器
您可以使用 JSON 萬用字元來選取任何陣列元素或任何 JSON 物件欄位。
配額
在屬性選取器中,您只能使用最多一個萬用字元選取器。
Numeric operator (數值運算子)
數值運算子以下列符號之一開始:大於 (">")、小於 ("<")、等於 ("=")、不等於 ("!=")、大於等於 (">=") 或是小於等於 ("<=")。
數字
您可以使用包含加號 ("+") 或減號 ("-") 符號的整數,並遵守科學表示法。使用星號 ("*") 作為萬用字元來比對數字。
下列程式碼片段示範如何設定篩選條件模式的格式,使用數值來比對 JSON 詞彙。
// Filter pattern with greater than symbol
{ $.bandwidth > 75 }
// Filter pattern with less than symbol
{ $.latency < 50 }
// Filter pattern with greater than or equal to symbol
{ $.refreshRate >= 60 }
// Filter pattern with less than or equal to symbol
{ $.responseTime <= 5 }
// Filter pattern with equal sign
{ $.errorCode = 400}
// Filter pattern with not equal sign
{ $.errorCode != 500 }
// Filter pattern with scientific notation and plus symbol
{ $.number[0] = 1e-3 }
// Filter pattern with scientific notation and minus symbol
{ $.number[0] != 1e+3 }
下列範例中的程式碼片段,示範篩選條件模式如何比對 JSON 日誌事件中的詞彙。
如果要使用 JSON 日誌事件範例測試篩選條件模式範例,則必須在單行中輸入 JSON 日誌範例。
JSON 日誌事件
{
"eventType": "UpdateTrail",
"sourceIPAddress": "111.111.111.111",
"arrayKey": [
"value",
"another value"
],
"objectList": [
{
"name": "a",
"id": 1
},
{
"name": "b",
"id": 2
}
],
"SomeObject": null,
"cluster.name": "c"
}
- Example: Filter pattern that matches string values
-
此篩選條件模式會比對屬性 "UpdateTrail"
中的字串 "eventType"
。
{ $.eventType = "UpdateTrail" }
- Example: Filter pattern that matches string values (IP address)
-
篩選條件模式包含一個萬用字元,並與屬性 "sourceIPAddress"
相符,因為其不包含帶有前綴的數字 "123.123."
。
{ $.sourceIPAddress != 123.123.* }
- Example: Filter pattern that matches a specific array element with a string value
-
此篩選條件模式會比對陣列 "value"
中的元素 "arrayKey"
。
{ $.arrayKey[0] = "value" }
- Example: Filter pattern that matches a string using regex
-
此篩選條件模式會比對屬性 "Trail"
中的字串 "eventType"
。
{ $.eventType = %Trail% }
- Example: Filter pattern that uses a wildcard to match values of any element in the array using regex
-
篩選條件模式包含可比對陣列 "arrayKey"
中元素 "value"
的 regex。
{ $.arrayKey[*] = %val.{2}% }
- Example: Filter pattern that uses a wildcard to match values of any element with a specific prefix and subnet using regex (IP address)
-
此篩選條件模式包含可比對屬性 "sourceIPAddress"
中元素 "111.111.111.111"
的 regex。
{ $.* = %111\.111\.111\.1[0-9]{1,2}% }
配額
在屬性選取器中,您只能使用最多一個萬用字元選取器。
- Example: Filter pattern that matches a JSON property with a period (.) in the key
-
{ $.['cluster.name'] = "c" }
- Example: Filter pattern that matches JSON logs using IS
-
您可以使用 IS
變數建立比對 JSON 日誌中欄位的篩選條件模式。IS
變數可以比對包含 NULL
、TRUE
或 FALSE
值的欄位。下列篩選條件模式會傳回 SomeObject
值為 NULL
的 JSON 日誌。
{ $.SomeObject IS NULL }
- Example: Filter pattern that matches JSON logs using NOT EXISTS
-
您可以使用NOT EXISTS
變數建立篩選器模式,以傳回記錄資料中不包含特定欄位的 JSON 記錄。下列篩選條件模式會使用 NOT EXISTS
傳回不包含欄位 SomeOtherObject
的 JSON 日誌。
{ $.SomeOtherObject NOT EXISTS }
您可以在篩選條件模式中使用邏輯運算子邏輯與 ("&&") 和邏輯或 ("||") 來建立兩個或多個條件為真的,與日誌事件相符的複合表達式。複合表達式支援使用小括號 ("()") 和以下標準運算次序:() > && > ||。下列範例中的程式碼片段,示範如何將篩選條件模式與複合表達式相結合,來比對 JSON 物件中的詞彙。
JSON 物件
{
"user": {
"id": 1,
"email": "John.Stiles@example.com"
},
"users": [
{
"id": 2,
"email": "John.Doe@example.com"
},
{
"id": 3,
"email": "Jane.Doe@example.com"
}
],
"actions": [
"GET",
"PUT",
"DELETE"
],
"coordinates": [
[0, 1, 2],
[4, 5, 6],
[7, 8, 9]
]
}
- Example: Expression that matches using AND (&&)
-
此篩選條件模式包含的複合表達式,將 "user"
中的 "id"
與數值 1
,和 "users"
陣列中第一個元素的 "email"
與字串 "John.Doe@example.com"
做比對。
{ ($.user.id = 1) && ($.users[0].email = "John.Doe@example.com") }
- Example: Expression that matches using OR (||)
-
此篩選條件模式包含的複合表達式,將 "user"
中的 "email"
與字串 "John.Stiles@example.com"
相比對。
{ $.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = "nonmatch" && $.actions[2] = "nonmatch" }
- Example: Expression that doesn't match using AND (&&)
-
此篩選條件模式包含一個找不到相符項目的複合表達式,因為該表達式與 "actions"
中的第三個動作不相符。
{ ($.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = "nonmatch") && $.actions[2] = "nonmatch" }
配額
在屬性選取器中,您只能使用最多一個萬用字元選取器,在具有複合運算式的篩選條件模式中,只能使用最多三個萬用字元選取器。
- Example: Expression that doesn't match using OR (||)
-
此篩選條件模式包含一個找不到相符項目的複合表達式,因為該表達式與 "users"
中的第一個屬性,或 "actions"
中的第三個動作不符。
{ ($.user.id = 2 && $.users[0].email = "nonmatch") || $.actions[2] = "GET" }
使用篩選條件模式來比對以空格分隔的日誌事件中的詞彙
您可以建立篩選條件模式來比對以空格分隔的日誌事件中的詞彙。下面提供了以空格分隔的日誌事件範例,示範了如何編寫用於比對空格分隔日誌事件中詞彙的篩選條件模式語法。
建立篩選條件模式來比對以空格分隔的日誌事件中的詞彙時,您可以使用任何條件式規則運算式。如需支援的規則運算式清單,請參閱支援的規則運算式。
- Example: Space-delimited log event
-
以下程式碼片段為以空格分隔的日誌事件,其中包含七個欄位:ip
、user
、username
、timestamp
、request
、status_code
,和 bytes
。
127.0.0.1 Prod frank [10/Oct/2000:13:25:15 -0700] "GET /index.html HTTP/1.0" 404 1534
中括號 ("[]") 和雙引號 ("") 之間的字元被視為單一欄位。
- Writing filter patterns that match terms in a space-delimited log event
-
若要建立用來比對以空格分隔的日誌事件中詞彙的篩選條件模式,須將篩選條件模式括在中括號 ("[]") 中,並指定逗點 (",") 分隔名稱的欄位。下列篩選條件模式會分析七個欄位。
[ip=%127\.0\.0\.[1-9]%, user, username, timestamp, request =*.html*, status_code = 4*, bytes]
您可以使用數字運算子 (>、<、=、!=、>= 或 <=) 和星號 (*) 作為萬用字元或 regex,來建立篩選條件模式。在範例篩選條件模式中,ip
使用可比對 IP 地址範圍 127.0.0.1 - 127.0.0.9 的 regex,其中 request
包含萬用字元,說明必須擷取包含 .html
的值,status_code
包含萬用字元,說明必須擷取以 4
開頭的值。
如果您不知道在空格分隔的日誌事件中剖析的欄位數量,則可以使用刪節號 (...) 來引用任何未命名的欄位。刪節號可以用來引用所需數量的欄位。下列範例為帶刪節號的篩選條件模式,代表先前範例篩選條件模式中的前四個未命名欄位。
[..., request =*.html*, status_code = 4*, bytes]
您也可以使用邏輯運算子,邏輯與 (&&) 和邏輯或 (||) 來建立複合表達式。下列篩選條件模式包含一個複合表達式,該表達式表明 status_code
的值必須是 404
或是 410
。
[ip, user, username, timestamp, request =*.html*, status_code = 404 || status_code = 410, bytes]
您可以使用模式比對,來建立按照特定順序比對詞彙的以空格分隔的篩選條件模式。使用指示器指定詞彙的順序。使用 w1 來表示第一個詞彙,並使用 w2 等來表示後續詞彙的順序。在詞彙之間插入逗號 (",")。下列範例中的程式碼片段示範了如何使用模式,來比對以空格分隔的篩選條件模式。
建立篩選條件模式來比對以空格分隔的日誌事件中的詞彙時,您可以使用任何條件式規則運算式。如需支援的規則運算式清單,請參閱支援的規則運算式。
以空格分隔的日誌事件
INFO 09/25/2014 12:00:00 GET /service/resource/67 1200
INFO 09/25/2014 12:00:01 POST /service/resource/67/part/111 1310
WARNING 09/25/2014 12:00:02 Invalid user request
ERROR 09/25/2014 12:00:02 Failed to process request
- Example: Match terms in order
-
下列以空格分隔的篩選條件模式會傳回第一個單字為 ERROR (錯誤) 的日誌事件。
[w1=ERROR, w2]
建立使用模式比對的以空格分隔的篩選條件模式時,必須在指定詞彙的順序後加上一個空白指標。例如:如果您建立了一個篩選條件模式以傳回第一個單字為 ERROR 的日誌事件,請在 w1 詞彙後加上一個空白 w2 指標。
- Example: Match terms with AND (&&) and OR (||)
-
您可以使用邏輯運算子邏輯與 ("&&") 和邏輯或 ("||") 建立包含條件的以空格分隔的篩選條件模式。下列篩選條件模式會傳回第一個單字為 ERROR (錯誤) 或 WARNING (警告) 的日誌事件。
[w1=ERROR || w1=WARNING, w2]
- Example: Exclude terms from matches
-
您可以建立以空格分隔的篩選條件模式,以傳回排除一個或多個詞彙的日誌事件。將不等於符號 ("!=") 放在想要排除的一個或多個詞彙之前。下列程式碼片段為篩選條件模式範例,其會傳回第一個單字不是 ERROR (錯誤) 和 WARNING (警告) 的日誌事件。
[w1!=ERROR && w1!=WARNING, w2]
- Example: Match the top level item in a resource URI
-
下列程式碼片段為篩選條件模式的範例,其使用 regex 比對資源 URI 中的上層詞彙。
[logLevel, date, time, method, url=%/service/resource/[0-9]+$%, response_time]
- Example: Match the child level item in a resource URI
-
下列程式碼片段為篩選條件模式的範例,其使用 regex 比對資源 URI 中的子層詞彙。
[logLevel, date, time, method, url=%/service/resource/[0-9]+/part/[0-9]+$%, response_time]