CloudWatch Logs Insights のクエリ構文
CloudWatch Logs Insights では、クエリ言語を使用してロググループに対するクエリの実行します。クエリ構文は、一般的な関数、算術演算と比較演算、正規表現など、さまざまな関数とオペレーションをサポートしています。複数のコマンドを含むクエリを作成します。コマンドはパイプ文字 (|) で区切ります。コメントを含むクエリを作成します。ハッシュ文字 (#) を使用してコメントを開始します。
注記
CloudWatch Logs Insights は、さまざまなログタイプのフィールドを自動で検出し、@ 文字で始まるフィールドを生成します。これらのフィールドの詳細については、「Amazon CloudWatch ユーザーガイド」の「サポートされるログと検出されるフィールド」を参照してください。
CloudWatch Logs Insights クエリコマンド
このセクションには、サポートされている CloudWatch Logs Insights クエリコマンドのリストが含まれています。
注記
このセクションのサンプルクエリのすべてがログイベントで機能するわけではありません。このセクションのクエリ例は、サポートされている CloudWatch Logs Insights クエリコマンドを使用してクエリをフォーマットする方法を示すことを目的としています。ログイベントの形式に合わせてクエリをフォーマットする必要がある場合があります。クエリの例については、「サンプルクエリ」を参照してください。
-
display
display
を使用して、クエリ結果の特定のフィールドを表示します。例: 1 つのフィールドを表示する
コードスニペットは、解析コマンドを使用して
@message
からデータを抽出し、エフェメラルフィールドloggingType
およびloggingMessage
を作成するクエリの例を示します。クエリは、loggingType
の値が ERROR であるすべてのログイベントを返します。display
は、クエリ結果にloggingMessage
の値のみを表示します。fields @message | parse @message "[*] *" as loggingType, loggingMessage | filter loggingType = "ERROR" | display loggingMessage
ヒント
クエリで 1 回だけ
display
を使用します。クエリでdisplay
を 2 回以上使用すると、クエリの結果には、使用されているdisplay
コマンドの直近の実行で指定されたフィールドが表示されます。 -
fields
fields
を使用して、クエリ結果の特定のフィールドを表示します。例: 特定のフィールドを表示する
コードスニペットは、20 個のログイベントを返し、降順で表示するクエリの例を示します。
@timestamp
と@message
の値がクエリ結果に表示されます。fields @timestamp, @message | sort @timestamp desc | limit 20
ヒント
display
を使用しないときは、このコマンドを使用します。fields
は、フィールド値を変更したり、クエリで使用できる新しいフィールドを作成したりするためのさまざまな機能やオペレーションをサポートしています。 -
filter
filter
を使用して、1 つ以上の条件に一致するログイベントを取得します。例: 1 つの条件を使用してログイベントをフィルタリングする
コードスニペットは、
range
の値が 3000 より大きいすべてのログイベントを返すクエリの例を示します。このクエリは、結果を 20 個のログイベントに制限し、ログイベントを@timestamp
別に降順で並べ替えます。fields @timestamp, @message | filter (range>3000) | sort @timestamp desc | limit 20
例: 複数の条件を使用してログイベントをフィルタリングする
キーワード
and
およびor
を使用して、複数の条件を組み合わせることができます。コードスニペットは、
range
の値が 3000 より大きく、accountId
の値が 123456789012 に等しいログイベントを返すクエリの例を示します。このクエリは、結果を 20 個のログイベントに制限し、ログイベントを@timestamp
別に降順で並べ替えます。fields @timestamp, @message | filter (range>3000 and accountId=123456789012) | sort @timestamp desc | limit 20
-
stats
stats
を使用して、ログフィールド値で集約統計を計算します。 -
sort
sort
を使用して、ログイベントを昇順 (asc
) または降順 (desc
) で表示します。 -
limit
limit
を使用して、クエリで返すログイベントの数を指定します。 -
parse
parse
を使用して、ログフィールドからデータを抽出し、クエリで処理できるエフェメラルフィールドを作成します。parse
は、ワイルドカードを使用するグロブモードと正規表現の両方をサポートします。ネストされた JSON フィールドは正規表現で解析できます。
例: ネストされた JSON フィールドの解析
コードスニペットは、取り込み中にフラット化された JSON ログイベントを解析する方法を示します。
{'fieldsA': 'logs', 'fieldsB': [{'fA': 'a1'}, {'fA': 'a2'}]}
コードスニペットは、
fieldsA
およびfieldsB
の値を抽出し、エフェメラルフィールドfld
およびarray
を作成する正規表現を含むクエリを示します。parse @message "'fieldsA': '*', 'fieldsB': ['*']" as fld, array
名前付きキャプチャグループ
正規表現で
parse
を使用すると、名前付きキャプチャグループを使用してパターンをフィールドに取り込むことができます。構文はparse @message (?<Name>pattern).
です。次の例では、VPC フローログのキャプチャグループを使用して、ENI を
NetworkInterface
という名前のフィールドに抽出します。parse @message /(?<NetworkInterface>eni-.*?) / display @timestamp, NetworkInterface
-
unmask
データ保護ポリシーにより一部のコンテンツがマスクされているログイベントのすべてのコンテンツを表示するには
unmask
を使用します。このコマンドを使用するには、logs:Unmask
アクセス許可が必要です。ロググループのデータ保護の詳細については、「機密性の高いログデータをマスキングで保護する」を参照してください。
注記
JSON ログイベントは取り込み中にフラット化されます。現在、ネストされた JSON フィールドを glob 表現で解析することはサポートされていません。解析できるのは、200 個以下のログイベントフィールドを含む JSON ログイベントのみです。ネストされた JSON フィールドを解析するときは、クエリ内の正規表現を JSON ログイベントの形式と一致するようにフォーマットする必要があります。
クエリコマンドを操作するためのガイドライン
クエリで指定されたログフィールドで、@
記号、ピリオド (.
)、英数字以外の文字を含むものは、バッククォートキー (`
) で囲む必要があります。例えば、ログフィールド foo-bar
では英数字以外の文字であるハイフン (`foo-bar`
) が含まれているため、バッククォート (-
) で囲む必要があります。
display
コマンドを使用して、クエリの結果で表示させたいフィールドを表示します。display
コマンドは、指定したフィールドだけを表示します。クエリに複数の display
コマンドが含まれている場合、クエリ結果には、最後の display
コマンドで指定したフィールドのみが表示されます。
fields
コマンドを as キーワードと共に使用すると、ログイベント内の関数とフィールドを使用してエフェメラルフィールドを作成できます。例えば、fields ispresent as isRes
はクエリの残りの部分で使用できる isRes
という名前のエフェメラルフィールドを作成します。
isRes
の値は 0 か 1 のどちらかになり、resolverArn
が検出されたフィールドであるかどうかによって変わります。クエリに複数の fields
コマンドがあり、display
コマンドが含まれない場合は、fields
コマンドで指定されたすべてのフィールドが表示されます。
フィルターコマンドの一致と正規表現
フィルターコマンドは、正規表現の使用をサポートします。以下の比較演算子 (=
、!=
、<
、<=
、>
、>=
) とブール演算子 (and
、or
、および not
) を使用できます。
キーワード in
を使用して集合要素関係をテストし、配列内の要素をチェックできます。配列の要素をチェックするには、in
の後に対象の配列を配置します。ブール演算子 not
および in
を使用できます。in
を使用するクエリを作成して、フィールドに文字列の一致があるログイベントを返すことができます。フィールドは完全な文字列でなければなりません。例えば、次のコードスニペットは、フィールド logGroup
が完全な文字列 example_group
であるログイベントを返すために in
を使用するクエリを示しています。
fields @timestamp, @message | filter logGroup in ["example_group"]
キーワードフレーズ like
および not like
を使用して、部分文字列を一致させることができます。正規表現の演算子 =~
を使用して部分文字列を一致させることができます。like
および not like
で部分文字列を一致させるには、単一引用符または二重引用符で一致させたい部分文字列を囲みます。正規表現パターンは、like
および not like
と共に使用できます。部分文字列を正規表現の演算子と一致させるには、一致させたい部分文字列をスラッシュで囲みます。次の例には、filter
コマンドを使用して部分文字列を照合する方法を示すコードスニペットが含まれます。
例: 部分文字列の一致
以下の例では、f1
に単語 Exception が含まれているログイベントを返します。これら 3 つの例すべてで、大文字と小文字が区別されます。
最初の例では、部分文字列を like
と一致させます。
fields f1, f2, f3 | filter f1 like "Exception"
2 番目の例では、部分文字列を like
および正規表現パターンと一致させます。
fields f1, f2, f3 | filter f1 like /Exception/
3 番目の例では、部分文字列を正規表現と一致させます。
fields f1, f2, f3 | filter f1 =~ /Exception/
例: 部分文字列をワイルドカードと一致させる
ピリオド記号 (.
) を正規表現のワイルドカードとして使用して、部分文字列に一致させることができます。次の例では、クエリは f1
の値が文字列 ServiceLog
で始まる一致を返します。
fields f1, f2, f3 | filter f1 like /ServiceLog./
ピリオド記号 (.*
) の後にアスタリスク記号を置いて、できるだけ多くの一致を返す貪欲な量指定子を作成することができます。例えば、次のクエリは f1
の値が文字列 ServiceLog
で始まるだけでなく、文字列 ServiceLog
も含む一致を返します。
fields f1, f2, f3 | filter f1 like /ServiceLog.*/
考えられる一致は、次のようにフォーマットされている可能性があります:
-
ServiceLogSampleApiLogGroup
-
SampleApiLogGroupServiceLog
例: 一致から部分文字列を除外する
次の例は、f1
に Exception という単語が含まれないログイベントを返すクエリを示しています。この例では大文字と小文字が区別されます。
fields f1, f2, f3 | filter f1 not like "Exception"
例: 大文字と小文字を区別しないパターンで部分文字列を一致させる
大文字と小文字を区別しない部分文字列を、like
および正規表現と一致させることができます。次のパラメータ (?i) を、一致させる部分文字列の前に配置します。次の例は、f1
に単語 Exception または exception が含まれるログベントを返すクエリを示しています。
fields f1, f2, f3 | filter f1 like /(?i)Exception/
クエリでのエイリアスの使用
エイリアスを含むクエリを作成します。ログフィールドの名前を変更するために、またはエフェメラルフィールドに値を抽出する場合にエイリアスを使用します。キーワード as
を使用して、ログフィールドまたは結果にエイリアスを指定します。クエリ内で複数のエイリアスを使用できます。次のコマンド内でエイリアスを使用できます。
-
fields
-
parse
-
sort
-
stats
次の例では、エイリアスを含むクエリを作成する方法を示します。
例
クエリの fields
コマンドはエイリアスを含みます。
fields @timestamp, @message, accountId as ID | sort @timestamp desc | limit 20
クエリは、フィールド @timestamp
、@message
、および accountId
の値を返します。結果は降順でソートされ、20 に制限されます。ID
の値は、エイリアス accountId
の下に一覧表示されます。
例
クエリの sort
および stats
コマンドはエイリアスを含みます。
stats count(*) by duration as time | sort time desc
クエリは、ロググループでフィールド duration
が発生した回数をカウントし、結果を降順で並べ替えます。duration
の値は、エイリアス time
の下に一覧表示されます。
クエリでのコメントの使用
CloudWatch Logs Insights は、クエリ内でのコメントをサポートしています。ハッシュ文字 (#) を使用してコメントを開始します。コメントを使用して、クエリまたはドキュメントクエリの行を無視できます。
例: クエリ
次のクエリを実行すると、2 行目は無視されます。
fields @timestamp, @message, accountId # | filter accountId not like "7983124201998" | sort @timestamp desc | limit 20
サポートされているオペレーションと関数
CloudWatch Logs Insights は次のオペレーションと関数をサポートしています。
算術演算子
算術演算子は、数値データ型を引数として受け入れ、数値結果を返します。算術演算子は、filter
コマンドと fields
コマンドで使用します。また、他の関数の引数としても使用します。
操作 | 説明 |
---|---|
|
加算 |
|
減算 |
|
乗算 |
|
除算 |
|
指数 ( |
|
残余または剰余 ( |
ブール演算子
ブール演算子 and
、or
、および not
を使用します。
注記
ブール演算子は、TRUE または FALSE の値を返す関数でのみ使用します。
比較演算子
比較演算子は、すべてのデータ型を引数として受け入れ、ブール値の結果を返します。比較オペレーションは、filter
コマンドで使用します。また、他の関数の引数としても使用します。
演算子 | 説明 |
---|---|
|
等しい |
|
等しくない |
|
未満 |
|
超 |
|
以下 |
|
以上 |
数値演算子
数値オペレーションは、数値データ型を引数として受け入れ、数値結果を返します。数値オペレーションは、filter
コマンドと fields
コマンドで使用します。また、他の関数の引数としても使用します。
操作 | 結果タイプ | 説明 |
---|---|---|
|
number |
絶対値 |
|
number |
上限 ( |
|
number |
下限 ( |
|
number |
最大値を返します |
|
number |
最小値を返します |
|
number |
自然対数 |
|
number |
平方根 |
日時関数
日時関数は、fields
コマンドと filter
コマンドで使用します。また、他の関数の引数としても使用します。これらの関数では、集計関数を使用してクエリの時間バケットを作成します。数字と m
(分) または h
(時間) で構成される期間を使用します。たとえば、10m
は 10 分、1h
は 1 時間です。次の表は、クエリコマンドで使用できるさまざまな日付時刻関数のリストを示したものです。このリストには、各関数の結果タイプと説明が記載されています。
ヒント
クエリコマンドを作成するときに、時間間隔セレクタを使用してクエリの対象とする期間を選択できます。例えば、5~30 分間隔、1 時間、3 時間、12 時間間隔、またはカスタム時間枠の期間を設定できます。また、特定の日付の間で期間を指定することもできます。
関数 | 結果タイプ | 説明 |
---|---|---|
|
タイムスタンプ |
これを使用して、複数のログエントリをクエリにまとめることができます。次の例では、1 時間あたりの例外の数を返します。
|
|
タイムスタンプ |
タイムスタンプを特定の期間に切り詰めます。たとえば、 |
|
タイムスタンプ |
タイムスタンプを特定の期間に切り上げ、次に切り詰めます。たとえば、 |
|
タイムスタンプ |
入力フィールドを Unix エポックからのミリ秒数として解釈し、タイムスタンプに変換します。 |
|
数値 |
指定されたフィールドで見つかったタイムスタンプを、Unix エポックからのミリ秒を表す数値に変換します。例えば、 |
注記
現在、CloudWatch Logs Insights では、可読性のあるタイムスタンプが記録されているログのフィルタリングをサポートしていません。
一般関数
一般関数は、fields
コマンドと filter
コマンドで使用します。また、他の関数の引数としても使用します。
関数 | 結果タイプ | 説明 |
---|---|---|
|
ブール値 |
フィールドが存在する場合は |
|
LogField |
リストから最初の null でない値を返します |
IP アドレス文字列関数
IP アドレス文字列関数は、filter
コマンドと fields
コマンドで使用します。また、他の関数の引数としても使用します。
関数 | 結果タイプ | 説明 |
---|---|---|
|
ブール型 |
フィールドが有効な IPv4 または IPv6 アドレスである場合、 |
|
ブール型 |
フィールドが有効な IPv4 アドレスである場合、 |
|
ブール型 |
フィールドが有効な IPv6 アドレスである場合、 |
|
ブール型 |
指定された v4 または v6 サブネット内でフィールドが有効な IPv4 または IPv6 アドレスである場合、 |
|
boolean |
指定された v4 サブネット内でフィールドが有効な IPv4 アドレスである場合、 |
|
boolean |
指定された v6 サブネット内でフィールドが有効な IPv6 アドレスである場合、 |
統計集計関数
集約関数は、stats
コマンドで使用します。また、他の関数の引数としても使用します。
関数 | 結果タイプ | 説明 |
---|---|---|
|
数値 |
指定したフィールドの値の平均。 |
|
数値 |
ログイベントをカウントします。 |
|
数値 |
フィールドの一意な値の数を返します。このフィールドの濃度が非常に高い場合 (一意な値が多数含まれている場合)、 |
|
LogFieldValue |
クエリを実行したログにおける、このログフィールドの値の最大数。 |
|
LogFieldValue |
クエリを実行したログにおける、このログフィールドの値の最小数。 |
|
LogFieldValue |
パーセンタイルは、データセットにおける値の相対的な位置を示します。たとえば、 |
|
数値 |
指定されたフィールドの値の標準偏差。 |
|
数値 |
指定したフィールドの値の合計。 |
統計非集計関数
非集約関数は、stats
コマンドで使用します。また、他の関数の引数としても使用します。
関数 | 結果タイプ | 説明 |
---|---|---|
|
LogField |
クエリを実行したうち最も早いタイムスタンプがあるログイベントから |
|
LogField |
クエリを実行したうち最も遅いタイムスタンプがあるログイベントから |
|
LogField |
クエリを実行したログをソートすると最初に来る |
|
LogField |
クエリを実行したログをソートすると最後に来る |
文字列関数
文字列関数は、fields
コマンドと filter
コマンドで使用します。また、他の関数の引数としても使用します。
関数 | 結果タイプ | 説明 |
---|---|---|
|
数値 |
フィールドが欠落しているか、空の文字列である場合、 |
|
数値 |
フィールドが欠落しているか、空の文字列であるか、空白が含まれている場合、 |
|
文字列 |
複数の文字列を連結します。 |
|
文字列 |
関数に 2 番目の文字列引数がない場合、文字列の左側からホワイトスペースを削除します。関数に 2 番目の文字列引数がある場合、ホワイトスペースは削除されません。その場合、 |
|
文字列 |
関数に 2 番目の文字列引数がない場合、文字列の右側からホワイトスペースを削除します。関数に 2 番目の文字列引数がある場合、ホワイトスペースは削除されません。その場合、 |
|
文字列 |
関数に 2 番目の文字列引数がない場合、文字列の両方の端からホワイトスペースを削除します。関数に 2 番目の文字列引数がある場合、ホワイトスペースは削除されません。その場合、 |
|
数値 |
文字列の長さを Unicode コードポイントで返します。 |
|
文字列 |
文字列を大文字に変換します。 |
|
文字列 |
文字列を小文字に変換します。 |
|
文字列 |
数値引数で指定されたインデックスから文字列の末尾までの部分文字列を返します。関数に 2 番目の数値引数がある場合、この引数には取得される部分文字列の長さが含まれます。たとえば、 |
|
文字列 |
例えば、関数 |
|
number |
|