CloudWatch Logs Insights クエリ構文
CloudWatch Logs Insights は、ロググループに対するクエリの実行に使用できるクエリ言語をサポートしています。各クエリには、1 つ以上のクエリコマンドを
Unix 形式のパイプ文字 (|
) で区切って含めることができます。
6 つのクエリコマンドがサポートされています。さらに、正規表現、算術オペレーション、比較オペレーション、数値関数、日時関数、文字列関数、汎用関数など、多数のサポート用の関数やオペレーションが用意されています。
コメントもサポートされています。クエリ内の #
文字で始まる行は無視されます。
@
シンボルで始まるフィールドは、CloudWatch Logs Insights によって生成されます。CloudWatch Logs が自動的に検出して生成するフィールドの詳細については、「サポートされるログと検出されるフィールド」を参照してください。
CloudWatch Logs Insights のクエリコマンド
次の表は、6 つのサポートされているクエリコマンドおよび基本的な例の一覧です。より強力なサンプルクエリについては、「サンプルクエリ」を参照してください。
コマンド | 説明 | 例 |
---|---|---|
|
クエリ結果に表示するフィールドを指定します。このコマンドをクエリで複数回指定すると、最後に指定したフィールドのみが使用されます。 |
次の例では、フィールド
|
|
指定したフィールドをログイベントから取得して表示します。 fields コマンド内で関数とオペレーションを使用して、表示するフィールド値を変更したり、クエリの残りの部分で使用する新しいフィールドを作成したりできます。 |
次の例では、
次の例では、エフェメラルフィールド
|
|
クエリの結果を 1 つ以上の条件に基づいてフィルタリングします。 |
次の例では、
次の例も有効なクエリですが、結果には個別のフィールドが表示されません。代わりに、duration が 2000 を超えるすべてのログイベントについて、
次の例では、
次の例では、
次の例では、
この最後の例では、値が「foo」、「bar」、または「1」の
|
|
ログフィールドの値に基づいて集約統計を計算します。 統計演算子として、 |
次の例では、
|
|
取得したログイベントをソートします。昇順 ( |
次の例では、返されたイベントを
|
|
クエリから返されるログイベントの数を指定します。 これを使用して、結果を小さい数値に制限し、関連する結果の小さいセットを表示することができます。さらに、 制限を指定しない場合、クエリにはデフォルトで最大 1000 行表示されます。 |
次の例では、
|
|
ログフィールドからデータを抽出し、1 つ以上のエフェメラルフィールドを作成してクエリでさらに処理できるようにします。 glob 式に、 正規表現をスラッシュ (/) で囲みます。式内では、抽出される一致した文字列の各部が、名前付きキャプチャグループで囲まれます。名前付きキャプチャグループの例は |
この単一のログ行を例として使用します。
次の 2 つの
次の例では、正規表現を使用してログフィールド
|
前の表のクエリコマンドに関する注意事項
前の表のクエリコマンドには、次のルール、ガイドライン、およびヒントが適用されます。
-
クエリ内のログフィールドの名前に @ 記号、ピリオド (.)、および英数字以外の文字が含まれている場合は、ログフィールドをバックティック (
`
) 文字で囲む必要があります。たとえば、foo-bar
フィールド名は、英数字以外の文字が含まれているためバックティック文字で囲む必要があります。 -
fields
とdisplay
の両方を使用して、クエリ結果に表示するフィールドを指定します。両者の違いは以下のとおりです。-
display
コマンドは、結果に表示するフィールドを指定する場合のみ使用します。fields
コマンドを as キーワードとともに使用すると、ログイベント内の関数とフィールドを使用して新しいエフェメラルフィールドを作成できます。たとえば、fields ispresent(resolverArn) as isRes
はクエリの残りの部分で使用できるisRes
という名前のエフェメラルフィールドを作成します。isRes
の値は、resolverArn
がログイベント内の検出されたフィールドであるかどうかに応じて 0 または 1 です。 -
複数の
fields
コマンドがあり、display
コマンドを含めない場合は、すべてのfields commands are displayed.
で指定されたフィールド -
複数の
display
コマンドがある場合は、最後のdisplay command are displayed.
で指定されたフィールドのみ
-
フィルターコマンドの一致と正規表現
filter
コマンドでは、比較演算子 (=、!=、<、<=、>、>=)、ブール演算子 (and
、or
、not
) および正規表現を使用できます。
in
を使用して、集合要素関係をテストできます。in
のすぐ後にチェックする要素を含む配列を配置します。in
では not
を使用できます。in
を使用した文字列一致は、完全な文字列一致でなければなりません。
部分文字列でフィルタリングするには、filter
コマンドで like
または =~
(等号の後にチルダ) を使用します。like
または =~
を使用して部分文字列の一致を実行するには、一致部分文字列を二重引用符または一重引用符で囲みます。正規表現一致を実行するには、一致文字列をスラッシュで囲みます。クエリは、設定した条件に一致するログイベントのみ返します。
例
以下の 3 つの例では、f1
に単語 Exception
が含まれているすべてのイベントを返します。最初の 2 つの例では、正規表現を使用します。3 番目の例では、部分文字列の一致を使用します。これら 3 つの例すべてで、大文字と小文字が区別されます。
fields f1, f2, f3 | filter f1 like /Exception/
fields f1, f2, f3 | filter f1 =~ /Exception/
fields f1, f2, f3 | filter f1 like "Exception"
次の例では、「Exception」の検索で大文字と小文字を区別しないように変更します。
fields f1, f2, f3 | filter f1 like /(?i)Exception/
次の例では、正規表現を使用します。これは、f1
が単語 Exception
と正確に一致するすべてのイベントを返します。クエリでは大文字と小文字は区別されません。
fields f1, f2, f3 | filter f1 =~ /^(?i)Exception$/
クエリでのエイリアスの使用
as
を使用してクエリに 1 つ以上のエイリアスを作成できます。エイリアスは、fields
コマンド、stats
コマンド、および sort
コマンドでサポートされています。
ログフィールドのエイリアスと、オペレーションや関数の結果のエイリアスを作成できます。
例
クエリコマンドでのエイリアスの使用例は以下のとおりです。
fields abs(myField) as AbsoluteValuemyField, myField2
myField
の絶対値を AbsoluteValuemyField
として返します。また、myField2
フィールドも返します。
stats avg(f1) as myAvgF1 | sort myAvgF1 desc
f1
の平均値を myAvgF1
として計算し、結果の値を降順で返します。
クエリでのコメントの使用
#
文字を使用して、クエリの行をコメントアウトすることができます。#
文字で始まる行は無視されます。この機能は、クエリに説明を追加したり、行を削除することなく 1 回の呼び出しで複雑なクエリの一部を一時的に無視したりする場合に役立ちます。
次の例では、クエリの 2 行目は無視されます。
fields @timestamp, @message # | filter @message like /delay/ | limit 20
サポートされているオペレーションと関数
クエリ言語は、以下の表に示すように、多数のタイプのオペレーションと関数をサポートしています。
比較オペレーション
比較オペレーションは、filter
コマンドで使用できます。また、他の関数の引数としても使用できます。比較オペレーションは、すべてのデータ型を引数として受け入れ、ブール値の結果を返します。
= != < <= > >=
ブール演算子
ブール演算子として and
、or
、および not
を使用できます。これらのブール演算子は、ブール値を返す関数でのみ使用できます。
算術オペレーション
算術オペレーションは、filter
コマンドと fields
コマンドで使用できます。また、他の関数の引数としても使用できます。算術オペレーションは、数値データ型を引数として受け入れ、数値結果を返します。
オペレーション | 説明 |
---|---|
|
加算 |
|
減算 |
|
乗算 |
|
除算 |
|
指数。 |
|
残余または剰余。 |
数値オペレーション
数値オペレーションは、filter
コマンドと fields
コマンドで使用できます。また、他の関数の引数としても使用できます。数値オペレーションは、数値データ型を引数として受け入れ、数値結果を返します。
オペレーション | 結果タイプ | 説明 |
---|---|---|
|
number |
絶対値。 |
|
number |
上限 ( |
|
number |
下限 ( |
|
number |
最大値を返します。 |
|
number |
最小値を返します。 |
|
number |
自然対数。 |
|
number |
平方根。 |
一般関数
一般関数は、filter
コマンドと fields
コマンドで使用できます。また、他の関数の引数としても使用できます。
関数 | 結果タイプ | 説明 |
---|---|---|
|
boolean |
フィールドが存在する場合は |
|
LogField |
リストから最初の null でない値を返します。 |
文字列関数
文字列関数は、filter
コマンドと fields
コマンドで使用できます。また、他の関数の引数としても使用できます。
関数 | 結果タイプ | 説明 |
---|---|---|
|
boolean |
フィールドが欠落しているか、空の文字列である場合、 |
|
boolean |
フィールドが欠落しているか、空の文字列であるか、空白が含まれている場合、 |
|
文字列 |
複数の文字列を連結します。 |
|
文字列 |
文字列の左側から空白を削除します。関数に 2 番目の文字列引数がある場合、 |
|
文字列 |
文字列の右側から空白を削除します。関数に 2 番目の文字列引数がある場合、 |
|
文字列 |
文字列の両端から空白を削除します。関数に 2 番目の文字列引数がある場合、 |
|
number |
文字列の長さを Unicode コードポイントで返します。 |
|
文字列 |
文字列を大文字に変換します。 |
|
文字列 |
文字列を小文字に変換します。 |
|
文字列 |
数値引数で指定されたインデックスから文字列の末尾までの部分文字列を返します。関数に 2 番目の数値引数がある場合、この引数には取得される部分文字列の長さが含まれます。たとえば、 |
|
文字列 |
|
|
number |
|
日時関数
日時関数は、filter
コマンドと fields
コマンドで使用できます。また、他の関数の引数としても使用できます。これらの関数では、集計関数を使用してクエリの時間バケットを作成できます。
日時関数の一部として、数字と m
(分) または h
(時間) で構成される期間を使用できます。たとえば、10m
は 10 分、1h
は 1 時間です。
関数 | 結果タイプ | 説明 |
---|---|---|
|
Timestamp |
|
|
Timestamp |
タイムスタンプを特定の期間に切り詰めます。たとえば、 |
|
Timestamp |
タイムスタンプを特定の期間に切り上げ、次に切り詰めます。たとえば、 |
|
Timestamp |
入力フィールドを Unix エポックからのミリ秒数として解釈し、タイムスタンプに変換します。 |
|
number |
指定されたフィールドで見つかったタイムスタンプを、Unix エポックからのミリ秒を表す数値に変換します。 |
IP アドレス関数
IP アドレス文字列関数は、filter
コマンドと fields
コマンドで使用できます。また、他の関数の引数としても使用できます。
関数 | 結果タイプ | 説明 |
---|---|---|
|
boolean |
フィールドが有効な IPv4 または IPv6 アドレスである場合、 |
|
boolean |
フィールドが有効な IPv4 アドレスである場合、 |
|
boolean |
フィールドが有効な IPv6 アドレスである場合、 |
|
boolean |
指定された v4 または v6 サブネット内でフィールドが有効な IPv4 または IPv6 アドレスである場合、 |
|
boolean |
指定された v4 サブネット内でフィールドが有効な IPv4 アドレスである場合、 |
|
boolean |
指定された v6 サブネット内でフィールドが有効な IPv6 アドレスである場合、 |
統計集計関数
集約関数は、stats
コマンドで使用できます。また、他の関数の引数としても使用できます。
関数 | 結果タイプ | 説明 |
---|---|---|
|
number |
指定したフィールドの値の平均。 |
|
number |
ログイベントをカウントします。 |
|
number |
フィールドの一意な値の数を返します。このフィールドの濃度が非常に高い場合 (一意な値が多数含まれている場合)、 |
|
LogFieldValue |
クエリを実行したログにおける、このログフィールドの値の最大数。 |
|
LogFieldValue |
クエリを実行したログにおける、このログフィールドの値の最小数。 |
|
LogFieldValue |
パーセンタイルは、データセットにおける値の相対的な位置を示します。たとえば、 |
|
number |
指定されたフィールドの値の標準偏差。 |
|
number |
指定したフィールドの値の合計。 |
統計非集計関数
非集約関数は、stats
コマンドで使用できます。また、他の関数の引数としても使用できます。
関数 | 結果タイプ | 説明 |
---|---|---|
|
LogField |
クエリを実行したうち最も早いタイムスタンプがあるログイベントから |
|
LogField |
クエリを実行したうち最も遅いタイムスタンプがあるログイベントから |
|
LogField |
クエリを実行したログをソートすると最初に来る |
|
LogField |
クエリを実行したログをソートすると最後に来る |