CloudWatch 搜尋表達式語法 - Amazon CloudWatch
字符化部分相符完全符合排除指標結構描述在搜尋中指定屬性名稱非英數字元布林值運算子使用數學表達式

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

CloudWatch 搜尋表達式語法

有效的搜尋表達式有以下格式。

SEARCH(' {Namespace, DimensionName1, DimensionName2, ...} SearchTerm', 'Statistic')

例如：

SEARCH('{AWS/EC2,InstanceId} MetricName="CPUUtilization"', 'Average')

  • SEARCH 一詞後面以大括號括住的查詢第一部分，是要搜尋的指標結構描述。指標結構描述包含指標命名空間和一或多個維度名稱。搜尋查詢可選擇是否包含指標結構描述。如果指定，則指標結構描述必須包含命名空間，且可以選擇包含一或多個該命名空間中有效的維度名稱。

    您不需要在指標結構描述內使用引號，除非命名空間或維度名稱包含空格或非英數字元。在這種情況下，您必須使用雙引號括住包含這些字元的名稱。

  • SearchTerm 也是選用的，但有效的搜尋必須包含指標結構描述、SearchTerm 或兩者皆含。SearchTerm 通常包含一或多個帳戶 ID、指標名稱或維度值。SearchTerm 可以包含多個搜尋詞，部分相符和完全相符。也可以包含布林值運算子。

    在 SearchTerm 中使用帳戶 ID 這種方式僅適用於特定帳戶，即設定為 CloudWatch 跨帳戶觀察功能中監控帳戶的帳戶。SearchTerm 中帳戶 ID 的語法為 :aws.AccountId = 444455556666。您也可以使用 'LOCAL' 來指定監控帳戶本身：:aws.AccountId = 'LOCAL'

    如需詳細資訊，請參閱CloudWatch 跨帳戶觀察功能。

    SearchTerm 可以包含一或多個指示項，例如本範例中的 MetricName=，但使用指示項非必要。

    指標結構描述和 SearchTerm 必須使用一對單引號括在一起。

  • Statistic 是任何有效 CloudWatch 統計的名稱。它必須用單引號括住。如需詳細資訊，請參閱統計資料。

前一個範例搜尋有 InstanceId 維度名稱之任何指標的 AWS/EC2 命名空間。運算式會傳回找到的所有 CPUUtilization 指標，並以圖形顯示 Average 統計資料。

搜尋運算式只能找到過去兩週內已報告資料的指標。

搜尋表達式限制

搜尋表達式查詢大小上限為 1024 個字元。一個圖形最多可有 100 個搜尋表達式。圖形最多可以顯示 500 個時間序列。

CloudWatch 搜尋表達式：字符化

當您指定 SearchTerm 時，搜尋函數會搜尋字符，這些是 CloudWatch 從完整的指標名稱、維度名稱、維度值和命名空間自動產生的子字串。CloudWatch 產生的字符在原始字串中使用大寫連字區別。數值字元也可以做為新字符的開頭，然後使用英數字元做為分隔符號，在非英數字元的前後建立字符。

同類型字符分隔符號字元的連續字串會產生一個字符。

所有產生的字符都是小寫。下表顯示產生的一些字符範例。

原始字串 產生的字符

CustomCount1

customcount1, custom, count, 1

SDBFailure

sdbfailure, sdb, failure

Project2-trial333

project2trial333, project, 2, trial, 333

CloudWatch 搜尋表達式：部分相符

當您指定 SearchTerm 時，搜尋詞也會字符化。CloudWatch 會尋找部分相符的指標，這是產生自搜尋詞之單一字符和產生自指標名稱、命名空間、維度名稱或維度值產生之單一字符的相符項目。

部分相符會搜尋不區分大小寫的相符單一字符。例如，使用下列任一搜尋詞會傳回 CustomCount1 指標：

  • count

  • Count

  • COUNT

不過，使用 couNT 做為搜尋詞找不到 CustomCount1，因為搜尋詞 couNT 的大寫已字符化為 cou 和 NT。

搜尋也會比對複合字符，這是在原始名稱中連續出現的多個字符。為比對複合字符，搜尋會區分大小寫。例如，如果原始詞彙是 CustomCount1，則搜尋 CustomCount 或 Count1 會成功，但搜尋 customcount 或 count1 則否。

CloudWatch 搜尋表達式：完全相符

您可以使用雙引號括住搜尋詞需要完全相符的那部分，定義搜尋只尋找與搜尋詞完全相符的項目。這些雙引號是括在用來括住整個搜尋詞的單引號中。例如，SEARCH(' {MyNamespace}, "CustomCount1" ', 'Maximum') 會尋找確切的字串 CustomCount1，如果此字串在名為 MyNamespace 的命名空間中做為指標名稱、維度名稱或維度值。不過，搜尋 SEARCH(' {MyNamespace}, "customcount1" ', 'Maximum') 或 SEARCH(' {MyNamespace}, "Custom" ', 'Maximum') 找不到這個字串。

單一搜尋表達式可以結合部分相符詞和完全相符詞。例如，SEARCH(' {AWS/NetworkELB, LoadBalancer} "ConsumedLCUs" OR flow ', 'Maximum') 會傳回名為 ConsumedLCUs 的 Elastic Load Balancing 指標，以及所有包含字符 flow 的 Elastic Load Balancing 指標或維度。

使用完全相符也是尋找有特殊字元名稱的好方法，例如非英數字元或空格，如下列範例所示。

SEARCH(' {"My Namespace", "Dimension@Name"}, "Custom:Name[Special_Characters" ', 'Maximum')

CloudWatch 搜尋表達式：排除指標結構描述

到目前為止所示範的範例，都包含以大括號括住的指標結構描述。省略指標結構描述的搜尋也有效。

例如，SEARCH(' "CPUUtilization" ', 'Average') 會傳回與字串 CPUUtilization 完全相符的所有指標名稱、維度名稱、維度值和命名空間。在 AWS 指標命名空間中，這可能包含來自數個服務的指標，包括 Amazon EC2、Amazon ECS、SageMaker AI 等。

若要將此搜尋縮小為僅一個 AWS 服務，最佳實務是在指標結構描述中指定命名空間和任何必要的維度，如下列範例所示。雖然這會將搜尋縮小到 AWS/EC2 命名空間，但仍然會傳回其他指標的結果，如已將 CPUUtilization 定義為這些指標的維度值。

SEARCH(' {AWS/EC2, InstanceType} "CPUUtilization" ', 'Average')

或者，您可以在 SearchTerm 中新增命名空間，如以下範例所示。但在本範例中，搜尋會比對任何 AWS/EC2 字串，即使是自訂的維度名稱或值。

SEARCH(' "AWS/EC2" MetricName="CPUUtilization" ', 'Average')

CloudWatch 搜尋表達式：在搜尋中指定屬性名稱

以下 "CustomCount1" 的完全相符搜尋會傳回名稱完全一致的所有指標。

SEARCH(' "CustomCount1" ', 'Maximum')

但也會傳回具有 CustomCount1 維度名稱、維度值或命名空間的指標。若要進一步建構您的搜尋，您可以指定要在搜尋中尋找的物件類型屬性名稱。以下範例會搜尋所有命名空間，並傳回名為 CustomCount1 的指標。

SEARCH(' MetricName="CustomCount1" ', 'Maximum')

您也可以使用命名空間和維度名稱/值對做為屬性名稱，如下列範例所示。這些範例中的第一例，也示範了您可以使用屬性名稱加部分符合搜尋。

SEARCH(' InstanceType=micro ', 'Average')
SEARCH(' InstanceType="t2.micro" Namespace="AWS/EC2" ', 'Average')

CloudWatch 搜尋表達式：非英數字元

非英數字元做為分隔符號，並標記指標、維度、命名空間和搜尋詞等名稱要分隔到字符的位置。當詞彙字符化後，非英數字元會被去除，也不會出現在字符中。例如，Network-Errors_2 產生字符 network、errors 和 2。

您的搜尋詞可以包含任何非英數字元。如果這些字元出現在搜尋詞中，它們可以在部分相符中指定複合字符。例如，以下所有搜尋都會尋找名為 Network-Errors-2 或 NetworkErrors2 的指標。

network/errors
network+errors
network-errors
Network_Errors

當您正在執行完全相符搜尋時，完全相符搜尋中使用的任何非英數字元都必須是出現在要搜尋字串中的正確字元。例如，如果您想要尋找 Network-Errors-2，則搜尋 "Network-Errors-2" 會成功，但搜尋 "Network_Errors_2" 則否。

當您執行完全相符搜尋時，必須使用反斜線跳脫下列字元。

" \ ( )

例如，使用搜尋詞 "Europe\\France Traffic\(Network\)" 以完全相符尋找指標名稱 Europe\France Traffic(Network)

CloudWatch 搜尋表達式：布林值運算子

搜尋支援在 SearchTerm 中使用布林值運算子 AND、OR 和 NOT。布林值運算子是括在您括住整個搜尋詞的單引號中。布林值運算子區分大小寫，因此 and、or 和 not 不是有效的布林值運算子。

您可以在搜尋中明確使用 AND，例如 SEARCH('{AWS/EC2,InstanceId} network AND packets', 'Average')。在搜尋詞之間不使用任何布林值運算子，即默示使用 AND 運算子搜尋這些詞，所以 SEARCH(' {AWS/EC2,InstanceId} network packets ', 'Average') 會獲得相同的搜尋結果。

使用 NOT 排除部分結果資料。例如，SEARCH(' {AWS/EC2,InstanceId} MetricName="CPUUtilization" NOT i-1234567890123456 ', 'Average') 傳回您所有執行個體的 CPUUtilization，但執行個體 i-1234567890123456 除外。您也可以使用 NOT 子句做為唯一的搜尋詞。例如，SEARCH( 'NOT Namespace=AWS ', 'Maximum') 會得到您所有的自訂指標 (指標與不包含 AWS 的命名空間)。

查詢中可以使用多個 NOT 詞。例如，SEARCH(' {AWS/EC2,InstanceId} MetricName="CPUUtilization" NOT "ProjectA" NOT "ProjectB" ', 'Average') 傳回區域中所有執行個體的 CPUUtilization，但維度值為 ProjectA 或 ProjectB 的執行個體除外。

您可以使用布林值運算子組合執行更強大詳細的搜尋，如以下範例所示。使用括號分組運算子。

接下來的兩個範例都會傳回 EC2 和 EBS 命名空間中所有包含 ReadOps 的指標。

SEARCH(' (EC2 OR EBS) AND MetricName=ReadOps ', 'Maximum')
SEARCH(' (EC2 OR EBS) MetricName=ReadOps ', 'Maximum')

以下範例會將前一項的搜尋縮小至只包含 ProjectA 的結果，這可能是維度值。

SEARCH(' (EC2 OR EBS) AND ReadOps AND ProjectA ', 'Maximum')

以下範例使用巢狀分組。它會傳回所有函數中 Errors 的 Lambda 指標，以及名稱中包含字串 ProjectA 或 ProjectB 之函數的 Invocations。

SEARCH(' {AWS/Lambda,FunctionName} MetricName="Errors" OR (MetricName="Invocations" AND (ProjectA OR ProjectB)) ', 'Average')

CloudWatch 搜尋表達式：使用數學表達式

您可以在圖形中的數學表達式中使用搜尋表達式。

例如，SUM(SEARCH(' {AWS/Lambda, FunctionName} MetricName="Errors" ', 'Sum')) 會傳回所有 Lambda 函數之 Errors 指標的總和。

搜尋表達式和數學表達式使用不同行可能會得到更多有用的結果。例如，假設您在圖形中使用以下兩個表達式。第一行分別顯示每個 Lambda 函數的 Errors 行。此表達式的 ID 是 e1。第二行會新增另一列顯示所有函數的錯誤總和。

SEARCH(' {AWS/Lambda, FunctionName}, MetricName="Errors" ', 'Sum')
SUM(e1)