Amazon CloudWatch Logs
ユーザーガイド

フィルターとパターンの構文

メトリクスフィルターで指定されたものに一致する語句や値を、ログイベントの中で検索できます。メトリクスフィルターがログイベントで語句、フレーズ、値を 1 つ見つけたら、CloudWatch メトリクスの値を増分できます。たとえば、ログイベントの中で ERROR という単語を検索して出現回数を数えるメトリクスフィルターを作成します。

メトリクスフィルターには、スペースで区切られたログイベントから数値を抽出する機能もあります。たとえば、ウェブリクエストのレイテンシーです。これらの例では、ログから抽出された実際の数値でメトリクス値を増分できます。

条件演算子やワイルドカードを使用して完全一致を見つけることもできます。メトリクスフィルターを作成する前に、CloudWatch コンソールで検索パターンをテストできます。以下のセクションでは、メトリクスフィルターの構文についてさらに詳しく説明します。

ログイベントの語句の一致

ログイベントで語句を検索するには、語句メトリクスフィルターパターンとして使用します。メトリクスフィルターパターンには複数の語句を指定できますが、一致させるためには語句はすべてログイベントに含まれるものである必要があります。メトリクスフィルターは大文字と小文字を区別します。

アルファベット文字およびアンダースコア以外の文字を含むメトリクスフィルターの語句は二重引用符 ("") で囲む必要があります。

語句を除外するには、語句の前で負符号 (-) を使用します。

例 1: すべてに一致するようにする

フィルターパターン "" はすべてのログイベントに一致します。

例 2: 単一語句

フィルターパターン「ERROR」は、次のように、この語句を含むログイベントメッセージに一致します:

  • [ERROR] A fatal exception has occurred

  • Exiting with ERRORCODE: -1

例 3: 語句の包含と語句の除外

前の例で、フィルターパターンを「ERROR」 - 「Exiting」に変更した場合、ログイベントメッセージ「Exiting with ERRORCODE: -1」が除外されます。

例 4: 複数語句

フィルターパターン「ERROR Exception」は、次のように両方の語句を含むログイベントメッセージに一致します。

  • [ERROR] Caught IllegalArgumentException

  • [ERROR] Unhandled Exception

フィルターパターン「Failed to process the request」は、次のようにすべての語句を含むログイベントメッセージに一致します。

  • [WARN] Failed to process the request

  • [ERROR] Unable to continue: Failed to process the request

OR パターンマッチング

OR パターンマッチングを使用して、テキストベースのフィルターで語句を一致させることができます。OR には疑問符を使用します (例: ?term)。

次の 3 つのログイベント例をご覧ください。ERROR は例 1、2 に一致します。?ERROR ?WARN は例 1、2、および 3 に一致します。それらのすべてには ERROR または WARN という単語が含まれているためです。ERROR WARN は例 1 のみと一致します。これは、これらの両方の単語が含まれている唯一の例であるためです。ERROR -WARN は例 2 と一致します。これは、WARN が含まれている文字列に一致しますが、WARN は含まれないためです。

  1. ERROR WARN message

  2. ERROR message

  3. WARN message

OR パターンマッチングを使用して、スペース区切りフィルターで語句を一致させることができます。スペース区切りフィルターでは、w1 はログイベントの最初の単語を意味し、w2 は 2 番目の単語を意味します。以下同様です。以下のサンプルパターンでは、ERROR が最初の単語であるため、[w1=ERROR, w2] はパターン 2 と一致し、[w1=ERROR || w1=WARN, w2] は パターン 2 および 3 と一致します。[w1!=ERROR&&w1!=WARN, w2] は ERROR および WARN の両方を含む行 (パターン 1) と一致します。

  1. ERROR WARN メッセージ

  2. ERROR メッセージ

  3. WARN メッセージ

OR パターンマッチングを使用して、JSON フィルターで語句を一致させることができます。以下のサンプルパターンでは、{$.foo = bar} はパターン 1 と一致し、{$.foo = baz } はパターン 2 と一致し、{$.foo = bar || $.foo = baz } はパターン 1 および 2 と一致します。

  1. {"foo": "bar"}

  2. {"foo": "baz"}

JSON ログイベントの語句の一致

JSON ログイベントから値を取得できます。JSON ログイベントから値を取得するには、文字列ベースのメトリクスフィルターを作成する必要があります。指数表記を含む文字列はサポートされていません。JSON ログイベントデータの項目は厳密にメトリクスフィルターと一致する必要があります。JSON ログイベントにメトリクスフィルターを作成して表示するのは次のような場合があります。

  • 特定のイベントが発生した場合。たとえば eventName が「UpdateTrail」の場合です。

  • IP が既知のサブネット以外の場合。たとえば、sourceIPAddress が既知のサブネットの範囲にない場合です。

  • 二つ以上の条件の組み合わせが true の場合。たとえば、eventName が「UpdateTrail」で、recipientAccountId が 123456789012 の場合です。

JSON ログイベントから値を取得するメトリクスフィルターの使用

メトリクスフィルターを使用して、JSON ログイベントから値を取得できます。メトリックスフィルターは受信ログをチェックし、ログデータの一致が見つかったときに数値を変更します。メトリクスフィルターを作成するときは、ログで一致するテキストが見つかるたびにカウントを増分するか、ログから数値を抽出し、それを使用してメトリクス値を増分することができます。

メトリクスフィルターを使用した JSON 条件の一致

JSON ログイベントのメトリクスフィルター構文は次の形式を使用します。

{ SELECTOR EQUALITY_OPERATOR STRING }

メトリクスフィルターは、JSON の記述であることを示すために中括弧 { } で囲む必要があります。メトリクスフィルターには次のパーツがあります。

SELECTOR

どの JSON プロパティを確認するかを指定します。プロパティセレクタは常に、JSON のルートを示すドル記号 ($) から始まります。プロパティセレクタは英数字の文字列であり「-」および「_」をサポートします。配列要素は [NUMBER] 構文で示され、プロパティに従う必要があります。例は次のとおりです。$.eventId、$.users[0]、$.users[0].id、$.requestParameters.instanceId。

EQUALITY_OPERATOR

= または != です。

STRING

引用符付きまたは引用符なしの文字列です。アスタリスク「*」ワイルドカード文字を検索語句の中間、前方、後方の文字の一致に使用できます。たとえば、[*Event] は [PutEvent] と [GetEvent] に一致します。[Event*] は [EventId] と [EventName] に一致します。[Ev*ent] は、実際の文字列 [Ev*ent] のみと一致します。英数字のみで構成された文字列を引用符で囲む必要はありません。unicode やそのほかの文字 (たとえば「@」「$」「\」など) を含む文字列は二重引用符で囲んで有効にする必要があります。

JSON メトリクスフィルターの例

JSON の例を次に示します。

{ "eventType": "UpdateTrail", "sourceIPAddress": "111.111.111.111", "arrayKey": [ "value", "another value" ], "objectList": [ { "name": "a", "id": 1 }, { "name": "b", "id": 2 } ], "SomeObject": null, "ThisFlag": true }

次のフィルターが一致します。

{ $.eventType = "UpdateTrail" }

UpdateTrail というイベントタイプのフィルター。

{ $.sourceIPAddress != 123.123.* }

プレフィックスが 123.123 のサブネットの範囲外にある IP アドレスのフィルター。

{ $.arrayKey[0] = "value" }

arrayKey の最初のエントリが「value」のフィルター。arrayKey が配列ではない場合、これは false になります。

{ $.objectList[1].id = 2 }

objectList の 2 番目のエントリが ID = 2 というプロパティを持つフィルター。objectList が配列ではない場合、これは false になります。objectList がオブジェクトではない場合、または ID プロパティがない場合、これは false になります。

{ $.SomeObject IS NULL }

null に設定されている SomeObject のフィルター。これは、指定したオブジェクトが null に設定されている場合のみ true になります。

{ $.SomeOtherObject NOT EXISTS }

存在しない SomeOtherObject のフィルター。これは、指定したオブジェクトがログデータに存在しない場合のみ true になります。

{ $.ThisFlag IS TRUE }

TRUE になっている ThisFlag のフィルター。これは、FALSE 値をチェックするブールフィルターでも機能します。

JSON 複合条件

OR (||) と AND (&&) を使用して複数の条件を組み合わせ、複合式にできます。括弧が使用できます。また、構文は演算子の標準の順序に従い、() > && > || となります。

{ "user": { "id": 1, "email": "John.Stiles@example.com" }, "users": [ { "id": 2, "email": "John.Doe@example.com" }, { "id": 3, "email": "Jane.Doe@example.com" } ], "actions": [ "GET", "PUT", "DELETE" ], "coordinates": [ [0, 1, 2], [4, 5, 6], [7, 8, 9] ] }
{ ($.user.id = 1) && ($.users[0].email = "John.Doe@example.com") }

上記の JSON に一致します。

{ ($.user.id = 2 && $.users[0].email = "nonmatch") || $.actions[2] = "GET" }

上記の JSON と一致しません。

{ $.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = nonmatch && $.actions[2] = nomatch }

上記の JSON に一致します。

{ ($.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = nonmatch) && $.actions[2] = nomatch }

上記の JSON と一致しません。

JSON に関する特別な考慮事項

SELECTOR は JSON の値ノード (文字列または数字) を指定する必要があります。配列またはオブジェクトを指定しても、ログ形式がフィルターと一致しないためフィルターは適用されません。たとえば、{$.users = 1} と {$.users != 1} は両方ともユーザーが配列であるログイベントとは一致しません。

{ "users": [1, 2, 3] }
数値比較

メトリクスフィルター構文は数値比較の正確な一致をサポートします。次の数値比較がサポートされています: <、>、>=、<=、=、!=

数字フィルターは次のような構文です。

{ SELECTOR NUMERIC_OPERATOR NUMBER }

メトリクスフィルターは、JSON の記述であることを示すために中括弧 { } で囲む必要があります。メトリクスフィルターには次のパーツがあります。

SELECTOR

どの JSON プロパティを確認するかを指定します。プロパティセレクタは常に、JSON のルートを示すドル記号 ($) から始まります。プロパティセレクタは英数字の文字列であり「-」および「_」をサポートします。配列要素は [NUMBER] 構文で示され、プロパティに従う必要があります。例は次のとおりです: $.latency、$.numbers[0]、$.errorCode、$.processes[4].averageRuntime。

NUMERIC_OPERATOR

次のいずれかを指定できます: =、!=、<、>、<=、または >=

NUMBER

オプションで + または - を伴う整数、オプションで + または - を伴う小数、科学的記数法で表した数字 (オプションで + または - を伴う整数または小数に続いて「e」、その後にオプションで + または - を伴う整数または小数) です。

例:

{ $.latency >= 500 } { $.numbers[0] < 10e3 } { $.numbers[0] < 10e-3 } { $.processes[4].averageRuntime <= 55.5 } { $.errorCode = 400 } { $.errorCode != 500 } { $.latency > +1000 }

スペース区切りログイベントから値を取得するメトリクスフィルターの使用

メトリクスフィルターを使用してスペース区切りログイベントから値を取得できます。角括弧 [] または 2 個の二重引用符 ("") で囲まれた文字は単一のフィールドとして扱われます。例:

127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] "GET /apache_pb.gif HTTP/1.0" 200 1534 127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] "GET /apache_pb.gif HTTP/1.0" 500 5324 127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] "GET /apache_pb.gif HTTP/1.0" 200 4355

スペース区切りイベントを解析するメトリクスフィルターパターンを指定するには、メトリクスフィルターパターンが、フィールドの名前をカンマで区切り、すべてのパターンを角括弧で囲んで指定する必要があります。たとえば、[ip, user, username, timestamp, request, status_code, bytes] のようになります。

フィールド数が不明な場合は、省略符号 (…) を使用した省略通知を使用できます。例:

[..., status_code, bytes] [ip, user, ..., status_code, bytes] [ip, user, ...]

また、フィールドに条件を追加して、すべての条件に一致するログイベントのみがフィルターに一致するようにできます。例:

[ip, user, username, timestamp, request, status_code, bytes > 1000] [ip, user, username, timestamp, request, status_code = 200, bytes] [ip, user, username, timestamp, request, status_code = 4*, bytes] [ip, user, username, timestamp, request = *html*, status_code = 4*, bytes]

次の例のように、AND 演算子として && を使用できます。

[ip, user, username, timestamp, request, status_code = 4* && bytes > 1000] [ip, user, username, timestamp, request, status_code = 4* && status_code != 403, bytes]

CloudWatch Logs は文字列条件フィールドおよび数値条件フィールドの両方をサポートします。文字列フィールドでは、= または != 演算子をアスタリスク (*) とともに使用できます。

数値フィールドでは、>、<、>=、<=、=、および != 演算子を使用できます。

スペース区切りフィルターを使用している場合、抽出されたフィールドは、フィルターで表示されるスペース区切りフィールド名をこれらの各フィールドの値にマッピングします。スペース区切りフィルターを使用していない場合、これは空となります。

フィルターの例:

[..., request=*.html*, status_code=4*,]

フィルターのログイベントの例:

127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /index.html HTTP/1.0\" 404 1534

ログイベントとフィルターパターンに対して抽出されたフィールド:

{ "$status_code": "404", "$request": "GET /products/index.html HTTP/1.0", "$7": "1534", "$4": "10/Oct/2000:13:25:15 -0700", "$3": "frank", "$2": "-", "$1": "127.0.0.1" }

一致が見つかった場合のメトリクス値の変更方法の設定

メトリクスフィルターが、ログイベントで一致するいずれかの用語、語句、または値を見つけた場合、メトリクス値に指定された量だけ CloudWatch メトリクスのカウントを増分します。メトリクス値は 1 分ごとに集計され、報告されます。

1 分の間にログが取り込まれても一致が見つからない場合は、デフォルト値に設定された値 (存在する場合) が報告されます。ただし、1 分の間に取り込まれたログイベントがない場合は、値は報告されません。

デフォルト値を指定すると、その値が 0 の場合でも、データはより頻繁に報告されるので、一致が見つからない場合にむらがあるメトリクスを避けるのに役立ちます。

たとえば、2 つのレコードを公開し、メトリクス値は 1 で、デフォルト値は 0 のロググループがあるとします。最初の 1 分で両方のログレコードで一致が見つかった場合、その分のメトリクス値は 2 になります。次の 1 分で発行されるログレコードに一致する値がない場合、デフォルト値の 0 が両方のログレコードに使用され、その 1 分のメトリクス値は 0 になります。

デフォルト値を指定しない場合、一致するパターンが見つからない期間についてはデータは報告されません。

ログエントリで見つかった数値を発行する

ログで見つかった一致する項目の数をカウントするだけでなく、メトリクスフィルターを使用してログで見つかった数値に基づく値を発行することができます。次の手順は、JSON リクエスト metricFilter: { $.latency = * } metricValue: $.latency で見つかったレイテンシーのメトリクスを公開する方法を示しています。

JSON リクエストで見つかったレイテンシーのメトリクスを発行するには

  1. https://console.aws.amazon.com/cloudwatch/にある CloudWatch コンソールを開きます。

  2. ナビゲーションペインで [ログ] を選択します。

  3. コンテンツペインでロググループを選択し、[メトリクスフィルターの作成] を選択します。

  4. [ログメトリクスフィルターの定義] 画面の [フィルターパターン] に、「{ $.latency = * }」と入力し、[メトリクスの割り当て] をクリックします。

  5. [メトリクスフィルターの作成とメトリクスの割り当て] 画面で、[メトリクスの詳細設定の表示] を選択します。

  6. [メトリクス名] に、「myMetric」と入力します。

  7. [メトリクス値] に「$.latency」と入力します。

  8. [デフォルト値] に「0」と入力し、[フィルターの作成] を選択します。デフォルト値を指定すると、ログイベントが発生しない期間でもデータが報告され、データが存在しないことがある、むらのあるメトリクスを回避できます。

次のログイベントは、フィルターの作成後、値 50 をメトリクス myMetric に発行します。

{ "latency": 50, "requestType": "GET" }