CloudWatch Logs Insights クエリ構文

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

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

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

CloudWatch Logs が自動的に検出するフィールドの詳細については、「サポートされるログと検出されるフィールド」を参照してください。

CloudWatch Logs Insights のクエリコマンド

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

コマンド	説明	例
display	クエリ結果に表示するフィールドを指定します。このコマンドをクエリで複数回指定すると、最後に指定したフィールドのみが使用されます。	FIELDS @message | PARSE @message "[*] *" as loggingType, loggingMessage | FILTER loggingType = "ERROR" | DISPLAY loggingMessage この例では、フィールド @message を使用し、一時フィールド loggingType および loggingMessage を作成して、クエリで使用します。これは、loggingType の値として ERROR を持つイベントのみにイベントをフィルタリングしますが、結果には loggingMessage フィールドのみを表示します。
fields	指定したフィールドをログイベントから取得しますfields コマンド内で関数とオペレーションを使用できます。	fields `foo-bar`, action, abs(f3-f4) この例では、foo-bar フィールドと action フィールドを取得し、さらにロググループ内のすべてのログイベントについて f3 と f4 の差異の絶対値を取得します。 クエリ内のログフィールドの名前に @ 記号、ピリオド (.)、および英数字以外の文字が含まれている場合は、ログフィールドをバックティック (`) 文字で囲む必要があります。たとえば、foo-bar フィールド名は、英数字以外の文字が含まれているためバックティック文字で囲む必要があります。
filter	クエリの結果を 1 つ以上の条件に基づいてフィルタリングします。比較演算子 (=、!=、<、<=、>、>=)、ブール演算子 (and、or、not) および正規表現を使用できます。 in を使用して、集合要素関係をテストできます。in のすぐ後にチェックする要素を含む配列を配置します。in では not を使用できます。	fields f1, f2, f3 | filter (duration>2000) は、duration フィールドの値が 2000 を超えるすべてのログイベントについて、f1 フィールド、f2 フィールド、および f3 フィールドを取得します。 filter (duration>2000) も有効なクエリですが、結果に個別のフィールドが表示されません。代わりに、duration が 2000 を超えるすべてのログイベントについて、@message フィールド内のすべてのログデータおよび @timestamp が結果に表示されます。 fields f1, f2 | filter (f1=10 or f3>25) は、f1 が 10 であるか、f3 が 25 を超えるすべてのログイベントについて、f1 フィールドと f2 フィールドを取得します。 fields f1 | filter statusCode like /2\d\d/ は、statusCode フィールドの値が 200～299 であるログイベントを返します。 fields @timestamp, @message | filter @message in [300,400,500] は、メッセージに「300」、「400」、または「500」を含むログイベントを返します。 fields @timestamp, @message | filter @message not in ["foo","bar",1] は、メッセージに「foo」、「bar」、または「1」を含まないログイベントを返します。
stats	ログフィールドの値に基づいて集約統計を計算します。統計演算子として、avg()、sum()、count()、,min()、max() などがサポートされています。 stats と by を併用すると、統計の計算時にデータをグループ化するための 1 つ以上の条件を指定できます。	stats avg (f1) by f2 は、f2 の一意な値ごとに f1 の平均値を計算します。
sort	取得したログイベントをソートします。昇順 (asc) と降順 (desc) の両方がサポートされています。	fields f1, f2, f3 | sort f1 desc は、f1、f2、f3 の各フィールドを取得し、返されたイベントを f1 の値に基づいて降順にソートします。
limit	クエリから返されるログイベントの数を指定します。 これを使用して、結果を小さい数値に制限し、関連する結果の小さいセットを表示することができます。さらに、limit で 1000 ～ 10,000 の数値を使用し、コンソールに表示されるクエリ結果の行数を、デフォルトの 1000 行より大きい数に増やすこともできます。 制限を指定しない場合、クエリにはデフォルトで最大 1000 行表示されます。	fields f1, f2 | sort @timestamp desc | limit 25 は、f1 フィールドと f2 フィールドを取得し、@timestamp の値に基づいてイベントを降順にソートして、ソート順で最初の 25 件のイベントを返します。この場合、ソート順は最新のタイムスタンプから開始されるため、最新の 25 件のイベントが返されます。 CloudWatch Logs Insights に用意されている一部のサンプルクエリでは、limit の代わりに head コマンドや tail コマンドを使用しています。これらのコマンドは廃止済みであり、limit に置き換えられています。ユーザーが書くすべてのクエリで、head または tail の代わりに limit を使用します。
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+)/ 次の例では、正規表現を使用して、ログフィールド @message から、エフェメラルフィールド @user2、@method2、@latency2 を抽出し、@method2 と @user2 の一意な組み合わせごとに平均レイテンシーを返します。 parse @message /user=(?<user2>.*?), method:(?<method2>.*?), latency := (?<latency2>.*?)/ | stats avg(@latency2) by @method2, @user2

フィルターコマンドの正規表現

filter クエリコマンドで 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"

次の例では、正規表現を使用します。これは、f1 に単語 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)	絶対値。
ceil(a)	上限 (a の値より大きい最小整数) に切り上げられます。
floor(a)	下限 (a の値より小さい最大整数) に切り下げられます。
greatest(a,b,... z)	最大値を返します。
least(a, b, ... z)	最小値を返します。
log(a)	自然対数。
sqrt(a)	平方根。

一般関数

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

関数	引数	結果タイプ	説明
ispresent(fieldname)	ログフィールド	Boolean	フィールドが存在する場合は true を返します。
coalesce(fieldname1, fieldname2, ... fieldnamex)	ログフィールド	ログフィールド	リストから最初の null でない値を返します。

文字列関数

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

関数	引数	結果タイプ	説明
isempty(fieldname)	文字列	Boolean	フィールドが欠落しているか、空の文字列である場合、true を返します。
isblank(fieldname)	文字列	Boolean	フィールドが欠落しているか、空の文字列であるか、空白が含まれている場合、true を返します。
concat(string1, string2, ... stringz)	文字列	文字列	複数の文字列を連結します。
ltrim(string) or ltrim(string1, string2)	文字列	文字列	文字列の左側から空白を削除します。関数に 2 番目の文字列引数がある場合、string1 の左側から string2 の文字を削除します。たとえば、ltrim("xyZfooxyZ","xyZ") は "fooxyZ" を返します。
rtrim(string) or rtrim(string1, string2)	文字列	文字列	文字列の右側から空白を削除します。関数に 2 番目の文字列引数がある場合、string1 の右側から string2 の文字を削除します。たとえば、rtrim("xyZfooxyZ","xyZ") は "xyZfoo" を返します。
trim(string) or trim(string1, string2)	文字列	文字列	文字列の両端から空白を削除します。関数に 2 番目の文字列引数がある場合、string1 の両端から string2 の文字を削除します。たとえば、trim("xyZfooxyZ","xyZ") は "foo" を返します。
strlen(string)	文字列	数値	文字列の長さを Unicode コードポイントで返します。
toupper(string)	文字列	文字列	文字列を大文字に変換します。
tolower(string)	文字列	文字列	文字列を小文字に変換します。
substr(string1, x), or substr(string1, x, y)	文字列、数値または文字列、数値、数値	文字列	数値引数で指定されたインデックスから文字列の末尾までの部分文字列を返します。関数に 2 番目の数値引数がある場合、この引数には取得される部分文字列の長さが含まれます。たとえば、substr("xyZfooxyZ",3, 3) は "foo" を返します。
replace(string1, string2, string3)	文字列、文字列、文字列	文字列	string1 の string2 のすべてのインスタンスを string3 に置き換えます。例えば、replace("foo","o","0") は "f00" を返します。
strcontains(string1, string2)	文字列	数値	string1 に string2 が含まれている場合は 1 を返し、それ以外の場合は 0 を返します。

日時関数

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

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

関数	引数	結果タイプ	説明
bin(period)	間隔	タイムスタンプ	@timestamp の値を特定の期間に切り上げ、次に切り詰めます。
datefloor(a, period)	タイムスタンプ、期間	タイムスタンプ	タイムスタンプを特定の期間に切り詰めます。たとえば、datefloor(@timestamp, 1h) は @timestamp のすべての値を 1 時間の下限に切り詰めます。
dateceil(a, period)	タイムスタンプ、期間	タイムスタンプ	タイムスタンプを特定の期間に切り上げ、次に切り詰めます。たとえば、dateceil(@timestamp, 1h) は @timestamp のすべての値を 1 時間の上限に切り詰めます。
fromMillis(fieldname)	数値	タイムスタンプ	入力フィールドを Unix エポックからのミリ秒数として解釈し、タイムスタンプに変換します。
toMillis(fieldname)	タイムスタンプ	数値	指定されたフィールドで見つかったタイムスタンプを、Unix エポックからのミリ秒を表す数値に変換します。

IP アドレス関数

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

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

Stats コマンドの集約関数

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

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

Stats コマンドの非集約関数

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

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