翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # CloudWatch Logs Insights 言語のクエリ構文 このセクションでは、Logs Insights QL の詳細について説明します。クエリ構文は、一般的な関数、算術演算と比較演算、正規表現など、さまざまな関数とオペレーションをサポートしています。 **重要** 大規模なクエリを実行して過剰な料金が発生するのを防ぐため、次のベストプラクティス留意してください。 各クエリに必要なロググループのみを選択します。 クエリには、常にできるだけ狭い時間範囲を指定します。 コンソールを使用してクエリを実行する場合は、CloudWatch Logs Insights コンソールページを閉じる前にすべてのクエリをキャンセルします。それ以外の場合、クエリは完了するまで実行され続けます。 CloudWatch Logs Insights ウィジェットをダッシュボードに追加するときは、更新ごとに新しいクエリが開始されるため、ダッシュボードが高頻度で更新されないようにしてください。 複数のコマンドを含むクエリを作成するときは、コマンドをパイプ文字 (**\$1**) で区切ります。 コメントを含むクエリを作成するときは、コメントをハッシュ文字 (**\$1**) で区切ります。 **注記** CloudWatch Logs Insights は、さまざまなログタイプのフィールドを自動で検出し、**@** 文字で始まるフィールドを生成します。これらのフィールドの詳細については、「*Amazon CloudWatch ユーザーガイド*」の「[サポートされるログと検出されるフィールド](https://docs.aws.amazon.com/en_us/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData-discoverable-fields.html)」を参照してください。 次の表で、各コマンドについて簡単に説明します。この表の後に、各コマンドについての詳細な説明と例を示します。 **注記** すべての Logs Insights QL クエリコマンドは、標準ログクラスのロググループでサポートされています。低頻度アクセスログクラスのロググループは `pattern`、`diff`、`unmask` を除くすべての Logs Insights QL クエリコマンドをサポートします。 | | | | --- |--- | | **` anomaly`** | 機械学習を使用して、ログデータの異常なパターンを識別します。 | | **` display`** | クエリ結果に特定のフィールドを表示します。 | | **` fields`** | クエリ結果に特定のフィールドを表示し、クエリで使用するフィールド値を変更したり新しいフィールドを作成したりするときに使用できる関数と演算をサポートします。 | | **` filter`** | クエリをフィルタリングし、1 つ以上の条件に一致するログイベントのみを返します。 | | **` filterIndex`** | フィールドインデックスで説明されているフィールドでインデックス付けされ、そのフィールドインデックスの値も含むロググループのみをスキャンするようクエリに強制します。これにより、このフィールドインデックスのクエリで指定された値を含むこれらのロググループのログイベントのみをスキャンしようとすることで、スキャンされるボリュームが減少します。 このコマンドは、低頻度アクセスログクラスのロググループではサポートされていません。 | | **` pattern`** | 自動的にログデータをパターンにクラスター化します。パターンは、ログフィールド間で繰り返される共有テキスト構造です。CloudWatch Logs Insights には、ログイベントで検出されたパターンを分析する方法が用意されています。詳細については、「[パターン分析](CWL_AnalyzeLogData_Patterns.md)」を参照してください。 | | **` diff`** | リクエストされた期間に検出されたログイベントと、以前の期間と同じ長さのログイベントを比較して、傾向を検索し、特定のログイベントが新しいかどうかを確認することができます。 | | **` parse`** | ログフィールドからデータを抽出し、クエリで処理できる抽出フィールドを作成します。**`parse`** は、ワイルドカードを使用する glob モードと正規表現の両方をサポートします。 | | **` sort`** | 返されたログイベントを昇順 (`asc`) または降順 (`desc`) で表示します。 | | **` SOURCE`** | `SOURCE` をクエリに含めると、クエリに含めるロググループ名のプレフィックス、アカウント識別子、ロググループクラスに基づいて大量のロググループを指定するのに役立ちます。このコマンドは、CloudWatch コンソールではなく、 AWS CLI またはプログラムでクエリを作成する場合にのみサポートされます。 | | **` stats`** | ログフィールドの値を使って集計した統計を算出します。 | | **` limit`** | クエリで返すログイベントの最大数を指定します。**`sort`** で「上位 20 件」または「最新の 20 件」の結果を返すソートと一緒に使用すると便利です。 | | **` dedup`** | 指定したフィールドの特定の値に基づいて、重複した結果を削除します。 | | **` unmask`** | データ保護ポリシーにより一部のコンテンツがマスクされているログイベントの、すべてのコンテンツを表示します。ロググループのデータ保護の詳細については、「[機密性の高いログデータをマスキングで保護する](mask-sensitive-log-data.md)」を参照してください。 | | **`[unnest](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-Unnest.html)`** | 入力として取得したリストをフラット化し、リスト内の各要素に対して 1 つのレコードを持つ複数のレコードを生成します。 | | **` lookup`** | フィールド値を一致させることで、ルックアップテーブルのデータを含むログイベントを強化します。ルックアップテーブルを使用して、ユーザーの詳細、アプリケーション名、製品情報などの参照データをクエリ結果に追加します。 | | **[その他の演算と関数](CWL_QuerySyntax-operations-functions.md)** | CloudWatch Logs Insightsは、比較、計算、日時、数値、文字列、IP アドレス、一般的な関数と演算も多数サポートしています。 | 以下のセクションでは、CloudWatch Logs Insights のクエリコマンドについてさらに詳しく説明します。 **Topics** + [ログクラスでサポートされている Logs Insights QL コマンド](CWL_AnalyzeLogData_Classes.md) + [異常](CWL_QuerySyntax-Anomaly.md) + [**display**](CWL_QuerySyntax-Display.md) + [fields](CWL_QuerySyntax-Fields.md) + [フィルター](CWL_QuerySyntax-Filter.md) + [filterIndex](CWL_QuerySyntax-FilterIndex.md) + [SOURCE](CWL_QuerySyntax-Source.md) + [pattern](CWL_QuerySyntax-Pattern.md) + [diff](CWL_QuerySyntax-Diff.md) + [parse](CWL_QuerySyntax-Parse.md) + [sort](CWL_QuerySyntax-Sort.md) + [stats](CWL_QuerySyntax-Stats.md) + [制限](CWL_QuerySyntax-Limit.md) + [重複排除](CWL_QuerySyntax-Dedup.md) + [マスクを外す](CWL_QuerySyntax-Unmask.md) + [ネスト解除](CWL_QuerySyntax-Unnest.md) + [lookup](CWL_QuerySyntax-Lookup.md) + [ブール、比較、数値、日時、その他の関数](CWL_QuerySyntax-operations-functions.md) + [特殊文字を含むフィールド](CWL_QuerySyntax-Guidelines.md) + [クエリでのエイリアスとコメントの使用](CWL_QuerySyntax-alias.md) # ログクラスでサポートされている Logs Insights QL コマンド すべての Logs Insights QL クエリコマンドは、標準ログクラスのロググループでサポートされています。低頻度アクセスログクラスのロググループは `pattern`、`diff`、`filterIndex`、`unmask` を除くすべてのクエリコマンドをサポートします。 # 異常 `anomaly` を使用すると、機械学習を用いてログデータ内の異常なパターンと潜在的な問題を自動的に特定します。 `anomaly` コマンドは既存の `pattern` 機能を拡張し、高度な分析を活用してログデータの潜在的な異常を特定します。`anomaly` を使用すると、ログの異常なパターンや動作を自動的に表示することで運用上の問題の特定と解決にかかる時間を短縮できます。 `anomaly` コマンドは ` pattern` コマンドと連携し、まずログパターンを識別してからそれらのパターン内の異常を検出します。さらに、`anomaly` を ` filter` または ` sort` コマンドと組み合わせ、データの特定のサブセットの異常検出に焦点を当てることもできます。 **異常コマンド入力** `anomaly` コマンドは通常、` pattern` コマンドの後に使用され、ログデータで識別されるパターンを分析します。このコマンドは追加のパラメータを必要とせず、クエリ内の前述のコマンドからの出力を分析します。 **特定される異常のタイプ** `anomaly` コマンドは、次の 5 つの異なるタイプの異常を識別します。 + *パターン頻度の異常*: アプリケーションが通常よりも多くのエラーメッセージの生成を開始する場合など、特定のログパターンの異常な頻度。 + *新しいパターンの異常*: ログに表示される新しいタイプのエラーやメッセージを示す、これまでに見られなかったログパターン。 + *トークンバリエーションの異常*: ログメッセージのコンテンツの不測の変更。予想されるログ形式の異常なバリエーションを示している可能性があります。 + *数値トークンの異常*: パフォーマンスの潜在的な問題やメトリクスの不測の変動を検出するのに役立つ、ログ内の数値の異常な変化。 + *HTTP エラーコードの異常*: HTTP エラーレスポンスに関連するパターン。特にウェブアプリケーションと API をモニタリングする場合に便利です。 **異常コマンド出力** `anomaly` コマンドは、入力データからのすべてのフィールドを保持し、ログデータの異常なパターンを識別するのに役立つ異常検出結果を追加します。 **例** 次のコマンドは、ログデータのパターンを識別し、それらのパターン内の異常を検出します。 ``` fields @timestamp, @message | pattern @message | anomaly ``` `anomaly` コマンドはフィルタリングと併用し、特定のログタイプに焦点を当てることができます。 ``` fields @timestamp, @message | filter @type = "REPORT" | pattern @message | anomaly ``` `anomaly` コマンドをソートと組み合わせて結果を整理できます。 ``` fields @timestamp, @message | filter @type = "ERROR" | pattern @message | anomaly | sort @timestamp desc ``` # **display** `display` を使用して、クエリ結果の特定のフィールドを表示します。 `display` コマンドは、指定したフィールドのみを表示します。クエリに複数の `display` コマンドが含まれている場合、クエリ結果には、最後の `display` コマンドで指定したフィールドのみが表示されます。 **例: 1 つのフィールドを表示する** コードスニペットは、解析コマンドを使用して `@message` からデータを抽出し、抽出フィールド `loggingType` および `loggingMessage` を作成するクエリの例を示します。クエリは、`loggingType` の値が **ERROR** であるすべてのログイベントを返します。`display` は、クエリ結果に `loggingMessage` の値のみを表示します。 ``` fields @message | parse @message "[*] *" as loggingType, loggingMessage | filter loggingType = "ERROR" | display loggingMessage ``` **ヒント** クエリで 1 回だけ `display` を使用します。クエリで `display` を 2 回以上使用すると、クエリの結果には、使用されている `display` コマンドの直近の実行で指定されたフィールドが表示されます。 # fields `fields` を使用して、クエリ結果の特定のフィールドを表示します。 クエリに複数の `fields` コマンドが含まれ、`display` コマンドが含まれていない場合は、結果に、`fields` コマンドで指定されたすべてのフィールドが表示されます。 **例: 特定のフィールドを表示する** 以下は、20 個のログイベントを返し、それらを降順で表示するクエリの例です。`@timestamp` と `@message` の値がクエリ結果に表示されます。 ``` fields @timestamp, @message | sort @timestamp desc | limit 20 ``` フィールド値を変更したり、クエリで使用できる新しいフィールドを作成したりするため、`fields` がサポートしている異なる関数や演算を使用するときは、`display` ではなく `fields` を使用します。 `fields` コマンドを *as* キーワードと共に使用すると、ログイベント内の関数とフィールドを使用して抽出フィールドを作成できます。例えば、`fields ispresent as isRes` はクエリの残りの部分で使用できる `isRes` という名前の抽出フィールドを作成します。 # フィルター `filter` を使用して、1 つ以上の条件に一致するログイベントを取得します。 **例: 1 つの条件を使用してログイベントをフィルタリングする** コードスニペットは、`range` の値が ***3000*** より大きいすべてのログイベントを返すクエリの例を示します。このクエリは、結果を 20 個のログイベントに制限し、ログイベントを `@timestamp` 別に降順で並べ替えます。 ``` fields @timestamp, @message | filter (range>3000) | sort @timestamp desc | limit 20 ``` **例: 複数の条件を使用してログイベントをフィルタリングする** キーワード `and` および `or` を使用して、複数の条件を組み合わせることができます。 コードスニペットは、`range` の値が ***3000*** より大きく、`accountId` の値が ***123456789012*** に等しいログイベントを返すクエリの例を示します。このクエリは、結果を 20 個のログイベントに制限し、ログイベントを `@timestamp` 別に降順で並べ替えます。 ``` fields @timestamp, @message | filter (range>3000 and accountId=123456789012) | sort @timestamp desc | limit 20 ``` ## インデックス付きフィールドとフィルターコマンド ロググループのフィールドインデックスを作成している場合は、それらのフィールドインデックスを活用して `filter` クエリの効率性を高め、スキャンされるボリュームを減らすことができます。例えば、`requestId` のフィールドインデックスを作成したとします。次に、 `filter requestId = value`または を含むそのロググループの CloudWatch Logs Insights クエリ`filter requestId IN [value, value, ...]`は、インデックス付きフィールドを含まないことがわかっているログイベントの処理をスキップしようとします。そのインデックス付きフィールドが含まれていることがわかっているログイベントのみをスキャンしようとすると、スキャン量を減らすことができ、クエリが高速になります。 フィールドインデックスおよびその作成方法の詳細については「[フィールドインデックスを作成してクエリパフォーマンスを改善し、スキャン量を削減する](CloudWatchLogs-Field-Indexing.md)」を参照してください。 **重要** フィールドインデックスの改善による恩恵があるのは `filter fieldName =...` と `filter fieldName IN...` を持つクエリのみです。`filter fieldName like` を持つクエリの場合、インデックスは使用されず、選択したロググループのすべてのログイベントを常にスキャンします。 **例: インデックスを使用して、特定のリクエスト ID に関連するログイベントを検索する** この例では、`requestId` でフィールドインデックスが作成されていることを前提としています。このフィールドインデックスを使用するロググループの場合、クエリはフィールドインデックスを活用して最小量のログイベントをスキャンし、値が `123456` の `requestId` を持つイベントを見つけようとします。 ``` fields @timestamp, @message | filter requestId = "1234656" | limit 20 ``` ## フィルターコマンドの一致と正規表現 フィルターコマンドは、正規表現の使用をサポートします。以下の比較演算子 (`=`、`!=`、`<`、`<=`、`>`、`>=`) とブール演算子 (`and`、`or`、および `not`) を使用できます。 キーワード `in` を使用して集合要素関係をテストし、配列内の要素をチェックできます。配列の要素をチェックするには、`in` の後に対象の配列を配置します。ブール演算子 `not` および `in` を使用できます。`in` を使用するクエリを作成して、フィールドに文字列の一致があるログイベントを返すことができます。フィールドは完全な文字列でなければなりません。例えば、次のコードスニペットは、フィールド `logGroup` が完全な文字列 `example_group` であるログイベントを返すために `in` を使用するクエリを示しています。 ``` fields @timestamp, @message | filter logGroup in ["example_group"] ``` キーワードフレーズ `like` および `not like` を使用して、部分文字列を一致させることができます。正規表現の演算子 `=~` を使用して部分文字列を一致させることができます。`like` および `not like` で部分文字列を一致させるには、単一引用符または二重引用符で一致させたい部分文字列を囲みます。正規表現パターンは、`like` および `not like` と共に使用できます。部分文字列を正規表現の演算子と一致させるには、一致させたい部分文字列をスラッシュで囲みます。次の例には、`filter` コマンドを使用して部分文字列を照合する方法を示すコードスニペットが含まれます。 **例: 部分文字列の一致** 以下の例では、`f1` に単語 ***Exception*** が含まれているログイベントを返します。これら 3 つの例すべてで、大文字と小文字が区別されます。 最初の例では、部分文字列を `like` と一致させます。 ``` fields f1, f2, f3 | filter f1 like "Exception" ``` 2 番目の例では、部分文字列を `like` および正規表現パターンと一致させます。 ``` fields f1, f2, f3 | filter f1 like /Exception/ ``` 3 番目の例では、部分文字列を正規表現と一致させます。 ``` fields f1, f2, f3 | filter f1 =~ /Exception/ ``` **例: 部分文字列をワイルドカードと一致させる** ピリオド記号 (`.`) を正規表現のワイルドカードとして使用して、部分文字列に一致させることができます。次の例では、クエリは `f1` の値が文字列 `ServiceLog` で始まる一致を返します。 ``` fields f1, f2, f3 | filter f1 like /ServiceLog./ ``` ピリオド記号 (`.*`) の後にアスタリスク記号を置いて、できるだけ多くの一致を返す貪欲な量指定子を作成することができます。例えば、次のクエリは `f1` の値が文字列 `ServiceLog` で始まるだけでなく、文字列 `ServiceLog` も含む一致を返します。 ``` fields f1, f2, f3 | filter f1 like /ServiceLog.*/ ``` 考えられる一致は、次のようにフォーマットされている可能性があります: + `ServiceLogSampleApiLogGroup` + `SampleApiLogGroupServiceLog` **例: 一致から部分文字列を除外する** 次の例は、`f1` に ***Exception*** という単語が含まれないログイベントを返すクエリを示しています。この例では大文字と小文字が区別されます。 ``` fields f1, f2, f3 | filter f1 not like "Exception" ``` **例: 大文字と小文字を区別しないパターンで部分文字列を一致させる** 大文字と小文字を区別しない部分文字列を、`like` および正規表現と一致させることができます。次のパラメータ (**?i**) を、一致させる部分文字列の前に配置します。次の例は、`f1` に単語 ***Exception*** または ***exception*** が含まれるログベントを返すクエリを示しています。 ``` fields f1, f2, f3 | filter f1 like /(?i)Exception/ ``` # filterIndex `filterIndex` を使用してインデックス付きデータのみを返すには、クエリで指定したフィールドでインデックス付けされたロググループのみをスキャンするようクエリに強制します。このフィールドでインデックス付けされるこれらのロググループの場合、インデックス付けされたフィールドのクエリで指定されたフィールドを含む任意のログイベントを持たないロググループをスキップすることで、クエリがさらに最適化されます。さらに、このフィールドインデックスのクエリで指定された値に一致するこれらのロググループのログイベントのみをスキャンしようとすることで、スキャンされるボリュームが減少します。フィールドインデックスおよびその作成方法の詳細については「[フィールドインデックスを作成してクエリパフォーマンスを改善し、スキャン量を削減する](CloudWatchLogs-Field-Indexing.md)」を参照してください。 インデックス付きフィールドで `filterIndex` を使用すると、フィールドインデックスを持つロググループとログイベントに実際の検索スペースを制限することで、ペタバイトのログデータを含むロググループを効率的にクエリできます。 例えば、アカウントの一部のロググループで `IPaddress` のフィールドインデックスを作成したとします。その後、次のクエリを作成してアカウント内のすべてのロググループをクエリし、`IPaddress` フィールドの値 `198.51.100.0` を含むログイベントを検索できます。 ``` fields @timestamp, @message | filterIndex IPaddress = "198.51.100.0" | limit 20 ``` `filterIndex` コマンドにより、このクエリは `IPaddress` においてインデックス付けされていないすべてのロググループのスキップを試みます。さらに、インデックス付けされたロググループ内で、クエリは `IPaddress` フィールドを持つもののそのフィールドの値として `198.51.100.0` が観測されないログイベントをスキップします。 `IN` 演算子を使用して、インデックス付きフィールドの複数の値のいずれかに結果を展開します。次の例では、`IPaddress` フィールドで値 `198.51.100.0` または `198.51.100.1` を含むログイベントを検索します。 ``` fields @timestamp, @message | filterIndex IPaddress in ["198.51.100.0", "198.51.100.1"] | limit 20 ``` CloudWatch Logs は、標準ログクラスのすべてのロググループにデフォルトのフィールドインデックスを提供します。デフォルトのフィールドインデックスは、次のフィールドで自動的に使用できます。 + `@logStream` + `@aws.region` + `@aws.account` + `@source.log` + `@data_source_name` + `@data_source_type` + `@data_format` + `traceId` + `severityText` + `attributes.session.id` CloudWatch Logs は、特定のデータソース名とタイプの組み合わせのデフォルトのフィールドインデックスも提供します。デフォルトのフィールドインデックスは、次のデータソース名とタイプの組み合わせで自動的に使用できます。 | データソース名とタイプ | デフォルトのフィールドインデックス | | --- | --- | | `amazon_vpc.flow` | `action` `logStatus` `region` `flowDirection` `type` | | `amazon_route53.resolver_query` | `query_type` `transport` `rcode` | | `aws_waf.access` | `action` `httpRequest.country` | | `aws_cloudtrail.data` ` aws_cloudtrail.management` | `eventSource` `eventName` `awsRegion` `userAgent` `errorCode` `eventType` `managementEvent` `readOnly` `eventCategory` `requestId` | デフォルトのフィールドインデックスは、ポリシー内で定義した任意のカスタムフィールドインデックスに追加されます。デフォルトのフィールドインデックスは、[フィールドインデックスクォータ](CloudWatchLogs-Field-Indexing-Syntax.md)にはカウントされません。 ## filterIndex と filter の比較 `filterIndex` と `filter` の違いを説明するために、次のクエリ例を検討してください。`IPaddress` のフィールドインデックスを 4 つのロググループ向けに作成したものの、5 番目のロググループには作成していないとします。`filterIndex` を使用する次のクエリは、フィールドのインデックスが付けられていないロググループのスキャンをスキップします。インデックス付きロググループごとに、インデックス付きフィールドを持つログイベントのみのスキャンを試行します。また、フィールドインデックスの作成後からの結果のみを返します。 ``` fields @timestamp, @message | filterIndex IPaddress = "198.51.100.0" | limit 20 ``` 対照的に、同じ 5 つのロググループのクエリに `filterIndex` の代わりに `filter` を使用する場合、クエリはインデックス付きロググループの値を含むログイベントだけではなく、インデックス化されていない 5 番目のロググループもスキャンし、その 5 番目のロググループ内のすべてのログイベントをスキャンします。 ``` fields @timestamp, @message | filter IPaddress = "198.51.100.0" | limit 20 ``` # SOURCE クエリ`SOURCE`に を含めることは、 AWS CLI または API を使用してクエリを作成するときに、クエリに含めるロググループやデータソースを指定するのに役立ちます。`SOURCE` コマンドは、CloudWatch コンソールではなく、 AWS CLI および API でのみサポートされます。CloudWatch コンソールを使用してクエリを開始する場合は、コンソールインターフェイスを使用してロググループを指定します。 クエリロググループ `SOURCE` を使用してクエリするロググループを指定するには、次のキーワードを使用できます。 + `namePrefix` は、指定した文字列で始まる名前を持つロググループに対してクエリを実行します。これを省略すると、すべてのロググループがクエリされます。 リストには最大 5 つのプレフィックスを含めることができます。 + `accountIdentifier` は、指定された AWS アカウントのロググループに対してクエリを実行します。これは、モニタリングアカウントでクエリを実行する場合にのみ機能します。これを省略した場合、デフォルトでは、リンクされたすべてのソースアカウントと現在のモニタリングアカウントをクエリします。クロスアカウントオブザーバビリティについて詳しくは「[CloudWatch cross-account observability](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html)」を参照してください。 リストには最大 20 個のアカウント識別子を含めることができます。 + `logGroupClass` は、標準アクセスまたは低頻度アクセスのいずれかの指定されたログクラスにあるロググループに対してクエリを実行します。これを省略した場合、デフォルトの標準ログクラスが使用されます。ログクラスの詳細については、「[ログクラス](CloudWatch_Logs_Log_Classes.md)」を参照してください。 この方法でクエリを実行するために多数のロググループを指定できるため、作成したフィールドインデックスを利用するクエリでのみ `SOURCE` を使用することをお勧めします。インデックスフィールドの詳細については、「[フィールドインデックスを作成してクエリパフォーマンスを改善し、スキャン量を削減する](CloudWatchLogs-Field-Indexing.md)」を参照してください。 次の例では、アカウント内のすべてのロググループを選択します。これがモニタリングアカウントの場合、モニタリング全体のロググループとすべてのソースアカウントが選択されます。ロググループの総数が 10,000 を超える場合は、別のロググループ選択方法を使用してロググループの数を減らすように求めるエラーが表示されます。 ``` SOURCE logGroups() ``` 次の例では、`111122223333` ソースアカウント内のロググループを選択します。CloudWatch のクロスアカウントオブザーバビリティのモニタリングアカウントでクエリを開始する場合は、すべてのソースアカウントだけではなくそのモニタリングアカウントのロググループもデフォルトで選択されます。 ``` SOURCE logGroups(accountIdentifiers:['111122223333']) ``` 次の例では、名前プレフィックスに基づいてロググループを選択します。 ``` SOURCE logGroups(namePrefix: ['namePrefix1', 'namePrefix2']) ``` 次の例では、低頻度アクセスログクラスのすべてのロググループを選択します。`class` 識別子を含めない場合、クエリはデフォルトである標準ログクラスのロググループにのみ適用されます。 ``` SOURCE logGroups(class: ['INFREQUENT_ACCESS']) ``` 次の例では、特定の名前プレフィックスで始まり、標準ログクラスにある 111122223333 アカウントのロググループを選択します。Standard がデフォルトのログクラス値であるため、このクラスはコマンドで説明されません。 ``` SOURCE logGroups(accountIdentifiers:['111122223333'], namePrefix: ['namePrefix1', 'namePrefix2'] ``` 最後の例では、 `SOURCE` コマンドで `start-query` AWS CLI コマンドを使用する方法を示しています。 ``` aws logs start-query --region us-east-1 --start-time 1729728200 --end-time 1729728215 --query-string "SOURCE logGroups(namePrefix: ['Query']) | fields @message | limit 5" ``` データソースのクエリ `SOURCE` を使用してクエリするデータソースを指定するには、 `dataSource`キーワードを使用できます。リストには最大 10 個のデータソースを含めることができます。 次の の例では、`amazon_vpc.flow`データソースを選択します。 ``` SOURCE dataSource(['amazon_vpc.flow']) ``` 次の例では、`amazon_vpc.flow`データソースを選択し、ロググループ名のプレフィックスに基づいてロググループを制限します。 ``` SOURCE dataSource(['amazon_vpc.flow']) logGroups(namePrefix: ['namePrefix1']) ``` # pattern `pattern` を使用してログデータを自動的にパターンにクラスター化します。 パターンは、ログフィールド間で繰り返される共有テキスト構造です。`pattern` を使用して新たな傾向を発見することや既知のエラーをモニタリングすることに加えて、頻繁に発生するログラインやコストの高いログラインを特定することができます。CloudWatch Logs Insights は、ログイベント内のパターンを検索してさらに分析するために使用できるコンソールエクスペリエンスも提供します。詳細については、「[パターン分析](CWL_AnalyzeLogData_Patterns.md)」を参照してください。 `pattern` コマンドは一般的なパターンを自動的に識別するため、ログを検索して分析するための出発点として使用できます。また、`pattern` を ` filter`、` parse`、または ` sort` コマンドと組み合わせて、より微調整されたクエリでパターンを識別することもできます。 **パターンコマンド入力** `pattern` コマンドでは、`@message` フィールド、` parse` コマンドを使用して作成された抽出フィールド、または 1 つ以上の [String 関数](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-operations-functions.html#CWL_QuerySyntax-string-functions)を使用して操作された文字列のいずれかの入力が予期されます。 CloudWatch Logs が動的トークンの表すデータのタイプを推測できない場合は、<トークン - *数値*> として表示され、*数値*は他の動的トークンと比較して、このトークンがパターン内のどこに表示されるかを示します。 動的トークンの一般的な例には、エラーコード、IP アドレス、タイムスタンプ、リクエスト ID があります。 **パターンコマンド出力** `pattern` コマンドは以下の出力を生成します。 + `@pattern`: ログイベントフィールド間で繰り返される共有テキスト構造。リクエスト ID やタイムスタンプなど、パターン内の異なるフィールドは*トークン*によって表現されます。CloudWatch Logs が動的トークンの表すデータのタイプを判断できる場合、トークンは `` として表示されます。*文字列*は、トークンが表すデータのタイプの説明です。*数値*は、他の動的トークンと比較して、このトークンがパターン内のどこに表示されるかを示します。 CloudWatch Logs は、名前を含むログイベントのコンテンツの分析に基づいて、その名前の文字列部分を割り当てます。 CloudWatch Logs が動的トークンの表すデータのタイプを推測できない場合は、<トークン - *数値*> として表示され、*数値*は他の動的トークンと比較して、このトークンがパターン内のどこに表示されるかを示します。 例えば、`[INFO] Request time: ms` はログメッセージ `[INFO] Request time: 327 ms` の出力候補です。 + `@ratio`: 選択した期間のログイベントと、識別されたパターンに一致する特定のロググループのログイベントの割合。例えば、選択したロググループと期間のログイベントの半分がパターンと一致する場合、`@ratio` は `0.50` を返します。 + `@sampleCount`: 選択した期間のログイベントと、識別されたパターンに一致する特定のロググループのログイベントの数。 + `@severityLabel`: ログの重要度またはレベル。ログに含まれる情報の種類を示します。`Error`、`Warning`、`Info`、`Debug` などが該当します。 **例** 次のコマンドは、選択した時間範囲内の指定されたロググループ内の構造が似ているログを識別し、パターンと数でグループ化します。 ``` pattern @message ``` `pattern` コマンドは ` filter` コマンドと組み合わせて使用できます ``` filter @message like /ERROR/ | pattern @message ``` `pattern` コマンドは、` parse` および ` sort` コマンドと共に使用できます。 ``` filter @message like /ERROR/ | parse @message 'Failed to do: *' as cause | pattern cause | sort @sampleCount asc ``` # diff リクエストされた期間に検出されたログイベントと、以前の期間と同じ長さのログイベントを比較します。これにより、傾向を検索し、特定のログイベントが新しいかどうかを確認できます。 `diff` コマンドに修飾子を追加して、比較する期間を指定します。 + `diff` は、現在選択されている時間範囲のログイベントを直前の時間範囲のログイベントと比較します。 + `diff previousDay` は、現在選択されている時間範囲のログイベントを、前日の同じ時刻のログイベントと比較します。 + `diff previousWeek` は、現在選択されている時間範囲のログイベントを、前週の同じ時刻のログイベントと比較します。 + `diff previousMonth` は、現在選択されている時間範囲のログイベントを、前月と同じ時刻のログイベントと比較します。 詳細については、「[(diff) を以前の時間範囲と比較する](CWL_AnalyzeLogData_Compare.md)」を参照してください。 # parse `parse` を使用して、ログフィールドからデータを抽出し、クエリで処理できる抽出フィールドを作成します。 **`parse`** は、ワイルドカードを使用する glob モードと正規表現の両方をサポートします。正規表現の構文の詳細については、「[サポートされている正規表現 (regex) 構文](FilterAndPatternSyntax.md#regex-expressions)」を参照してください。 ネストされた JSON フィールドは正規表現で解析できます。 **例: ネストされた JSON フィールドの解析** コードスニペットは、取り込み中にフラット化された JSON ログイベントを解析する方法を示します。 ``` {'fieldsA': 'logs', 'fieldsB': [{'fA': 'a1'}, {'fA': 'a2'}]} ``` コードスニペットは、`fieldsA` および `fieldsB` の値を抽出し、抽出フィールド `fld` および `array` を作成する正規表現を含むクエリを示します。 ``` parse @message "'fieldsA': '*', 'fieldsB': ['*']" as fld, array ``` 名前付きキャプチャグループ 正規表現で **`parse`** を使用すると、名前付きキャプチャグループを使用してパターンをフィールドに取り込むことができます。構文は `parse @message (?pattern)` です。 次の例では、VPC フローログのキャプチャグループを使用して、ENI を `NetworkInterface` という名前のフィールドに抽出します。 ``` parse @message /(?eni-.*?) / | display NetworkInterface, @message ``` **注記** JSON ログイベントは取り込み中にフラット化されます。現在、ネストされた JSON フィールドを glob 表現で解析することはサポートされていません。解析できるのは、200 個以下のログイベントフィールドを含む JSON ログイベントのみです。ネストされた JSON フィールドを解析するときは、クエリ内の正規表現を JSON ログイベントの形式と一致するようにフォーマットする必要があります。 ## 解析コマンドの例 **glob 式を使用して、ログフィールド `@message` から、抽出フィールド `@user`、`@method`、`@latency` を抽出し、`@method` および `@user` との一意の組み合わせごとに平均レイテンシーを返します。** ``` parse @message "user=*, method:*, latency := *" as @user, @method, @latency | stats avg(@latency) by @method, @user ``` **正規表現を使用して、ログフィールド `@message` から、フィールド `@user2`、`@method2`、`@latency2` を抽出し、`@method2` および `@user2` との一意の組み合わせごとに平均レイテンシーを返します。** ``` parse @message /user=(?.*?), method:(?.*?), latency := (?.*?)/ | stats avg(latency2) by @method2, @user2 ``` **フィールド `loggingTime`、`loggingType`、`loggingMessage` を抽出し、`ERROR` または `INFO` 文字列を含むログイベントをフィルタリングし、`ERROR` 文字列を含むイベントの `loggingMessage` および `loggingType` フィールドのみを表示します。** ``` FIELDS @message | PARSE @message "* [*] *" as loggingTime, loggingType, loggingMessage | FILTER loggingType IN ["ERROR", "INFO"] | DISPLAY loggingMessage, loggingType = "ERROR" as isError ``` # sort `sort` を使用して、ログイベントを指定したフィールドごとに昇順 (`asc`) または降順 (`desc`) で表示します。これを `limit` コマンドと一緒に使用すれば、「上位 N 件」または「下位 N 件」のクエリを作成できます。 ソートアルゴリズムは、自然ソートの更新バージョンです。昇順でソートする場合、次のロジックが使用されます。 + 数値以外のすべての値は、すべての数値より前に来ます。*数値*は数のみを含む値であり、数と他の文字の組み合わせは含まれません。 + 数以外の値の場合、アルゴリズムは、連続する数と連続するアルファベット文字を別々のチャンクにグループ化して比較します。数以外の部分は Unicode 値の順に並び、数の部分は最初に長さ順に並んでから、数値の順に並びます。 Unicode の順序の詳細については、「[List of Unicode character](https://en.wikipedia.org/wiki/List_of_Unicode_characters)」を参照してください。 例として、昇順のソートの結果を次に示します。 ``` !: >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> sorted by unicode order # *%04 0# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Alphanumeric starting with numbers 5A 111A >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Starts with more digits than 5A, so it sorted to be later than 5A 2345_ @ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 2345 is compared with @ in the unicode order, @_ A >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Values starting with letters A9876fghj a12345hfh 0 >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Number values 01 1 2 3 ``` 降順でソートする場合、ソート結果は逆になります。 例えば、Amazon VPC フローログの次のクエリでは、ホスト間のパケット転送の上位 15 件を検索します。 ``` stats sum(packets) as packetsTransferred by srcAddr, dstAddr | sort packetsTransferred desc | limit 15 ``` # stats `stats` を使用して、ログデータを棒グラフ、折れ線グラフ、積み上げ面グラフなどで視覚化します。これにより、ログデータのパターンをより効率的に特定できます。CloudWatch Logs Insights は、`stats` 関数と 1 つ以上の集計関数を使用するクエリの視覚化を生成します。 例えば、Route 53 ロググループの次のクエリは、Route 53 レコードの 1 時間あたりのディストリビューションをクエリタイプ別に視覚化して返します。 ``` stats count(*) by queryType, bin(1h) ``` このようなクエリはすべて、棒グラフを生成できます。クエリで `bin()` 関数を使用して、時間の経過とともにデータを 1 つのフィールドでグループ化する場合、折れ線グラフや積み上げ面グラフも表示できます。 `bin` 関数では、次の時間単位と略語がサポートされています。複数の文字を含むすべての単位と略語では、s の複数形への追加がサポートされています。したがって、`hr` および `hrs` の両方とも時間を指定して機能します。 + `millisecond` `ms` `msec` + `second` `s` `sec` + `minute` `m` `min` + `hour` `h` `hr` + `day` `d` + `week` `w` + `month` `mo` `mon` + `quarter` `q` `qtr` + `year` `y` `yr` **Topics** + [時系列データを視覚化](#CWL_Insights-Visualizing-TimeSeries) + [フィールド別にグループ化されたログデータを視覚化](#CWL_Insights-Visualizing-ByFields) + [1 つのクエリで複数の stats コマンドを使用する](#CWL_QuerySyntax-stats-multi) + [統計と併用する関数](#CWL_QuerySyntax-stats-functions) ## 時系列データを視覚化 時系列の視覚化は、次の特性を持つクエリで機能します。 + 1 つ以上の集計関数が含まれているクエリ。詳細については、「[Aggregation Functions in the Stats Command](#CWL_Insights_Aggregation_Functions)」を参照してください。 + `bin()` 関数を使用して 1 つのフィールドでデータをグループ化するクエリ。 これらのクエリは、折れ線グラフ、積み上げ面グラフ、棒グラフ、円グラフを生成できます。 **例** 完全なチュートリアルについては、「[チュートリアル: 時系列の視覚化を生成するクエリを実行する](CWL_AnalyzeLogData_VisualizationQuery.md)」を参照してください。 時系列の視覚化で機能するクエリの他の例を以下に示します。 次のクエリでは、`myfield1` フィールドの平均値の視覚化を生成します。データポイントは 5 分間隔で作成されます。各データポイントは、それまでの 5 分間隔のログに基づく `myfield1` 値の平均の集約です。 ``` stats avg(myfield1) by bin(5m) ``` 次のクエリでは、異なるフィールドに基づく 3 つの値の視覚化を生成します。データポイントは 5 分間隔で作成されます。視覚化が生成されるのは、クエリに集計関数が含まれており、グループ化フィールドとして `bin()` が使用されているためです。 ``` stats avg(myfield1), min(myfield2), max(myfield3) by bin(5m) ``` **折れ線グラフと積み上げ面グラフの制限** ログエントリ情報を集計するが、`bin()` 関数を使用しないクエリでは、棒グラフを生成できます。ただし、これらのクエリは折れ線グラフや積み上げ面グラフを生成できません。これらのタイプのクエリの詳細については、「[フィールド別にグループ化されたログデータを視覚化](#CWL_Insights-Visualizing-ByFields)」を参照してください。 ## フィールド別にグループ化されたログデータを視覚化 `stats` 関数と 1 つ以上の集計関数を使用するクエリの棒グラフを作成できます。詳細については、「[Aggregation Functions in the Stats Command](#CWL_Insights_Aggregation_Functions)」を参照してください。 視覚化を表示するには、クエリを実行します。次に、[**Visualization (視覚化)**] タブを選択し、[**Line (線)**] の横にある矢印を選択して、[**Bar (棒)**] を選択します。棒グラフでは、視覚化は最大 100 本の棒に制限されています。 **例** 完全なチュートリアルについては、「[チュートリアル: ログフィールド別にグループ化された視覚化を生成するクエリを実行する](CWL_AnalyzeLogData_VisualizationFieldQuery.md)」を参照してください。次の段落では、フィールド別の視覚化のクエリに関する他の例を示します。 次の VPC フローログクエリは、各宛先アドレスについて、セッションごとに転送された平均バイト数を検出します。 ``` stats avg(bytes) by dstAddr ``` また、結果の値ごとに複数の棒を含むグラフを生成することもできます。たとえば、次の VPC フローログクエリは、各宛先アドレスについて、セッションごとに転送された平均および最大バイト数を検出します。 ``` stats avg(bytes), max(bytes) by dstAddr ``` 次のクエリは、各クエリタイプの Amazon Route 53 クエリログの数を検出します。 ``` stats count(*) by queryType ``` ## 1 つのクエリで複数の stats コマンドを使用する 1 つのクエリで最大 2 つの `stats` コマンドを使用できます。これにより、最初の集計の出力に対して追加の集計を実行できます。 **例: 2 つの `stats` コマンドによるクエリ** 例えば、次のクエリは、最初に 5 分間のビンの合計トラフィック量を検索し、次に、その 5 分間のビンの中で最大、最低、および平均のトラフィック量を計算します。 ``` FIELDS strlen(@message) AS message_length | STATS sum(message_length)/1024/1024 as logs_mb BY bin(5m) | STATS max(logs_mb) AS peak_ingest_mb, min(logs_mb) AS min_ingest_mb, avg(logs_mb) AS avg_ingest_mb ``` **例: 複数の stats コマンドを `filter`、`fields`、`bin` などの他の関数と組み合わせます。** 1 つのクエリで、2 つの `stats` コマンドを、`filter` や `fields` などの他のコマンドと組み合わせることができます。例えば、次のクエリは、セッション内の異なる IP アドレス数を調べ、クライアントプラットフォームごとにセッション数を調べて、それらの IP アドレスをフィルタリングして、最後にクライアントプラットフォームごとのセッションリクエストの平均を求めます。 ``` STATS count_distinct(client_ip) AS session_ips, count(*) AS requests BY session_id, client_platform | FILTER session_ips > 1 | STATS count(*) AS multiple_ip_sessions, sum(requests) / count(*) AS avg_session_requests BY client_platform ``` クエリでは、`bin` と `dateceil` の関数を複数の `stats` コマンドと共に使用できます。例えば、次のクエリは、最初にメッセージを 5 分のブロックに結合し、次に 5 分間のブロックを 10 分のブロックに集約して、各 10 分ブロック内の最大、最低、および平均のトラフィック量を計算します。 ``` FIELDS strlen(@message) AS message_length | STATS sum(message_length) / 1024 / 1024 AS logs_mb BY BIN(5m) as @t | STATS max(logs_mb) AS peak_ingest_mb, min(logs_mb) AS min_ingest_mb, avg(logs_mb) AS avg_ingest_mb BY dateceil(@t, 10m) ``` **注意事項と制限事項** 1 つのクエリにつき、最大 2 つの `stats` コマンドを持つことができます。このクォータは変更できません。 `sort` または `limit` コマンドを使用する場合は、2 番目の `stats` コマンドの後に指定する必要があります。2 番目の `stats` コマンドより前に置くと、クエリは無効になります。 クエリに 2 つの `stats` コマンドがある場合、1 つ目の `stats` 集計が完了するまで、クエリの結果の一部は表示されなくなります。 1 つのクエリにある 2 番目の `stats` コマンドでは、1 番目の `stats` コマンドで定義されているフィールドのみを参照できます。例えば、最初の `stats` 集計以降 `@message` フィールドが使用できなくなるため、次のクエリは無効です。 ``` FIELDS @message | STATS SUM(Fault) by Operation # You can only reference `SUM(Fault)` or Operation at this point | STATS MAX(strlen(@message)) AS MaxMessageSize # Invalid reference to @message ``` 最初の `stats` コマンドの後に参照するフィールドは、すべて最初の `stats` コマンドで定義する必要があります。 ``` STATS sum(x) as sum_x by y, z | STATS max(sum_x) as max_x by z # You can only reference `max(sum_x)`, max_x or z at this point ``` **重要** この `bin` 関数は常に `@timestamp` フィールドを暗黙的に使用します。つまり、2 番目の `stats` コマンドでは、1 番目の `stats` コマンドを使用して `timestamp` フィールドを伝達しないと `bin` を使用できないということです。例えば、以下のクエリは有効ではありません。 ``` FIELDS strlen(@message) AS message_length | STATS sum(message_length) AS ingested_bytes BY @logStream | STATS avg(ingested_bytes) BY bin(5m) # Invalid reference to @timestamp field ``` 代わりに、最初の `stats` コマンドで `@timestamp` フィールドを定義し、次の例のように 2 番目の `stats` コマンドで `dateceil` と共にそれを使用できます。 ``` FIELDS strlen(@message) AS message_length | STATS sum(message_length) AS ingested_bytes, max(@timestamp) as @t BY @logStream | STATS avg(ingested_bytes) BY dateceil(@t, 5m) ``` ## 統計と併用する関数 CloudWatch Logs Insights は、統計集計関数と統計非集計関数の両方をサポートしています。 statsaggregation 関数は、`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` の値を返します。 | # 制限 `limit` を使用して、クエリで返すログイベントの数を指定します。`limit` を省略すると、クエリは結果に最大 10,000 個のログイベントを返します。 例えば、以下の例は、最新の 25 のログイベントのみを返しています。 ``` fields @timestamp, @message | sort @timestamp desc | limit 25 ``` # 重複排除 指定したフィールドの特定の値に基づいて、重複した結果を削除するときは、`dedup` を使用します。`dedup` は 1 つ以上のフィールドで使用できます。`dedup` を使ってフィールドを 1 つ指定すると、そのフィールドの一意の値ごとに 1 つのログイベントのみが返されます。複数のフィールドを指定すると、そのフィールドの一意の値の組み合わせごとに 1 つのログイベントが返されます。 重複はソート順に基づいて破棄され、ソート順の最初の結果だけが保持されます。`dedup` コマンドを実行する前に、結果をソートすることが推奨されます。`dedup` を実行する前に結果がソートされていない場合は、`@timestamp` を使用しているデフォルトの降順のソート順が使用されます。 NULL 値は、評価において重複とは見なされません。指定したフィールドのいずれかに NULL 値が含まれるログイベントは保持されます。NULL 値のフィールドを削除するには、`isPresent(field)` 関数を使用して **`filter`** を実行します。 `dedup` コマンドの後のクエリで使用できるクエリコマンドは、`limit` だけです。 クエリ`dedup`で を使用すると、コンソールに「**Showing X of Y records**」などのメッセージが表示されます。ここで、X は重複排除された結果の数、Y は重複排除前に一致したレコードの合計数です。これは、重複したレコードが削除されたことを示すものであり、データが欠落していることを意味するものではありません。 **例: `server` という名前のフィールドの、一意の値ごとに、最新のログイベントのみを表示 します。** 次の例では、`server` の一意の値ごとに、最新のイベントの `timestamp`、`server`、`severity`、`message` フィールドのみを表示します。 ``` fields @timestamp, server, severity, message | sort @timestamp desc | dedup server ``` CloudWatch Logs Insights クエリのその他の例については、「[一般的なクエリ](CWL_QuerySyntax-examples.md#CWL_QuerySyntax-examples-general)」を参照してください。 # マスクを外す データ保護ポリシーにより一部のコンテンツがマスクされているログイベントのすべてのコンテンツを表示するには `unmask` を使用します。このコマンドを使用するには、`logs:Unmask` アクセス許可が必要です。 ロググループのデータ保護の詳細については、「[機密性の高いログデータをマスキングで保護する](mask-sensitive-log-data.md)」を参照してください。 # ネスト解除 `unnest` を使用し、入力として取得されたリストをフラット化し、リスト内の各要素に対して 1 つのレコードを持つ複数のレコードを生成します。フィールドに含まれる項目の数に基づいて、このコマンドは現在のレコードを破棄し、新しいレコードを生成します。各レコードには、項目を表す `unnested_field` が含まれます。他のすべてのフィールドは元のレコードから取得されます。 `unnest` の入力は `LIST` で、`jsonParse` 関数から取得されます。詳細については、「[構造型](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-operations-functions.html#CWL_QuerySyntax-structure-types)」を参照してください。`MAP`、`String`、`numbers` などの他のタイプは、`unnest` に 1 つの項目を含むリストとして扱われます。 **コマンド構造** 以下の例はこのコマンドの形式を説明しています。 ``` unnest field into unnested_field ``` **クエリの例** 次の例では、JSON オブジェクト文字列を解析し、フィールドイベントのリストを展開します。 ``` fields jsonParse(@message) as json_message | unnest json_message.events into event | display event.name ``` このクエリ例のログイベントは、次のように JSON 文字列になります。 ``` { "events": [ { "name": "exception" }, { "name": "user action" } ] } ``` この場合、サンプルクエリはクエリ結果に 2 つのレコードを生成します。1 つは `exception` として `event.name` を使用し、もう 1 つは**ユーザーアクション**として `event.name` を使用します。 **クエリの例** 次の例では、リストをフラット化し、項目を除外します。 ``` fields jsonParse(@message) as js | unnest js.accounts into account | filter account.type = "internal" ``` **クエリの例** 次の例では集計用のリストをフラット化します。 ``` fields jsonParse(trimmedData) as accounts | unnest accounts into account | stats sum(account.droppedSpans) as n by account.accountId | sort n desc | limit 10 ``` # lookup を使用して`lookup`、ルックアップテーブルからの参照データを使用してクエリ結果を強化します。ルックアップテーブルには、Amazon CloudWatch Logs にアップロードする CSV データが含まれています。クエリが実行されると、 `lookup` コマンドはログイベントのフィールドをルックアップテーブルのフィールドと照合し、指定された出力フィールドを結果に追加します。 ユーザー IDsユーザーの詳細にマッピングする、製品コードを製品情報にマッピングする、エラーコードをエラーの説明にマッピングするなどのデータエンリッチメントシナリオには、ルックアップテーブルを使用します。 ## ルックアップテーブルの作成と管理 クエリで `lookup` コマンドを使用する前に、ルックアップテーブルを作成する必要があります。ルックアップテーブルは、CloudWatch コンソールから、または Amazon CloudWatch Logs API を使用して作成および管理できます。 **ルックアップテーブルを作成するには (コンソール)** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**設定**を選択し、**ログ**タブを選択します。 1. **ルックアップテーブル**までスクロールし、**管理**を選択します。 1. **ルックアップテーブルの作成** を選択します。 1. ルックアップテーブルの名前を入力します。名前には、英数字、ハイフン、アンダースコアのみを含めることができます。 1. (オプション) 説明を入力します。 1. CSV ファイルをアップロードします。ファイルには、列名を含むヘッダー行を含める必要があり、UTF-8 エンコーディングを使用し、10 MB を超えることはできません。 1. (オプション) テーブルデータを暗号化する AWS KMS キーを指定します。 1. **[作成]** を選択します。 ルックアップテーブルを作成したら、CloudWatch Logs Insights クエリエディタで表示できます。**Lookup tables** タブを選択して、使用可能なテーブルとそのフィールドを参照します。 ルックアップテーブルを更新するには、テーブルを選択し、**アクション**、**更新**を選択します。新しい CSV ファイルをアップロードして、既存のすべてのコンテンツを置き換えます。ルックアップテーブルを削除するには、**アクション**、**削除**を選択します。 **注記** アカウントごとに、 ごとに最大 100 個のルックアップテーブルを作成できます AWS リージョン。CSV ファイルは最大 10 MB です。Amazon CloudWatch Logs API を使用してルックアップテーブルを管理することもできます。詳細については、*Amazon CloudWatch Logs API リファレンス*の「[CreateLookupTable](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLookupTable.html)」を参照してください。 **注記** ルックアップテーブルが KMS キーで暗号化されている場合、そのルックアップテーブルを参照するクエリで `StartQuery` API を使用するには、呼び出し元がキー (ルックアップテーブルの暗号化に使用される KMS キー) に対する`kms:Decrypt`アクセス許可を持っている必要があります。詳細については、「[を使用して CloudWatch Logs のルックアップテーブルを暗号化する AWS Key Management Service](encrypt-lookup-tables-kms.md)」を参照してください。 ## 検索のクエリ構文 **コマンド構造** このコマンドの形式を次に示します。 ``` lookup table lookup-field as log-field [,...] output-mode output-field[,...] ``` コマンドは、次の引数を使用します。 + `table` – 使用するルックアップテーブルの名前。 + `lookup-field` – 照合するルックアップテーブルのフィールド。 + `log-field` – 一致するログイベントのフィールド。一致は完全で大文字と小文字が区別されます。 + `output-mode` – 出力フィールドを結果`OUTPUT`に追加するには、 を指定します。ログイベントに同じ名前のフィールドがすでに存在する場合、上書きされます。 + `output-field` – 結果に追加するルックアップテーブルの 1 つ以上のフィールド。 **例: ユーザーの詳細を使用してログイベントを強化する** `id` フィールドを含むイベントを含むロググループと、列 `id`、、`name`、`email`および `user_data`を含む という名前のルックアップテーブルがあるとします`department`。次のクエリは、各ログイベントをルックアップテーブルのユーザー名、E メール、部門で強化します。 ``` fields action, status, name, email, department | lookup user_data id OUTPUT name, email, department ``` **例: 集計でルックアップを使用する** 集計関数でルックアップ出力フィールドを使用できます。次のクエリは、ユーザーの詳細を含むログイベントを強化し、E メールアドレス別にグループ化されたイベントをカウントします。 ``` fields user_id, action, username, email, department | lookup user_data user_id OUTPUT username, email, department | stats count(*) by email ``` **例: フィルターでルックアップを使用する** ルックアップによって返されたフィールドに基づいて結果をフィルタリングできます。次のクエリは、ログイベントを強化し、特定の部門のイベントのみを表示するようにフィルタリングします。 ``` fields user_id, action | lookup user_data user_id OUTPUT username, email, department | filter department = "Engineering" ``` # ブール、比較、数値、日時、その他の関数 CloudWatch Logs Insights は、以下のセクションで説明するように、クエリ内の他の多くの演算や関数をサポートしています。 **Topics** + [算術演算子](#CWL_QuerySyntax-operations-arithmetic) + [ブール演算子](#CWL_QuerySyntax-operations-Boolean) + [比較演算子](#CWL_QuerySyntax-operations-comparison) + [数値演算子](#CWL_QuerySyntax-operations-numeric) + [構造型](#CWL_QuerySyntax-structure-types) + [日時関数](#CWL_QuerySyntax-datetime) + [一般関数](#CWL_QuerySyntax-general-functions) + [JSON 関数](#CWL_QuerySyntax-json-functions) + [IP アドレス文字列関数](#CWL_QuerySyntax-IPaddress-functions) + [文字列関数](#CWL_QuerySyntax-string-functions) ## 算術演算子 算術演算子は、数値データ型を引数として受け入れ、数値結果を返します。算術演算子は、`filter` コマンドと `fields` コマンドで使用します。また、他の関数の引数としても使用します。 | 運用 | 説明 | | --- | --- | | `a + b` | 加算 | | `a - b` | 減算 | | `a * b` | 乗算 | | `a / b` | 除算 | | `a ^ b` | 指数 (`2 ^ 3` は `8` を返します) | | `a % b` | 残余または剰余 (`10 % 3` は `1` を返します) | ## ブール演算子 ブール演算子 `and`、`or`、および `not` を使用します。 **注記** ブール演算子は、**TRUE** または **FALSE** の値を返す関数でのみ使用します。 ## 比較演算子 比較演算子は、すべてのデータ型を引数として受け入れ、ブール値の結果を返します。比較オペレーションは、`filter` コマンドで使用します。また、他の関数の引数としても使用します。 | 演算子 | 説明 | | --- | --- | | `=` | Equal | | `!=` | 等しくない | | `<` | Less than | | `>` | Greater than | | `<=` | 以下 | | `>=` | 以上 | ## 数値演算子 数値オペレーションは、数値データ型を引数として受け入れ、数値結果を返します。数値オペレーションは、`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)` | 数値 | 平方根 | ## 構造型 マップまたはリストは、クエリの属性にアクセスして使用できる、CloudWatch Logs Insights の構造型です。 **例: マップまたはリストを取得するには** `jsonParse` を使用して、JSON 文字列であるフィールドを解析し、マップまたはリストにします。 ``` fields jsonParse(@message) as json_message ``` **例: 属性にアクセスするには** ドットアクセス演算子 (map.attribute) を使用して、マップ内の項目にアクセスします。マップ内の属性に特殊文字が含まれている場合は、バッククォートを使用して属性名を囲みます (map.attributes.`special.char`)。 ``` fields jsonParse(@message) as json_message | stats count() by json_message.status_code ``` ブラケットアクセス演算子 (list[index]) を使用して、リスト内の特定の位置にある項目を取得します。 ``` fields jsonParse(@message) as json_message | filter json_message.users[1].action = "PutData" ``` キー名に特殊文字が含まれている場合は、特殊文字をバッククォート (``) でラップします。 ``` fields jsonParse(@message) as json_message | filter json_message.`user.id` = "123" ``` **例: 空の結果** マップとリストは、文字列、数値、日時関数では null として扱われます。 ``` fields jsonParse(@message) as json_message | display toupper(json_message) ``` マップとリストを他のフィールドと比較すると `false` になります。 **注記** `dedup`、`pattern`、`sort`、`stats` におけるマップとリストの使用はサポートされていません。 ## 日時関数 **日時関数** 日時関数は、`fields` コマンドと `filter` コマンドで使用します。また、他の関数の引数としても使用します。これらの関数では、集計関数を使用してクエリの時間バケットを作成します。数値と次のいずれかで構成される期間を使用します。 + `ms` はミリ秒 + `s` は秒 + `m` は分 + `h` は時間 たとえば、`10m` は 10 分、`1h` は 1 時間です。 **注記** 日時関数に最適な時間単位を使用します。CloudWatch Logs は、選択した時間単位に従ってリクエストを制限します。例えば、`s` を使用するすべてのリクエストの最大値として 60 を上限とします。したがって、`bin(300s)` を指定すると、CloudWatch Logs はこれを 60 秒として実際に実装します。60 は 1 分間の秒数であるため、CloudWatch Logs は `s` で 60 を超える数値を使用しません。5 分間のバケットを作成するには、代わりに `bin(5m)` を使用します。 `ms` の上限は 1000、`s` と `m` の上限は 60、`h` の上限は 24 です。 次の表は、クエリコマンドで使用できるさまざまな日付時刻関数のリストを示したものです。このリストには、各関数の結果タイプと説明が記載されています。 **ヒント** クエリコマンドを作成するときに、時間間隔セレクタを使用してクエリの対象とする期間を選択できます。例えば、5～30 分間隔、1 時間、3 時間、12 時間間隔、またはカスタム時間枠の期間を設定できます。また、特定の日付の間で期間を指定することもできます。 | 関数 | 結果タイプ | 説明 | | --- | --- | --- | | `bin(period: Period)` | タイムスタンプ | `@timestamp` の値を特定の期間に切り上げ、次に切り詰めます。例えば、`bin(5m)` は `@timestamp` の値を最も近い 5 分に四捨五入します。 これを使用して、複数のログエントリをクエリにまとめることができます。次の例では、1 時間あたりの例外の数を返します。 
filter @message like /Exception/ 
    | stats count(*) as exceptionCount by bin(1h)
    | sort exceptionCount desc
`bin` 関数では、次の時間単位と略語がサポートされています。複数の文字を含むすべての単位と略語では、s の複数形への追加がサポートされています。したがって、`hr` および `hrs` の両方とも時間を指定して機能します。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-operations-functions.html) | | `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 エポックからのミリ秒を表す数値に変換します。例えば、`toMillis(@timestamp)` はタイムスタンプを `2022-01-14T13:18:031.000-08:00` から `1642195111000` に変換します。 | | `now()` | 数値 | クエリ処理が開始された時刻をエポック秒単位で返します。この関数は引数を取りません。 これを使用して、現在の時刻に従ってクエリ結果をフィルタリングできます。 例えば、次のクエリは、過去 2 時間の 4xx エラーをすべて返します。 
parse @message "Status Code: *;" as statusCode\n 
| filter statusCode >= 400 and statusCode <= 499  \n 
| filter toMillis(@timestamp) >= (now() * 1000 - 7200000)
次の例では、`error` または `failure` という単語のいずれかを含む過去 5 時間のすべてのログエントリを返します。 
fields @timestamp, @message 
| filter @message like /(?i)(error|failure)/ 
| filter toMillis(@timestamp) >= (now() * 1000 - 18000000)
| **注記** 現在、CloudWatch Logs Insights では、可読性のあるタイムスタンプが記録されているログのフィルタリングをサポートしていません。 ## 一般関数 **一般関数** 一般関数は、`fields` コマンドと `filter` コマンドで使用します。また、他の関数の引数としても使用します。 | 関数 | 結果タイプ | 説明 | | --- | --- | --- | | `ispresent(fieldName: LogField)` | ブール値 | フィールドが存在する場合は `true` を返します | | `coalesce(fieldName: LogField, ...fieldNames: LogField[])` | LogField | リストから最初の null でない値を返します | ## JSON 関数 **JSON 関数** JSON 関数は、`fields` コマンドと `filter` コマンドで使用します。また、他の関数の引数としても使用します。 | 関数 | 結果タイプ | 説明 | | --- | --- | --- | | `jsonParse(fieldName: string)` | マップ \$1 リスト \$1 空 | 入力が JSON オブジェクトまたは JSON 配列の文字列表現である場合、マップまたはリストを返します。入力がその表現のいずれかでない場合、空の値を返します。 | | `jsonStringify(fieldName: Map \| List)` | String | マップまたはリストデータから JSON 文字列を返します。 | ## IP アドレス文字列関数 **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 表記を使用します。`192.0.2.0` または `2001:db8::` は CIDR ブロックの開始アドレスです。 | | `isIpv4InSubnet(fieldName: string, subnet: string)` | boolean | 指定された v4 サブネット内でフィールドが有効な IPv4 アドレスである場合、`true` を返します。サブネットを指定するときは、`192.0.2.0/24` などの CIDR 表記を使用します。`192.0.2.0` は CIDR ブロックの開始アドレスです。 | | `isIpv6InSubnet(fieldName: string, subnet: string)` | boolean | 指定された v6 サブネット内でフィールドが有効な IPv6 アドレスである場合、`true` を返します。サブネットを指定するときは、`2001:db8::/32` などの CIDR 表記を使用します。`2001:db8::` は CIDR ブロックの開始アドレスです。 | ## 文字列関数 **文字列関数** 文字列関数は、`fields` コマンドと `filter` コマンドで使用します。また、他の関数の引数としても使用します。 | 関数 | 結果タイプ | 説明 | | --- | --- | --- | | `isempty(fieldName: string)` | Number | フィールドが欠落しているか、空の文字列である場合、`1` を返します。 | | `isblank(fieldName: string)` | Number | フィールドが欠落しているか、空の文字列であるか、空白が含まれている場合、`1` を返します。 | | `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(fieldName: string, searchValue: string, replaceValue: string)` | 文字列 | `searchValue` の `fieldName: string` のすべてのインスタンスを `replaceValue` に置き換えます。 例えば、関数 `replace(logGroup,"smoke_test","Smoke")` はフィールド `logGroup` に文字列値 `smoke_test` を含むログイベントを検索し、その値を文字列 `Smoke` に置き換えます。 | | `strcontains(str: string, searchValue: string)` | 数値 | `str` に `searchValue` が含まれている場合は 1 を返し、それ以外の場合は 0 を返します。 | # 特殊文字を含むフィールド フィールドに `@` 記号またはピリオド (`.`) 以外の英数字以外の文字が含まれている場合は、フィールドをバッククォート文字 (```) で囲む必要があります。例えば、ログフィールド `foo-bar` では英数字以外の文字であるハイフン (``foo-bar``) が含まれているため、バッククォート (`-`) で囲む必要があります。 # クエリでのエイリアスとコメントの使用 エイリアスを含むクエリを作成します。ログフィールドの名前を変更するために、またはフィールドに値を抽出する場合にエイリアスを使用します。キーワード `as` を使用して、ログフィールドまたは結果にエイリアスを指定します。クエリ内で複数のエイリアスを使用できます。次のコマンド内でエイリアスを使用できます。 + `fields` + `parse` + `sort` + ` stats ` 次の例では、エイリアスを含むクエリを作成する方法を示します。 **例** クエリの `fields` コマンドはエイリアスを含みます。 ``` fields @timestamp, @message, accountId as ID | sort @timestamp desc | limit 20 ``` クエリは、フィールド `@timestamp`、`@message`、および `accountId` の値を返します。結果は降順でソートされ、20 に制限されます。`ID` の値は、エイリアス `accountId` の下に一覧表示されます。 **例** クエリの `sort` および `stats` コマンドはエイリアスを含みます。 ``` stats count(*) by duration as time | sort time desc ``` クエリは、ロググループでフィールド `duration` が発生した回数をカウントし、結果を降順で並べ替えます。`duration` の値は、エイリアス `time` の下に一覧表示されます。 ## コメントの使用 CloudWatch Logs Insights は、クエリ内でのコメントをサポートしています。ハッシュ文字 (**\$1**) を使用してコメントを開始します。コメントを使用して、クエリまたはドキュメントクエリの行を無視できます。 **例: クエリ** 次のクエリを実行すると、2 行目は無視されます。 ``` fields @timestamp, @message, accountId # | filter accountId not like "7983124201998" | sort @timestamp desc | limit 20 ```