CloudWatch 検索式の構文

有効な検索式の形式は次のとおりです。

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

次に例を示します。

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

前の例では、ディメンション名として AWS/EC2 を持つすべてのメトリクスについて InstanceId 名前空間を検索します。検出したすべての CPUUtilization メトリクスと、Average 統計を示すグラフを返します。

検索式で検索できるのは、過去 2 週間以内にデータを報告したメトリクスだけです。

検索式の制限

検索式の最大クエリサイズは 1,024 文字です。1 つのグラフに最大 100 つの検索式を含めることができます。グラフには最大 500 の時系列を表示できます。

CloudWatch 検索式: トークン分割

SearchTerm を指定すると、検索機能でトークンが検索されます。トークンは、CloudWatch で、完全なメトリクス名、ディメンション名、ディメンション値、名前空間から自動的に生成される部分文字列です。CloudWatch により、元の文字列のキャメルケース文字で区別されたトークンが生成されます。数字は新しいトークンの開始部分として、英数字以外の文字は区切り文字として機能します。その結果、英数字以外の文字の前後にトークンが作成されます。

同じタイプのトークンの区切り文字の連続文字列は 1 つのトークンになります。

トークンはすべて小文字で生成されます。生成されたトークンの例を次の表に示します。

CloudWatch 検索式: 部分一致

SearchTerm を指定すると、検索語もトークン分割されます。CloudWatch は、部分一致に基づいてメトリクスを検索します。部分一致は、検索語から生成された単一のトークンと、メトリクス名、名前空間、ディメンション名、またはディメンション値から生成された単一のトークンとの一致を表します。

単一のトークンに一致する部分一致検索では、大文字と小文字は区別されません。たとえば、次のいずれかの検索語を使用して CustomCount1 メトリクスを返すことができます。

ただし、検索語 couNT は、cou と NT にトークン分割されるため、検索語に couNT を使用しても、CustomCount1 は見つかりません。

元の名前に連続して現れる複数のトークンである複合トークンにも一致するように検索することもできます。複合トークンと一致させるには、大文字と小文字を区別して検索します。たとえば、元の語が CustomCount1 で、CustomCount や Count1 と検索すると一致しますが、customcount や count1 では一致しません。

CloudWatch 検索式: 完全一致

完全一致を必要とする検索語の部分を二重引用符で囲むことで、検索語の完全一致のみを検索するように検索を定義することができます。これらの二重引用符は、検索語全体で使用される単一引用符で囲まれています。たとえば、CustomCount1 が MyNamespace という名前の名前空間にメトリクス名、ディメンション名、ディメンション値として存在する場合は、SEARCH(' {MyNamespace}, "CustomCount1" ', 'Maximum') で正確な文字列が検索されます。ただし、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 などの複数のサービスのメトリクスを含めることができます。

この検索を 1 つの 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')

また、名前空間とディメンション名/値をプロパティ名として使用することもできます。以下に例を示します。これらの例のうち、1 つ目は、部分一致検索でもプロパティ名を使用できることを示しています。

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 検索式: ブール演算子

ブール演算子 AND、OR、NOT を SearchTerm 内で使用して検索することができます。ブール演算子は、検索語全体を囲むために使用する単一引用符で囲まれています。ブール演算子では、大文字と小文字は区別されるため、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 が含まれるものは除く)。

強力で詳細な検索を行うには、ブール演算子を組み合わせることができます。以下に例を示します。演算子をグループ化するには括弧を使用します。

次の 2 つの例ではいずれも、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 メトリクスの合計を返します。

検索式と数式に個別の行を使用すると、より有用な結果が得られる場合があります。たとえば、グラフで次の 2 つの式を使用するとします。最初の行には、各 Lambda 関数の各 Errors 行が表示されます。この数式の ID は、e1 です。2 行目には、すべての関数からのエラーの合計を示す別の行が追加されています。

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