篩選條件和模式語法
注意
如果您要尋找有關如何使用 Amazon CloudWatch Logs Insights 查詢語言查詢日誌群組的資訊，請參閱《查詢語法》。
您可以建立指標篩選條件，以比對日誌事件中的詞彙，並將日誌資料轉換為指標。當指標篩選條件與某個詞彙相符時，便會增加指標的計數。例如：您可以建立指標篩選條件來搜尋與計算日誌事件中單字 ERROR (錯誤) 的出現次數。
您可以對指標指派單位和維度。例如：如果您建立了一個指標篩選條件，以計算單字 ERROR (錯誤) 在日誌事件中出現的次數，則可以指定一個名為 ErrorCode 的維度，以顯示包含 ERROR (錯誤) 這個單字的日誌事件總數，並根據回報的錯誤代碼篩選資料。
提示
指派單位給指標時，務必指定正確的單位。如果隨後再更改單位，則更改可能無法生效。
主題
使用篩選條件模式比對日誌事件中的詞彙。
篩選條件模式構成了指標篩選條件用來比對日誌事件中詞彙的語法。詞彙可以是單字、完全相符字詞或數值。使用要比對的詞彙建立篩選條件模式。篩選條件模式僅傳回包含您所定義的詞彙的日誌事件。您可以在 CloudWatch 主控台測試篩選條件模式。下列程式碼片段範例，示範如何使用篩選條件模式來比對日誌事件中的詞彙。
注意
篩選條件模式區分大小寫。將完全相符字詞和包含非英數字元的詞彙括在雙引號 ("") 中。
範例：比對單一詞彙
下方程式碼片段為單一詞彙篩選條件模式的範例，其會傳回所有訊息中包含單字 ERROR (錯誤) 的日誌事件。
ERROR
篩選條件模式與以下日誌事件訊息相符：
[ERROR 400] BAD REQUEST[ERROR 401] UNAUTHORIZED REQUEST[ERROR 419] MISSING ARGUMENTS[ERROR 420] INVALID ARGUMENTS
範例：比對多個詞彙
以下程式碼片段為多項詞彙篩選條件範例，其會傳回所有訊息中包含單字 ERROR (錯誤) 和 ARGUMENTS (引數) 的日誌事件。
ERROR ARGUMENTS
篩選條件會傳回如下的日誌事件訊息：
[ERROR 419] MISSING ARGUMENTS[ERROR 420] INVALID ARGUMENTS
篩選條件模式不會傳回以下日誌事件訊息，因為它們不包含在篩選條件模式中指定的兩個詞彙。
[ERROR 400] BAD REQUEST[ERROR 401] UNAUTHORIZED REQUEST
範例：比對單一和多個詞彙
您可以使用模式比對，來建立會傳回包含單一和多個詞彙之日誌事件的篩選條件模式。將問號 ("?") 置於想要比對的詞彙之前。下列程式碼片段為篩選條件模式的範例，篩選條件模式會傳回所有訊息中包含單字 ERROR 或單字 ARGUMENTS 的日誌事件。
?ERROR ?ARGUMENTS
篩選條件模式與以下日誌事件訊息相符：
[ERROR 400] BAD REQUEST[ERROR 401] UNAUTHORIZED REQUEST[ERROR 419] MISSING ARGUMENTS[ERROR 420] INVALID ARGUMENTS
範例：比對完全相符字詞
下列程式碼片段為篩選條件的範例，其會傳回訊息中包含完全相符字詞 INTERNAL SERVER ERROR (內部伺服器錯誤) 的日誌事件。
"INTERNAL SERVER ERROR"
篩選條件模式會傳回以下日誌事件訊息：
[ERROR 500] INTERNAL SERVER ERROR
範例：包含詞彙和排除詞彙
您可以建立篩選條件模式，令其傳回訊息中包含某些詞彙，並排除其他詞彙的日誌事件。將減號 ("-") 置於想要排除的詞彙之前。下列程式碼片段為篩選條件模式的範例，其會傳回訊息中包含詞彙 ERROR (錯誤) 並排除詞彙 ARGUMENTS (引數) 的日誌事件。
ERROR -ARGUMENTS
篩選條件模式會傳回如下日誌事件訊息：
[ERROR 400] BAD REQUEST[ERROR 401] UNAUTHORIZED REQUEST
篩選條件模式不會傳回以下日誌事件訊息，因為它們包含單字 ARGUMENTS (引數)。
[ERROR 419] MISSING ARGUMENTS[ERROR 420] INVALID ARGUMENTS
範例：完全相符
您可以用雙引號比對日誌事件中的所有內容。下列程式碼片段為篩選條件模式的範例，其會傳回所有日誌事件。
" "
使用指標篩選條件從 JSON 日誌事件比對詞彙並擷取值
指標篩選條件是指包含篩選條件模式的組態。您可以建立指標篩選條件，以比對日誌事件中的詞彙，並將日誌資料轉換為指標。當您的指標篩選條件與某個詞彙相符時，便可以增加指標的計數。指標篩選條件僅比對您在篩選條件模式中定義的詞彙。您可以在 CloudWatch 主控台中測試指標篩選條件。您也可以建立指標篩選條件以比對詞彙，並從 JSON 日誌事件擷取值。下列範例為描述 JSON 詞彙字串和數值之指標篩選條件的語法。
範例：與字串比對的指標篩選條件
您可以建立指標篩選條件以比對 JSON 日誌事件中的字串。下列程式碼片段顯示的範例為以字串為基礎的指標篩選條件。
{PropertySelectorEqualityOperatorString}
將指標篩選條件括在大括號 ("{}") 中。以字串為基礎的指標篩選條件必須包含以下部分：
Property selector (屬性選擇器)
屬性選擇器以後面帶一個句點的貨幣符號 ("$.") 開始。屬性選擇器都是英數字元字串，並支援連字號 ("-") 和底線 ("_") 字元。字串不支援科學符號。屬性選擇器指向 JSON 日誌事件中的值節點。值節點可以是字串或數字。將陣列放在屬性選擇器之後。陣列中的元素依循從零開始的編號系統，意即陣列中的第一個元素是元素 0，第二個元素是元素 1，依此類推。將元素括在中括號內 ("[]")。如果屬性選擇器指向陣列或物件，則指標篩選條件會與日誌格式不相符。如果 JSON 屬性包含句點 (
".")，則可以使用括號標記法來選取該屬性。Equality operator (等式運算子)
等式運算子以下列符號之一開始：等於 ("=") 或不等於 ("!=")。等式運算子傳回布林值 (true 或 false)。
字串
您可以用雙引號 ("") 括住字串。包含除了英數字元和底線符號以外類型的字串必須置於雙引號中。使用星號 ("*") 作為萬用字元來比對文本。
下列程式碼片段包含一個指標篩選條件範例，示範如何設定指標篩選條件的格式，使用字串來比對 JSON 詞彙。
{ $.eventType = "UpdateTrail" }
範例：與數值比對的指標篩選條件
您可以建立指標篩選條件以比對 JSON 日誌事件中的數值。下列程式碼片段為與數值相符之指標篩選條件的語法範例。
{PropertySelectorNumericOperatorNumber}
將指標篩選條件括在大括號 ("{}") 中。比對數值的指標篩選條件必須包含以下部分：
Property selector (屬性選擇器)
屬性選擇器以後面帶一個句點的貨幣符號 ("$.") 開始。屬性選擇器都是英數字元字串，並支援連字號 ("-") 和底線 ("_") 字元。字串不支援科學符號。屬性選擇器指向 JSON 日誌事件中的值節點。值節點可以是字串或數字。將陣列放在屬性選擇器之後。陣列中的元素依循從零開始的編號系統，意即陣列中的第一個元素是元素 0，第二個元素是元素 1，依此類推。將元素括在中括號內 ("[]")。如果屬性選擇器指向陣列或物件，則指標篩選條件會與日誌格式不相符。如果 JSON 屬性包含句點 (
".")，則可以使用括號標記法來選取該屬性。Numeric operator (數值運算子)
數值運算子以下列符號之一開始：大於 (">")、小於 ("<")、等於 ("=")、不等於 ("!=")、大於等於 (">=") 或是小於等於 ("<=")。
數字
您可以使用包含加號 ("+") 或減號 ("-") 符號的整數，並遵守科學表示法。使用星號 ("*") 作為萬用字元來比對數字。
下列程式碼片段示範如何設定指標篩選條件的格式，使用數值來比對 JSON 詞彙。
// Metric filter with greater than symbol { $.bandwidth > 75 } // Metric filter with less than symbol { $.latency < 50 } // Metric filter with greater than or equal to symbol { $.refreshRate >= 60 } // Metric filter with less than or equal to symbol { $.responseTime <= 5 } // Metric filter with equal sign { $.errorCode = 400} // Metric filter with not equal sign { $.errorCode != 500 } // Metric filter with scientific notation and plus symbol { $.number[0] = 1e-3 } // Metric filter with scientific notation and minus symbol { $.number[0] != 1e+3 }
在 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" }
注意
如果要使用範例 JSON 日誌事件測試範例指標篩選條件，則必須在單行中輸入範例 JSON 日誌。
範例：與字串比對的指標篩選條件
指標篩選條件與屬性 "eventType" 中的字串 "UpdateTrail" 相符。
{ $.eventType = "UpdateTrail" }
範例：與數字比對的指標篩選條件
指標篩選條件包含一個萬用字元，並與屬性 "sourceIPAddress" 相符，因為其不包含帶有前綴的數字 "123.123."。
{ $.sourceIPAddress != 123.123.* }
範例：與陣列中元素比對的指標篩選條件
指標篩選條件與陣列 "arrayKey" 中的元素 "value" 相符。
{ $.arrayKey[0] = "value" }
範例：與陣列中的物件比對的指標篩選條件
指標篩選條件與陣列 "objectList" 中的物件 "id":2 相符。
{ $.objectList[1].id = 2 }
範例：符合金鑰中包含句點 (.) 的 JSON 屬性的指標篩選條件。
{ $.['cluster.name'] = "c" }
範例：指標篩選條件使用 IS 比對 JSON 日誌
您可以使用 IS 變數建立比對 JSON 日誌中欄位的指標篩選條件。IS 變數可以比對包含 NULL、TRUE 或 FALSE 值的欄位。下列指標篩選條件會傳回 SomeObject 值為 NULL 的 JSON 日誌。
{ $.SomeObject IS NULL }
範例：指標篩選條件使用 NOT EXISTS 比對 JSON 日誌
您可以使用 NOT EXISTS 變數建立指標篩選條件，以傳回日誌資料中不包含特定欄位的 JSON 日誌。下列指標篩選條件會使用 NOT EXISTS 傳回不包含欄位 SomeOtherObject 的 JSON 日誌。
{ $.SomeOtherObject NOT EXISTS }
注意
目前不支援變數 IS NOT 和 EXISTS。
使用複合表達式比對 JSON 物件中的詞彙
您可以在指標篩選條件中使用邏輯運算子邏輯與 ("&&") 和邏輯或 ("||") 來建立兩個或多個條件為真的，與日誌事件相符的複合表達式。複合表達式支援使用小括號 ("()") 和以下標準運算次序：() > && > ||。下列範例中的程式碼片段，示範如何將指標篩選條件與複合表達式相結合，來比對 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] ] }
範例：使用 AND (&&) 邏輯並且相符的表達式
該指標篩選條件包含的複合表達式，將 "user" 中的"id" 與數值 1，和 "email" 中的 "users" 與字串 "John.Doe@example.com" 相比對。
{ ($.user.id = 1) && ($.users[0].email = "John.Doe@example.com") }
範例：使用 OR (||) 邏輯且找到相符結果的表達式
該指標篩選條件包含的複合表達式，將 "user" 中的 "email" 與字串 "John.Stiles@example.com" 相比對。
{ $.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = "nonmatch" && $.actions[2] = "nonmatch" }
範例：使用 AND (&&) 邏輯但並不相符的表達式
該指標篩選條件包含一個找不到相符項目的複合表達式，因為該表達式與 "coordinates" 中的第一個和第二個座標，以及 "actions" 中的第三個動作不符。
{ ($.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = "nonmatch") && $.actions[2] = "nonmatch" }
範例：使用 OR (||) 邏輯但未找到相符結果的表達式
指標篩選條件包含一個找不到相符項目的複合表達式，因為該表達式與 "users" 中的第一個屬性，或 "actions" 中的第三個動作不符。
{ ($.user.id = 2 && $.users[0].email = "nonmatch") || $.actions[2] = "GET" }
使用指標篩選條件從空格分隔日誌事件中擷取值
您可以建立從空格分隔日誌事件中的欄位對應和擷取值的指標篩選條件。下列範例中的程式碼片段，包含顯示空格分隔的日誌事件、對應到空格分隔的日誌事件中欄位的指標篩選條件，以及指標篩選條件從空格分隔的日誌事件中的欄位所擷取的值。
範例：空格分隔的日誌事件
以下程式碼片段為以空格分隔的日誌事件，其中包含七個欄位：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
注意
中括號 ("[]") 和雙引號 ("") 之間的字元被視為單一欄位。
範例：指標篩選條件
要建立指標篩選條件，用來對應到以空格分隔的日誌事件中的欄位，並從中擷取值，須將指標篩選條件括在中括號 ("[]") 中，並指定以逗號 (",") 分隔名稱的欄位。下列指標篩選條件會分析七個欄位。
[ip, user, username, timestamp, request =*.html*, status_code = 4*, bytes]
您可以使用數字運算子 (>、<、=、!=、>= 或 <=) 和星號 (*) 作為萬用字元，來建立指標篩選條件。在範例指標篩選條件中，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]
範例：擷取的欄位和值
下列程式碼片段顯示了指標篩選條件從空格分隔的日誌事件中的欄位擷取的值。
{ "$bytes": "1534", "$status_code": "404", "$request": "GET /index.html HTTP/1.0", "$timestamp": "10/Oct/2000:13:25:15 -0700", "$username": "frank", "$user": "Prod", "$ip": "127.0.0.1" }
使用模式比對來比對空格分隔日誌事件中的詞彙
您可以使用模式比對，來建立按照特定順序比對詞彙的空格分隔指標篩選條件。使用指示器指定詞彙的順序。使用 w1 來表示第一個詞彙，並使用 w2 等來表示後續詞彙的順序。在詞彙之間插入逗號 (",")。下列範例中的程式碼片段，示範如何使用模式比對搭配空格分隔的指標篩選條件。
範例：按照順序比對詞彙
下列空格分隔的指標篩選條件，會傳回第一個單字為 ERROR (錯誤) 的日誌事件。
[w1=ERROR, w2]
注意
建立使用模式比對的空格分隔指標篩選條件時，必須在指定詞彙的順序後加上一個空白指標。例如：如果您建立了一個指標篩選條件以傳回第一個單字為 ERROR 的日誌事件，請在 w1 詞彙後加上一個空白 w2 指標。
範例：使用 AND (&&) 和 OR (||) 邏輯比對詞彙
您可以使用邏輯運算子邏輯與 ("&&") 和邏輯或 ("||") 建立包含條件的空格分隔的指標篩條件。下列指標篩選條件會傳回第一個單字為 ERROR (錯誤) 或 WARNING (警告) 的日誌事件。
[w1=ERROR || W1=WARNING, w2]
範例：從相符項目中排除詞彙
您可以建立空格分隔的指標篩選條件，以傳回排除一個或多個詞彙的日誌事件。將不等於符號 ("!=") 放在想要排除的一個或多個詞彙之前。下列程式碼片段為指標篩選條件範例，其會傳回第一個單字不是 ERROR (錯誤) 和 WARNING (警告) 的日誌事件。
[w1!=ERROR && w1!=WARNING, w2]
配置指標篩選條件的指標值
建立指標篩選條件時，您可以定義篩選條件模式，並指定指標的值和預設值。您可以將指標值設置為數字、名稱標識符或數字識別碼。如果您未指定預設值，指標篩選條件找不到相符項目時，CloudWatch 將不會回報資料。我們建議您指定預設值，即使該值為 0。設定預設值有助於 CloudWatch 更準確地回報資料，防止 CloudWatch 彙總起伏不定的指標。CloudWatch 每分鐘彙總並報告指標值。
指標篩選條件在日誌事件中找到相符項目時，會根據指標值增加指標的計數。如果指標篩選條件未找到相符項目，CloudWatch 會回報指標的預設值。例如：假設有一個日誌群組，每分鐘發佈兩個記錄且指標值為 1，預設值為 0。如果指標篩選條件第一分鐘內，在兩個日誌記錄中找到相符項目，則該分鐘的指標值為 2。如果指標篩選條件第二分鐘內，未在任何一筆記錄中找到相符項目，則該分鐘的預設值為 0。如果將維度分配給指標篩選條件產生的指標，則無法為這些指標指定預設值。
您也可以設置指標篩選條件，使用從日誌事件中擷取的值 (而非靜態值) 來增加指標。如需更多詳細資訊，請參閱 使用日誌事件中的值來增加指標的值。
從 JSON 或空格分隔日誌事件的值中將維度連同指標一起發佈
您可以使用 CloudWatch 主控台或 AWS CLI 建立指標篩選條件，用來發佈具有 JSON 和空格分隔的日誌事件產生之指標的維度。維度是名稱/數值配對，僅適用於 JSON 和空格分隔的篩選條件模式。您可以建立最多包含三個維度的 JSON 和空格分隔的指標篩選條件。如需維度以及如何將維度指派給指標的詳細資訊，請參閱下列各節：
《Amazon CloudWatch 使用者指南》中的維度
《Amazon CloudWatch Logs 使用者指南》中的範例：從 Apache 日誌中擷取欄位並指派維度
重要
維度包含與自訂指標相同收費的值。為了避免費用出乎意料，請勿將高基數欄位指定為維度，例如 IPAddress 或 requestID。
從日誌事件擷取的指標會以自訂指標收費。為了避免費用意外過高，如果指標篩選條件針對您已指定的維度，在一定時間內產生 1000 個不同的名稱/值組，Amazon 可能會停用該指標篩選條件。
您可以建立帳單警示，通知您預估的費用。如需詳細資訊，請參閱建立帳單警示來監控預估的 AWS 費用。
從 JSON 日誌事件將維度連同指標一起發佈
下列範例程式碼片段描述如何在 JSON 指標篩選條件中指定維度。
範例：JSON 日誌事件
{ "eventType": "UpdateTrail", "sourceIPAddress": "111.111.111.111", "arrayKey": [ "value", "another value" ], "objectList": [ {"name": "a", "id": 1 }, {"name": "b", "id": 2 } ] }
注意
如果要使用 JSON 日誌事件範例測試指標篩選條件範例，則必須在單行中輸入JSON 日誌範例。
範例：指標篩選條件
每當 JSON 日誌事件包含屬性 eventType 和 "sourceIPAddress" 時，指標篩選條件會增加指標。
{ $.eventType = "*" && $.sourceIPAddress != 123.123.* }
當您建立 JSON 指標篩選條件時，您可以將指標篩選條件中的任何屬性指定為維度。例如：若要設定 eventType 作為維度，請使用下列內容：
"eventType" : $.eventType
指標範例包含一個名為 "eventType" 的維度，其維度值在日誌事件範例中為 "UpdateTrail"。
從空格分隔日誌事件將維度連同指標一起發佈
下列範例程式碼片段，描述如何在空格分隔的指標篩選條件中指定維度。
範例：空格分隔的日誌事件
127.0.0.1 Prod frank [10/Oct/2000:13:25:15 -0700] "GET /index.html HTTP/1.0" 404 1534
範例：指標篩選條件
[ip, server, username, timestamp, request, status_code, bytes > 1000]
當空格分隔的日誌事件包含篩選條件中指定的任何欄位時，該指標篩選條件會增加指標。例如：指標篩選條件在空格分隔的日誌事件範例中查找下列欄位和值。
{ "$bytes": "1534", "$status_code": "404", "$request": "GET /index.html HTTP/1.0", "$timestamp": "10/Oct/2000:13:25:15 -0700", "$username": "frank", "$server": "Prod", "$ip": "127.0.0.1" }
當您建立空格分隔的指標篩選條件時，您可以將指標篩選條件中的任何欄位指定為維度。例如：若要設定 server 作為維度，請使用下列內容：
"server" : $server
指標篩選條件範例中有一個名為 server 的維度，其維度值在日誌事件範例中為 "Prod"。
使用日誌事件中的值來增加指標的值
您可以建立指標篩選條件來發佈日誌事件中找到的數值。本節中的過程中使用下列範例指標篩選條件，來示範如何將 JSON 日誌事件中的數值發佈到指標。
{ $.latency = * } metricValue: $.latency
建立在日誌事件中發佈的值的指標篩選條件
在 https://console.aws.amazon.com/cloudwatch/
開啟 CloudWatch 主控台。 -
在導覽窗格中，選擇 Logs (日誌)，然後選擇 Log groups (日誌群組)。
-
選擇或建立日誌群組。
如需詳細資訊，請參閱《Amazon CloudWatch Logs 使用者指南》中的在 CloudWatch Logs 中建立日誌群組。
-
選擇 Actions (動作)，然後選擇 Create metric filter (建立指標篩選條件)。
-
針對 Filter Pattern (篩選條件模式)，輸入
{ $.latency = * }，然後選擇 Next (下一步)。 -
針對 Metric Name (指標名稱)，輸入 myMetric。
-
針對 Metric Value (指標值)，輸入
$.latency。 (選用) 針對 Default Value (預設值)，輸入 0，然後選擇 Next (下一步)。
我們建議您指定預設值，即使該值為 0。設定預設值有助於 CloudWatch 更準確地回報資料，防止 CloudWatch 彙總起伏不定的指標。CloudWatch 每分鐘彙總並報告指標值。
選擇 Create metric filter (建立指標篩選條件)。
指標篩選條件的範例與 JSON 日誌事件範例中的詞彙 "latency" 相符，並將數值 50 發佈到指標 myMetric。
{ "latency": 50, "requestType": "GET" }
