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

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

メトリクスフィルタで指定されたものに一致する語句や値が、ログイベントの中で検索されます。メトリクスフィルタは、ログイベントで語句、フレーズ、値を 1 つ見つけるたびに CloudWatch メトリクスでカウントします。たとえば、ログイベントの中で ERROR という単語を検索して出現回数を数えるメトリクスフィルタを作成します。メトリクスフィルタには、スペースで区切られたログイベントから値を抽出する機能もあります。たとえば、ウェブリクエストのレイテンシーです。条件演算子やワイルドカードを使用して完全一致を見つけることもできます。メトリクスフィルタを作成する前に、CloudWatch コンソールで検索パターンをテストできます。以下のセクションでは、メトリクスフィルタの構文についてさらに詳しく説明します。

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

ログイベントで ERROR などの語句を検索するには、ERROR をメトリクスフィルタパターンとして使用します。メトリクスフィルタパターンには複数の語句を指定できますが、一致させるためには語句はすべてログイベントに含まれるものである必要があります。たとえば、フィルタパターン ERROR は以下のログイベントメッセージに一致します。

  • [ERROR] A fatal exception has occurred

  • Exiting with ERRORCODE: -1

フィルタパターン 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 の場合です。

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

メトリクスフィルタを使用してスペース区切りログイベントから値を取得できます。角括弧 [] または 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" }

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 やそのほかの文字(たとえば「@」「$」「\」など)を含む文字列は二重引用符で囲んで有効にする必要があります。

メトリクスフィルタの例

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 }

上記の JSON の例は、これらのフィルタのいずれかが一致します。

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 値をチェックするブールフィルタでも機能します。

複合条件

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 と一致しません。

特別な考慮事項

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 }

メトリクスフィルタ値の抽出

JSON イベントで見つかった数値をメトリクス値として CloudWatch に発行できます。次の手順は、JSON リクエスト metricFilter: { $.latency = * } metricValue: $.latency で見つかったレイテンシーのメトリクスを公開する方法を示しています。

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

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

  2. 必要に応じてリージョンを変更します。ナビゲーションバーから、必要に応じてリージョンを選択します。詳細については、『アマゾン ウェブ サービス全般のリファレンス』の「リージョンとエンドポイント」を参照してください。

  3. [Navigation] ペインの [Logs] をクリックします。

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

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

  6. [Create Metric Filter and Assign a Metric] 画面で、[Show advanced metric settings] をクリックします。

  7. [Metric Name] フィールドに「myMetric」と入力します。

  8. [Metric Value] フィールドに「$.latency」と入力し、[Create Filter] をクリックします。

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

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