メニュー
Amazon CloudWatch ログ
ユーザーガイド

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

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

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

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

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

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

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

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

例 1: 単一語句

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

  • [ERROR] A fatal exception has occurred

  • Exiting with ERRORCODE: -1

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

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

例 3: 複数語句

フィルタパターン「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

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

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

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

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

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

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

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

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

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

Copy
{ 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 の例を次に示します。

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

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

Copy
{ $.eventType = "UpdateTrail" }

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

Copy
{ $.sourceIPAddress != 123.123.* }

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

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

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

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

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

Copy
{ $.SomeObject IS NULL }

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

Copy
{ $.SomeOtherObject NOT EXISTS }

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

Copy
{ $.ThisFlag IS TRUE }

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

JSON 複合条件

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

Copy
{ "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] ] }
Copy
{ ($.user.id = 1) && ($.users[0].email = "John.Doe@example.com") }

上記の JSON に一致します。

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

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

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

上記の JSON に一致します。

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

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

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

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

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

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

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

Copy
{ SELECTOR NUMERIC_OPERATOR NUMBER }

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

SELECTOR

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

NUMERIC_OPERATOR

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

NUMBER

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

例:

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

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

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

Copy
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] のようになります。

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

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

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

Copy
[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]

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

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

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

フィルタの例:

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

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

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

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

Copy
{ "$status_code": "400", "$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. ナビゲーションペインで [Logs] を選択します。

  3. コンテンツペインでロググループを選択し、[Create Metric Filter] を選択します。

  4. [Define Logs Metric Filter] 画面の [Filter Pattern] に、「{ $.latency = * }」と入力し、[Assign Metric] をクリックします。

  5. [Create Metric Filter and Assign a Metric] 画面で、[Show advanced metric settings] を選択します。

  6. [Metric Name] に、「myMetric」と入力します。

  7. [Metric Value] に「$.latency」と入力します。

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

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

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