CloudWatch Logs Insights のクエリ構文 - Amazon CloudWatch Logs
サポートされているクエリコマンドフィルターコマンドの一致と正規表現クエリでのエイリアスの使用クエリでのコメントの使用サポートされているオペレーションと関数

CloudWatch Logs Insights のクエリ構文

CloudWatch Logs Insights は、ロググループに対するクエリの実行に使用できるクエリ言語をサポートしています。各クエリには、1 つ以上のクエリコマンドを Unix 形式のパイプ文字 (|) で区切って含めることができます。

6 つのクエリコマンドがサポートされています。さらに、正規表現、算術オペレーション、比較オペレーション、数値関数、日時関数、文字列関数、汎用関数など、多数のサポート用の関数やオペレーションが用意されています。

コメントもサポートされています。クエリ内の # 文字で始まる行は無視されます。

@ シンボルで始まるフィールドは、CloudWatch Logs Insights によって生成されます。CloudWatch Logs が自動的に検出して生成するフィールドの詳細については、サポートされるログと検出されるフィールド を参照してください。

CloudWatch Logs Insights クエリコマンド

次の表は、6 つのサポートされているクエリコマンドおよび基本的な例の一覧です。より強力なサンプルクエリについては、「サンプルクエリ」を参照してください。

コマンド 説明 例

display

クエリ結果に表示するフィールドを指定します。このコマンドをクエリで複数回指定すると、最後に指定したフィールドのみが使用されます。

次の例では、フィールド @message を使用し、エフェメラルフィールド loggingType および loggingMessage を作成して、クエリで使用します。これは、ERROR の値として loggingType を持つイベントのみにイベントをフィルタリングしますが、結果にはそれらのイベントの loggingMessage フィールドのみを表示します。 

fields @message
    | parse @message "[*] *" as loggingType, loggingMessage
    | filter loggingType = "ERROR"
    | display loggingMessage

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 コマンドでは、さまざまな演算子や式を使用できます。詳細については、「フィルターコマンドの一致と正規表現」を参照してください。

次の例では、f1 フィールドの値が 2000 を超えるすべてのログイベントについて、f2 フィールド、f3 フィールド、および duration フィールドを取得します。 

fields f1, f2, f3 | filter (duration>2000)

次の例も有効なクエリですが、結果には個別のフィールドが表示されません。代わりに、duration が 2000 を超えるすべてのログイベントについて、@timestamp フィールド内のすべてのログデータおよび @message が結果に表示されます。 

filter (duration>2000)

次の例では、f1 が 10 であるか、f2 が 25 を超えるすべてのログイベントについて、f1 フィールドと f3 フィールドを取得します。 

fields f1, f2 | filter (f1=10 or f3>25)

次の例では、statusCode フィールドの値が 200～299 であるログイベントを返します。 

fields f1 | filter statusCode 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 つ以上の条件を指定できます。

統計演算子として、sum()、avg()、count()、min()、max() などがサポートされています。

次の例では、f1 の一意の値ごとに f2 の平均値を計算します。 

stats avg (f1) by f2

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+)/

次の例では、正規表現を使用して、ログフィールド user2 から、エフェメラルフィールド method2、latency2、および @message を抽出し、method2 と user2 の一意的な組み合わせごとに平均レイテンシーを返します。 

parse @message /user=(?<user2>.*?), method:(?<method2>.*?), latency := (?<latency2>.*?)/ 
    | stats avg(latency2) by method2, user2

前の表のクエリコマンドに関する注意事項

前の表のクエリコマンドには、次のルール、ガイドライン、およびヒントが適用されます。

  • クエリ内のログフィールドの名前に @ 記号、ピリオド (.)、および英数字以外の文字が含まれている場合は、ログフィールドをバックティック (`) 文字で囲む必要があります。たとえば、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 のすぐ後にチェックする要素を含む配列を配置します。not では in を使用できます。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 コマンドで使用できます。また、他の関数の引数としても使用できます。算術オペレーションは、数値データ型を引数として受け入れ、数値結果を返します。

オペレーション 説明

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)

ブール型

フィールドが欠落しているか、空の文字列である場合、true を返します。

isblank(fieldName: string)

ブール型

フィールドが欠落しているか、空の文字列であるか、空白が含まれている場合、true を返します。

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(str: string, searchValue: string, replaceValue: string)

文字列

searchValue の str のすべてのインスタンスを replaceValue に置き換えます。たとえば、replace("foo","o","0") は "f00" を返します。

strcontains(str: string, searchValue: string)

数値

str に searchValue が含まれている場合は 1 を返し、それ以外の場合は 0 を返します。

日時関数

日時関数は、filter コマンドと fields コマンドで使用できます。また、他の関数の引数としても使用できます。これらの関数では、集計関数を使用してクエリの時間バケットを作成できます。

日時関数の一部として、数字と m (分) または h (時間) で構成される期間を使用できます。たとえば、10m は 10 分、1h は 1 時間です。

関数 結果タイプ 説明

bin(period: Period)

タイムスタンプ

@timestamp の値を特定の期間に切り上げ、次に切り詰めます。

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 エポックからのミリ秒を表す数値に変換します。

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 の値を返します。