CloudWatch Logs Insights のクエリ構文

CloudWatch Logs Insights は、ロググループに対するクエリの実行に使用できるクエリ言語をサポートしています。クエリ構文は、一般的な関数、算術演算と比較演算、正規表現など、さまざまな関数とオペレーションをサポートしています。クエリには複数のクエリコマンドを含めることができます。クエリ内のクエリコマンドは、Unix 形式のパイプ文字 (|) で区切ります。クエリ構文の詳細については、「サポートされているオペレーションと関数」を参照してください。

CloudWatch Logs Insights は、クエリ内でのコメントの使用をサポートしています。ハッシュ記号 (#) で始まる行は無視されます。CloudWatch Logs Insights は、多くのログタイプのフィールドを自動で検出し、@ シンボルで始まるフィールドを生成します。CloudWatch Logs が自動的に生成するフィールドの詳細については、「Amazon CloudWatch ユーザーガイド」の「サポートされるログと検出されるフィールド」を参照してください。

CloudWatch Logs Insights クエリコマンド

次の表は、サポートされている CloudWatch Logs Insights のクエリコマンドおよびベーシックな例のリストです。クエリとその他のログタイプの一般的なクエリの例については、「Amazon CloudWatch Logs ユーザーガイド」の「サンプルクエリ」を参照してください。

コマンド	説明	例
display	クエリ結果に表示するフィールドを指定します。このコマンドをクエリで複数回使用すると、クエリ結果には、最後に使用した display コマンドで指定したフィールドのみが表示されます。	次のクエリの例にはフィールド @message が含まれています。parse コマンドは、メッセージログ形式から値を抽出し、エフェメラルフィールド loggingType と loggingMessage を作成します。このクエリは、ERROR の値として loggingType を持つイベントのみにログイベントをフィルタリングし、結果にはそれらのイベントの loggingMessage のみを表示します。 fields @message | parse @message "[*] *" as loggingType, loggingMessage | filter loggingType = "ERROR" | display loggingMessage
fields	指定したフィールドをログイベントから取得して表示します。クエリに display コマンドが含まれていない場合、クエリ結果には、fields コマンドで指定したフィールドが表示されます。 fields コマンド内で関数とオペレーションを使用して、表示するフィールド値を変更したり、クエリの残りの部分で使用する新しいフィールドを作成したりできます。	次の例では、foo-bar フィールドと action フィールドを表示し、さらにロググループ内のすべてのログイベントについて f3 と f4 の差異の絶対値を表示します。 fields `foo-bar`, action, abs(f3-f4) 次の例では、エフェメラルフィールド opStatus を作成して表示します。各ログエントリの opStatus の値は、Operation フィールドと StatusCode フィールドの値がハイフンで連結されたものです。 fields concat(Operation, '-', StatusCode) as opStatus
filter	クエリの結果を 1 つ以上の条件に基づいてフィルタリングします。filter コマンドは、さまざまな演算子や式をサポートしています。詳細については、「フィルターコマンドの一致と正規表現」を参照してください。	次の例では、duration フィールドの値が 2000 を超えるすべてのログイベントについて、f1 フィールド、f2 フィールド、および f3 フィールドを取得します。 fields f1, f2, f3 | filter (duration>2000) 次の例は先ほどのクエリと似ていますが、クエリの結果には個別のフィールドが表示されません。代わりに、2 つ目のクエリでは duration が 2000 を超えるすべてのログイベントについて、@timestamp フィールドと、@message フィールド内のすべてのログデータが結果に表示されます。 filter (duration>2000) 次の例では、f1 が 10 であるか、f3 が 25 を超えるすべてのログイベントについて、f1 フィールドと f2 フィールドを取得します。 fields f1, f2 | filter (f1=10 or f3>25) 次の例では、statusCode フィールドの値が 200～299 であるログイベントを返します。 fields f1 | filter statusCode like /2\d\d/ 次の例では、statusCode フィールドの値が 200～299 以外のログイベントを返します。 fields f1 | filter statusCode not like /2\d\d/ 次の例では、statusCode が「300」、「400」、または「500」であるログイベントを返します。 fields @timestamp, @message | filter statusCode in [300,400,500] この最後の例では、値が「foo」、「bar」、または「1」の Type フィールドを持たないログイベントを返します。 fields @timestamp, @message | filter Type not in ["foo","bar",1]
stats	ログフィールドの値で集計した統計を算出します。stats コマンドに by を付けることで、条件を 1 つ以上指定できます。統計データは、指定の条件でグループ化できます。 stats コマンドでは、sum()、avg()、count()、min()、および max() の演算子がサポートされます。	次の例では、f1 の一意の値ごとに f2 の平均値を計算します。 stats avg (f1) by f2 次の例では、1 時間あたりの例外の数をカウントします。 filter @message like /Exception/ | stats count(*) as exceptionCount by bin(1h) | sort exceptionCount desc この例では、エフェメラルフィールド [exceptionCount] のメッセージに [「Exception」] という単語が現れた合計回数が as によってグループ化され、[bin(1h)] フィールドの統計データが by によってグループ化されます。
sort	取得したログイベントをソートします。昇順 (asc) と降順 (desc) の両方がサポートされています。	次の例では、返されたイベントを f1 の値に基づいて降順にソートし、f1、f2、f3 の各フィールドを表示します。 fields f1, f2, f3 | sort f1 desc
limit	クエリから返されるログイベントの数を指定します。 これを使用して、結果を小さい数値に制限し、関連する結果の小さいセットを表示することができます。さらに、limit で 1000 ～ 10,000 の数値を使用し、コンソールに表示されるクエリ結果の行数を、デフォルトの 1000 行より大きい数に増やすこともできます。 制限を指定しない場合、クエリにはデフォルトで最大 1000 行表示されます。	次の例では、@timestamp の値に基づいてイベントを降順にソートして、ソート順で最初の 25 件のイベントの f1 フィールドと f2 フィールドを返します。この場合、ソート順は最新のタイムスタンプから開始されるため、最新の 25 件のイベントが返されます。 sort @timestamp desc | limit 25 | display f1, f2
parse	ログフィールドからデータを抽出し、1 つ以上のエフェメラルフィールドを作成してクエリでさらに処理できるようにします。 parse コマンドは、glob 表現と正規表現をサポートしています。 glob 表現の場合は、定数文字列 (一重引用符または二重引用符で囲まれた文字) を parse コマンドと共に使用します。変数テキストはアスタリスク (*) に置き換えます。アスタリスクはワイルドカードとして機能します。アスタリスクの後にキーワード as を使用してワイルドカード値をエフェメラルフィールドに抽出し、エイリアスを指定します。 正規表現をスラッシュ (/) で囲みます。式では、抽出される一致した文字列の各部が、名前付きキャプチャグループで囲まれます。名前付きキャプチャグループの例は (?<name>.*) で、name が名前で、.* はパターンです。	この単一のログ行を例として使用します。 25 May 2019 10:24:39,474 [ERROR] {foo=2, bar=data} The error was: DataIntegrityException 次の 2 つの parse 式は、それぞれ以下のことを行います。エフェメラルフィールド level、config、および exception が作成されます。level の値は ERROR、config の値は {foo=2, bar=data}、exception の値は DataIntegrityException です。最初の例は glob 式を使用し、2 番目の式は正規表現を使用します。 parse @message "[*] * The error was: *" as level, config, exception parse @message /\[(?<level>\S+)\]\s+(?<config>\{.*\})\s+The error was: (?<exception>\S+)/ この単一のログ行を例として使用します。 25 May 2019 10:24:39,474 user=user1234, method=sampleMethod, latency := 216 次の例では、正規表現を使用して、ログフィールド user2 から、エフェメラルフィールド method2、latency2、および @message を抽出し、method2 と user2 の一意的な組み合わせごとに平均レイテンシーを返します。 parse @message /user=(?<user2>.*?), method=(?<method2>.*?), latency := (?<latency2>.*?)/ | stats avg(latency2) by method2, user2

クエリコマンドを操作するためのガイドライン

クエリで指定されたログフィールドで、@ 記号、ピリオド (.)、英数字以外の文字を含むものは、バッククォートキー (`) で囲む必要があります。例えば、ログフィールド 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) を使用できます。

注記

ユーザーが正規表現に精通していることを前提としています。CloudWatch Logs Insights は、複数の正規表現マッチングライブラリである Hyperscan をサポートしています。ハイパースキャンの詳細については、ハイパースキャンのウェブサイトを参照してください。

キーワード 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/

最後の例では、部分文字列を正規表現と一致させます。

fields f1, f2, f3 
| filter f1 =~ /Exception/

例: 部分文字列をワイルドカードと一致させる

アスタリスク記号 (*) を正規表現のワイルドカードとして使用して、部分文字列に一致させることができます。次の例は、f1 に文字 E で始まる単語が含まれているログイベントを返します。この例では大文字と小文字が区別されます。

fields f1, f2, f3
| filter f3 like /E*/

注記

アスタリスク記号の前にピリオドを置いて (.*)、できるだけ多くの一致を返す貪欲な量指定子を作成することができます。

例: 一致から部分文字列を除外する

次の例は、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 を使用してクエリに 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 コマンドで使用できます。また、他の関数の引数としても使用できます。算術オペレーションは、数値データ型を引数として受け入れ、数値結果を返します。

オペレーション	説明
a + b	加算
a - b	減算
a * b	乗算
a / b	除算
a ^ b	指数。2 ^ 3 は 8 を返します。
a % b	残余または剰余。10 % 3 は 1 を返します。

数値演算子

数値オペレーションは、filter コマンドと fields コマンドで使用できます。また、他の関数の引数としても使用できます。数値オペレーションは、数値データ型を引数として受け入れ、数値結果を返します。

オペレーション	結果タイプ	説明
abs(a: number)	数値	絶対値。
ceil(a: number)	数値	上限 (a の値より大きい最小整数) に切り上げられます。
floor(a: number)	数値	下限 (a の値より小さい最大整数) に切り下げられます。
greatest(a: number, ...numbers: number[])	数値	最大値を返します。
least(a: number, ...numbers: number[])	数値	最小値を返します。
log(a: number)	数値	自然対数。
sqrt(a: number)	数値	平方根。

一般関数

一般関数は、filter コマンドと fields コマンドで使用できます。また、他の関数の引数としても使用できます。

関数	結果タイプ	説明
ispresent(fieldName: LogField)	ブール型	フィールドが存在する場合は true を返します。
coalesce(fieldName: LogField, ...fieldNames: LogField[])	LogField	リストから最初の null でない値を返します。

文字列関数

文字列関数は、filter コマンドと fields コマンドで使用できます。また、他の関数の引数としても使用できます。

関数	結果タイプ	説明
isempty(fieldName: string)	数値	フィールドが欠落しているか、空の文字列である場合、1 を返します。
isblank(fieldName: string)	数値	フィールドが欠落しているか、空の文字列であるか、空白が含まれている場合、1 を返します。
concat(str: string, ...strings: string[])	文字列	複数の文字列を連結します。
ltrim(str: string) ltrim(str: string, trimChars: string)	文字列	関数に 2 番目の文字列引数がない場合、文字列の左側からホワイトスペースを削除します。関数に 2 番目の文字列引数がある場合、ホワイトスペースは削除されません。その場合、strの左から trimChars 個の文字が削除されます。たとえば、ltrim("xyZxyfooxyZ","xyZ") は "fooxyZ" を返します。
rtrim(str: string) rtrim(str: string, trimChars: string)	文字列	関数に 2 番目の文字列引数がない場合、文字列の右側からホワイトスペースを削除します。関数に 2 番目の文字列引数がある場合、ホワイトスペースは削除されません。その場合、strの右から trimChars 個の文字が削除されます。たとえば、rtrim("xyZfooxyxyZ","xyZ") は "xyZfoo" を返します。
trim(str: string) trim(str: string, trimChars: string)	文字列	関数に 2 番目の文字列引数がない場合、文字列の両方の端からホワイトスペースを削除します。関数に 2 番目の文字列引数がある場合、ホワイトスペースは削除されません。その場合、strの両方から trimChars 個の文字が削除されます。たとえば、trim("xyZxyfooxyxyZ","xyZ") は "foo" を返します。
strlen(str: string)	数値	文字列の長さを Unicode コードポイントで返します。
toupper(str: string)	文字列	文字列を大文字に変換します。
tolower(str: string)	文字列	文字列を小文字に変換します。
substr(str: string, startIndex: number) substr(str: string, startIndex: number, length: number)	文字列	数値引数で指定されたインデックスから文字列の末尾までの部分文字列を返します。関数に 2 番目の数値引数がある場合、この引数には取得される部分文字列の長さが含まれます。たとえば、substr("xyZfooxyZ",3, 3) は "foo" を返します。
replace(fieldName: string, searchValue: string, replaceValue: string)	文字列	searchValue の fieldName: string のすべてのインスタンスを replaceValue に置き換えます。 例えば、関数 replace(logGroup,"smoke_test","Smoke") はフィールド logGroup に文字列値 smoke_test を含むログイベントを検索し、その値を文字列 Smoke に置き換えます。
strcontains(str: string, searchValue: string)	number	str に searchValue が含まれている場合は 1 を返し、それ以外の場合は 0 を返します。

日時関数

日時関数は、filter コマンドと fields コマンドで使用できます。また、他の関数の引数としても使用できます。これらの関数では、集計関数を使用してクエリの時間バケットを作成できます。数字と m (分) または h (時間) で構成される期間も使用できます。たとえば、10m は 10 分、1h は 1 時間です。次の表は、クエリコマンドで使用できるさまざまな日付時刻関数のリストを示したものです。このリストには、各関数の結果タイプと説明が記載されています。

注記

クエリコマンドを作成するときに、時間間隔セレクタを使用してクエリの対象とする期間を選択できます。例えば、5～30 分間隔、1 時間、3 時間、12 時間間隔、またはカスタム時間枠の期間を設定できます。また、特定の日付の間で期間を指定することもできます。クエリコマンドの実行方法については、「Amazon CloudWatch Logs ユーザーガイド」の「チュートリアル: サンプルクエリを実行および変更する」を参照してください。

関数	結果タイプ	説明
bin(period: Period)	タイムスタンプ	@timestamp の値を特定の期間に切り上げ、次に切り詰めます。例えば、bin(5m) は @timestamp の値を切り詰める前に、5 分刻みで四捨五入を行います。
datefloor(timestamp: Timestamp, period: Period)	タイムスタンプ	タイムスタンプを特定の期間に切り詰めます。たとえば、datefloor(@timestamp, 1h) は @timestamp のすべての値を 1 時間の下限に切り詰めます。
dateceil(timestamp: Timestamp, period: Period)	タイムスタンプ	タイムスタンプを特定の期間に切り上げ、次に切り詰めます。たとえば、dateceil(@timestamp, 1h) は @timestamp のすべての値を 1 時間の上限に切り詰めます。
fromMillis(fieldName: number)	タイムスタンプ	入力フィールドを Unix エポックからのミリ秒数として解釈し、タイムスタンプに変換します。
toMillis(fieldName: Timestamp)	数値	指定されたフィールドで見つかったタイムスタンプを、Unix エポックからのミリ秒を表す数値に変換します。例えば、toMillis(@timestamp) はタイムスタンプを 2022-01-14T13:18:031.000-08:00 から 1642195111000 に変換します。

注記

現在、CloudWatch Logs Insights では、可読性のあるタイムスタンプが記録されているログのフィルタリングをサポートしていません。

IP アドレス関数

IP アドレス文字列関数は、filter コマンドと fields コマンドで使用できます。また、他の関数の引数としても使用できます。

関数	結果タイプ	説明
isValidIp(fieldName: string)	ブール型	フィールドが有効な IPv4 または IPv6 アドレスである場合、true を返します。
isValidIpV4(fieldName: string)	ブール型	フィールドが有効な IPv4 アドレスである場合、true を返します。
isValidIpV6(fieldName: string)	ブール型	フィールドが有効な IPv6 アドレスである場合、true を返します。
isIpInSubnet(fieldName: string, subnet: string)	ブール型	指定された v4 または v6 サブネット内でフィールドが有効な IPv4 または IPv6 アドレスである場合、true を返します。サブネットを指定するときは、 192.0.2.0/24 や 2001:db8::/32 などの CIDR 表記を使用します。
isIpv4InSubnet(fieldName: string, subnet: string)	ブール型	指定された v4 サブネット内でフィールドが有効な IPv4 アドレスである場合、true を返します。サブネットを指定する場合は、192.0.2.0/24 などの CIDR 表記を使用します。
isIpv6InSubnet(fieldName: string, subnet: string)	ブール型	指定された v6 サブネット内でフィールドが有効な IPv6 アドレスである場合、true を返します。サブネットを指定する場合は、2001:db8::/32 などの CIDR 表記を使用します。

統計集計関数

集約関数は、stats コマンドで使用できます。また、他の関数の引数としても使用できます。

関数	結果タイプ	説明
avg(fieldName: NumericLogField)	数値	指定したフィールドの値の平均。
count() count(fieldName: LogField)	数値	ログイベントをカウントします。count() (または count(*)) は、クエリによって返されたすべてのイベントをカウントし、count(fieldName) は指定されたフィールド名を含むすべてのレコードをカウントします。
count_distinct(fieldName: LogField)	数値	フィールドの一意な値の数を返します。このフィールドの濃度が非常に高い場合 (一意な値が多数含まれている場合)、count_distinct から返される値は単なる概算値です。
max(fieldName: LogField)	LogFieldValue	クエリを実行したログにおける、このログフィールドの値の最大数。
min(fieldName: LogField)	LogFieldValue	クエリを実行したログにおける、このログフィールドの値の最小数。
pct(fieldName: LogFieldValue, percent: number)	LogFieldValue	パーセンタイルは、データセットにおける値の相対的な位置を示します。たとえば、pct(@duration, 95) が @duration 値を返した場合、@duration の値の 95% がこの値より低く、5% がこの値より高くなります。
stddev(fieldName: NumericLogField)	数値	指定されたフィールドの値の標準偏差。
sum(fieldName: NumericLogField)	数値	指定したフィールドの値の合計。

統計非集計関数

非集約関数は、stats コマンドで使用できます。また、他の関数の引数としても使用できます。

関数	結果タイプ	説明
earliest(fieldName: LogField)	LogField	クエリを実行したうち最も早いタイムスタンプがあるログイベントから fieldName の値を返します。
latest(fieldName: LogField)	LogField	クエリを実行したうち最も遅いタイムスタンプがあるログイベントから fieldName の値を返します。
sortsFirst(fieldName: LogField)	LogField	クエリを実行したログをソートすると最初に来る fieldName の値を返します。
sortsLast(fieldName: LogField)	LogField	クエリを実行したログをソートすると最後に来る fieldName の値を返します。