翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # CloudWatch Logs Insights を使用したログデータの分析 CloudWatch Logs Insights を使用すると、Amazon CloudWatch Logs のログデータをインタラクティブに検索し分析することができます。クエリを実行して、運用上の問題により効率的かつ効果的に対応できます。ロググループを使用したクエリに加えて、ファセット、データソース、データ型を使用してクエリを実行できます。問題が発生した場合は、CloudWatch Logs Insights を使用して、潜在的な原因を特定し、デプロイされた修正を検証することができます。ダッシュボードに追加されたクエリを含め、アカウントあたりの同時 CloudWatch Logs Insights QL は 100 に制限されています。さらに、OpenSearch Service PPL または OpenSearch Service SQL のいずれかに対して 15 OpenSearch の同時クエリを実行できます。 CloudWatch Logs Insights は、クエリに使用できる 3 つのクエリ言語をサポートしています。 + いくつかのシンプルで強力なコマンドを備えた目的別の **Logs Insights クエリ言語 (Logs Insights QL)**。 + **OpenSearch Service パイプ処理言語 (PPL)**。OpenSearch PPL を使用すると、パイプ (\$1) で区切られた一連のコマンドを使用してログを分析できます。 OpenSearch PPL を使用すると、パイプ処理されたコマンドを使用してデータを取得、クエリ、分析できるため、複雑なクエリの理解と構成が容易になります。構文を使用すると、コマンドを連鎖してデータの変換と処理を行えます。PPL を使用すると、データをフィルターして集計し、豊富な一連の算術、文字列、日付、条件付きなどの関数を用いて分析できます。 + **OpenSearch Service 構造化クエリ言語 (SQL)**。OpenSearch SQL クエリを使用すると、宣言的な方法でログを分析できます。SELECT、FROM、WHERE、GROUP BY、HAVING などのコマンドや、SQL で使用できるその他のさまざまなコマンドや関数を使用できます。ロググループ間で JOINs を実行し、サブクエリを使用してログ間でデータを関連付け、一連の豊富な JSON、算術、文字列、条件付きなどの SQL 関数を使用してログに対する強力な分析を実行できます。 SQL コマンドまたは PPL コマンドを使用する場合は、フィールドをバッククォートの特殊文字 (非アルファベットおよび非数値) で囲んでクエリを正常に実行してください。例えば、`@message`、`Operation.Export`、`Test::Field` をバッククォートで囲みます。フィールド名がアルファベットのみの場合はバッククオートで囲む必要はありません。 CloudWatch Logs Insights には、任意のクエリ言語で使用できる以下の機能があります。 + Amazon Route 53、、Amazon VPC などのサービスからの AWS ログの[*ログフィールド、およびログイベントを JSON として出力するアプリケーションまたはカスタムログの自動検出*](CWL_AnalyzeLogData-discoverable-fields.md)。 AWS Lambda AWS CloudTrail + [*フィールドインデックス*](CloudWatchLogs-Field-Indexing.md)を作成してコストを削減し、特に多数のロググループまたはログイベントのクエリで結果を高速化。ログイベントで一般的なフィールドのフィールドインデックスを作成したら、クエリでこれらを使用できます。このクエリは、インデックス付きフィールドが含まれていないことがわかっているログイベントの処理をスキップし、データ処理量を抑制します。 **注記** `filterIndex` コマンドは Logs Insights QL でのみ使用できます。 + ログイベントの[*パターンの検出と分析*](CWL_AnalyzeLogData_Patterns.md)。パターンは、ログフィールド間で繰り返される共有テキスト構造です。クエリの結果を表示するときは、**[パターン]**タブを選択して、結果のサンプルに基づいて CloudWatch Logs が検出したパターンを表示できます。 + [*クエリの保存*](CWL_Insights-Saving-Queries.md)、クエリ履歴の表示、保存されたクエリの再実行、[パラメータを使用した保存されたクエリの使用](CWL_Insights-Saving-Queries.md#CWL_Insights-Parameterized-Queries)。 + [*ダッシュボードへのクエリの追加*](CWL_ExportQueryResults.md)。 + [*によるクエリ結果の暗号化 AWS Key Management Service*](CloudWatchLogs-Insights-Query-Encrypt.md)。 + [自然言語を使用したクエリ生成](CloudWatchLogs-Insights-Query-Assist.md)により、自然言語を使用して CloudWatch Logs Insights クエリを作成できます。探しているデータについて質問あるいは説明すると、AI はそのプロンプトに基づいてクエリを生成し、そのクエリの仕組みを詳しく説明します。 + [ファセットを使用して、ログをグループ化、フィルタリング、インタラクティブに探索します](CloudWatchLogs-Facets.md)。 以下の CloudWatch Logs Insights 機能は、Logs Insights QL を使用する場合にのみサポートされます。 + ロググループのログイベントと以前の期間のログイベントを比較する[比較クエリ](CWL_AnalyzeLogData_Compare.md)。 **重要** CloudWatch Logs Insights は、ロググループの作成時刻より前のタイムスタンプを持つログイベントにはアクセスすることができません。 CloudWatch のクロスアカウントオブザーバビリティでモニタリングアカウントとして設定されたアカウントにサインインしている場合、このモニタリングアカウントにリンクされているソースアカウントのロググループで CloudWatch Logs Insights クエリを実行できます。異なるアカウントにある複数のロググループをクエリするクエリを実行できます。詳細については、「[CloudWatch のクロスアカウントオブザーバビリティ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html)」を参照してください。 また、Logs Insights QL を使用してクエリを作成する場合は、自然言語を使用して CloudWatch Logs Insights クエリを作成することもできます。そのためには、どのようなデータを探しているのかを質問したり、具体的に説明したりしてみてください。AI 支援機能が働いて、プロンプトに基づいてクエリが生成され、クエリの仕組みを説明した文が 1 行ずつ表示されます。詳細については、「[Use natural language to generate and update CloudWatch Logs Insights queries](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogs-Insights-Query-Assist.html)」を参照してください。 サポートされているクエリ言語のいずれかを使用したクエリは、完了していない場合、60 分後にタイムアウトします。クエリ結果は 7 日間利用できます。 CloudWatch Logs Insights クエリでは、クエリ言語に関係なく、クエリされたデータの量に基づいて料金が発生します。詳細については、「[Amazon CloudWatch 料金表](https://aws.amazon.com/cloudwatch/pricing/)」をご覧ください。 CloudWatch Logs Insights を使用して、2018 年 11 月 5 日以降に CloudWatch Logs に送信されたログデータを検索できます。 **重要** ネットワークセキュリティチームがウェブソケットの使用を許可しない場合は、現在 CloudWatch コンソールの CloudWatch Logs Insights 部分にアクセスすることはできません。API を使用して CloudWatch Logs Insights のクエリ機能を使用できます。詳細については、*Amazon CloudWatch Logs API リファレンス*の「[StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html)」を参照してください。 **Topics** + [サポートされているクエリ言語](CWL_AnalyzeLogData_Languages.md) + [自然言語を使用した CloudWatch Logs Insights クエリの生成と更新](CloudWatchLogs-Insights-Query-Assist.md) + [サポートされるログと検出されるフィールド](CWL_AnalyzeLogData-discoverable-fields.md) + [フィールドインデックスを作成してクエリパフォーマンスを改善し、スキャン量を削減する](CloudWatchLogs-Field-Indexing.md) + [ファセットを使用してログをグループ化および探索する](CloudWatchLogs-Facets.md) + [パターン分析](CWL_AnalyzeLogData_Patterns.md) + [CloudWatch Logs Insights クエリの保存と再実行](CWL_Insights-Saving-Queries.md) + [クエリをダッシュボードに追加する、またはクエリ結果をエクスポートする](CWL_ExportQueryResults.md) + [実行中のクエリまたはクエリ履歴を表示する](CloudWatchLogs-Insights-Query-History.md) + [でクエリ結果を暗号化する AWS Key Management Service](CloudWatchLogs-Insights-Query-Encrypt.md) + [CloudWatch Logs Insights クエリ結果から自然言語の概要を生成する](CloudWatchLogs-Insights-Query-Results-Summary.md) # サポートされているクエリ言語 以下のセクションでは、各クエリ言語でサポートされるコマンドがリストアップされています。また、構文形式の説明とサンプルクエリも提供されています。 **Topics** + [CloudWatch Logs Insights クエリ言語 (Logs Insights QL)](CWL_AnalyzeLogData_LogsInsights.md) + [OpenSearch パイプ処理言語 (PPL)](CWL_AnalyzeLogData_PPL.md) + [OpenSearch 構造化クエリ言語 (SQL)](CWL_AnalyzeLogData_SQL.md) # CloudWatch Logs Insights クエリ言語 (Logs Insights QL) このセクションには、Logs Insights QL のコマンドと関数の完全なドキュメントが含まれています。また、この言語のサンプルクエリも含まれています。 使用できる他のクエリ言語について詳しくは、「[OpenSearch Service PPL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_PPL.html)」、「[OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html)」、「[CloudWatch Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)」を参照してください。 **Topics** + [CloudWatch Logs Insights 言語のクエリ構文](CWL_QuerySyntax.md) + [Logs Insights QL の使用を開始する: クエリチュートリアル](CWL_AnalyzeLogData_Tutorials.md) + [サンプルクエリ](CWL_QuerySyntax-examples.md) + [(diff) を以前の時間範囲と比較する](CWL_AnalyzeLogData_Compare.md) + [グラフでログデータを視覚化する](CWL_Insights-Visualizing-Log-Data.md) # 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 ``` # Logs Insights QL の使用を開始する: クエリチュートリアル 以下のセクションでは、Logs Insights QL の使用を開始する際に役立つサンプルのクエリのチュートリアルをご覧いただけます。 **Topics** + [チュートリアル: サンプルクエリを実行および変更する](CWL_AnalyzeLogData_RunSampleQuery.md) + [チュートリアル: 集計関数を使用してクエリを実行する](CWL_AnalyzeLogData_AggregationQuery.md) + [チュートリアル: ログフィールド別にグループ化された視覚化を生成するクエリを実行する](CWL_AnalyzeLogData_VisualizationFieldQuery.md) + [チュートリアル: 時系列の視覚化を生成するクエリを実行する](CWL_AnalyzeLogData_VisualizationQuery.md) # チュートリアル: サンプルクエリを実行および変更する 以下のチュートリアル通りに、CloudWatch Logs Insights の使用を開始できます。Logs Insights QL のサンプルクエリを実行し、次にこのクエリを変更して再実行する方法を示します。 クエリを実行するには、CloudWatch Logs に保存済みのログが必要です。CloudWatch Logs をすでに使用していて、ロググループとログストリームが設定済みである場合は、開始する準備が整っています。また、 AWS CloudTrail、Amazon Route 53、または Amazon VPC などのサービスを使用し、それらのサービスから CloudWatch Logs に移動するようにログを設定している場合は、既にログが存在する可能性があります。CloudWatch Logs にログを送信する方法の詳細については、「[CloudWatch Logs の開始方法](CWL_GettingStarted.md)」を参照してください。 CloudWatch Logs Insights のクエリは、ログイベントから一連のフィールドを返すか、ログイベントに対して実行された数学的な集約やその他のオペレーションの結果を返します。このチュートリアルでは、ログイベントのリストを返すクエリを示します。 ## サンプルクエリを実行する **CloudWatch Logs Insights サンプルクエリを実行するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。 **[Logs Insights]** (ログのインサイト) ページでは、Logs Insights QL のクエリエディタにデフォルトクエリが表示されます。デフォルトでは、最新の 20 件のログイベントが返されます。 1. **[Select log group]** (ロググループの選択) ドロップダウンから、クエリを実行するロググループを 1 つ以上選択します。 これが CloudWatch のクロスアカウントオブザーバビリティのモニタリングアカウントの場合は、モニタリングアカウントだけでなくソースアカウントのロググループも選択できます。1 つのクエリで複数のアカウントのログを一度にクエリできます。 ロググループは、ロググループ名、アカウント ID、またはアカウントラベルでフィルタリングできます。 標準ログクラスのロググループを選択すると、CloudWatch Logs Insights はグループ内のデータフィールドを自動的に検出します。検出されたフィールドを表示するには、ページの右上あたりにある **[Fields]** (フィールド) メニューを選択します。 **注記** 検出されたフィールドは、標準ログクラスのロググループでのみサポートされます。ログクラスの詳細については、「[ログクラス](CloudWatch_Logs_Log_Classes.md)」を参照してください。 1. (オプション) 時間間隔セレクタを使用して、クエリを実行する期間を選択します。 5～30 分間隔、1 時間、3 時間、12 時間間隔、またはカスタム時間枠を選択できます。 1. **[Run]** (実行) を選択して結果を表示します。 このチュートリアルでは、最近追加されたログイベントが 20 件表示されます。 また、CloudWatch Logs は、このロググループのログイベントを時間の経過に従って棒グラフで表示します。この棒グラフは、表に示されるイベントだけでなく、クエリと時間範囲に一致するロググループ内のイベントの分布も示します。 1. 返されたログイベントのすべてのフィールドを表示するには、番号付きイベントの左にある三角形のドロップダウンアイコンを選択します。 ## サンプルクエリを変更する このチュートリアルでは、サンプルクエリを変更して、最新のログイベントを 50 件表示します。 前のチュートリアルをまだ実行していない場合は、今すぐ実行してください。このチュートリアルは、前のチュートリアルが終了した箇所から開始します。 **注記** CloudWatch Logs Insights に用意されている一部のサンプルクエリでは、`limit` の代わりに `head` または `tail` コマンドを使用します。これらのコマンドは非推奨であり、`limit` に置き換えられています。ユーザーが記述するすべてのクエリで、`limit` または `head` の代わりに `tail` を使用します。 **CloudWatch Logs Insights のサンプルクエリを変更するには** 1. クエリエディタで、**20** を **50** に変更し、[**実行**] を選択します。 新しいクエリの結果が表示されます。デフォルトの時間範囲でロググループに十分なデータがあるとして、これで 50 件のログイベントが一覧表示されます。 1. (オプション) 作成したクエリは保存できます。このクエリを保存するには、[**保存**] を選択します。詳細については、「[CloudWatch Logs Insights クエリの保存と再実行](CWL_Insights-Saving-Queries.md)」を参照してください。 ## サンプルクエリにフィルターコマンドを追加する このチュートリアルでは、クエリエディタを使用してクエリに対してより強力な変更を行う方法を示します。このチュートリアルでは、取得したログイベントのフィールドに基づいて、前のクエリの結果をフィルタリングします。 前のチュートリアルをまだ実行していない場合は、今すぐ実行してください。このチュートリアルは、前のチュートリアルが終了した箇所から開始します。 **前のクエリにフィルターコマンドを追加するには** 1. フィルタリングするフィールドを決定します。過去 15 分間に選択したロググループに含まれるログイベントで CloudWatch Logs により検出された最も一般的なフィールドと、各フィールドが出現するログイベントの割合を確認するには、ページの右側にある [**Fields (フィールド)**] を選択します。 特定のログイベントに含まれているフィールドを表示するには、その行の左にあるアイコンを選択します。 ログ内のイベントに応じて、ログイベントに [**awsRegion**] フィールドが表示される場合があります。このチュートリアルの残りの部分では、フィルターフィールドとして [**awsRegion**] を使用しますが、このフィールドが使用できない場合は、別のフィールドを使用できます。 1. クエリエディタボックスで [**50**] の後にカーソルを置き、Enter キーを押します。 1. 新しい行で、最初に \$1 (パイプ文字) とスペースを入力します。CloudWatch Logs Insights クエリのコマンドは、パイプ文字で区切る必要があります。 1. **filter awsRegion="us-east-1"** と入力します。 1. [**Run (実行)**] を選択します。 クエリが再度実行されます。今回は、新しいフィルターに一致する 50 件の最新の結果が表示されます。 別のフィールドにフィルターを適用してエラーが発生した場合は、必要に応じてフィールド名をエスケープします。フィールド名に英数字以外の文字が含まれている場合は、フィールド名の前後にバッククォート文字 (`) を挿入します (例: **`error-code`="102"**)。 英数字以外の文字を含むフィールド名にはバッククォート文字を使用する必要がありますが、値には必要ありません。値は常に引用符 (") で囲まれます。 Logs Insights QL には、強力なクエリ機能として、複数の正規表現のコマンドとサポート、算術演算、統計演算などが含まれています。詳細については、「[CloudWatch Logs Insights 言語のクエリ構文](CWL_QuerySyntax.md)」を参照してください。 # チュートリアル: 集計関数を使用してクエリを実行する 集約関数は、`stats` コマンドで使用できます。また、他の関数の引数としても使用できます。このチュートリアルでは、指定したフィールドを含むログイベントの数をカウントするクエリコマンドを実行します。このクエリコマンドは、指定したフィールドの値でグループ化された合計数を返します。集計関数の詳細については、「Amazon CloudWatch Logs ユーザーガイド**」の「[サポートされているオペレーションと関数](https://docs.aws.amazon.com/en_us/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html#CWL_QuerySyntax-operations-functions)」を参照してください。 **集計関数を使用したクエリの実行方法** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。 1. **Logs Insights QL** タブが選択されていることを確認します。 1. **[Select log group]** (ロググループの選択) ドロップダウンから、クエリを実行するロググループを 1 つ以上選択します。 これが CloudWatch のクロスアカウントオブザーバビリティのモニタリングアカウントの場合は、モニタリングアカウントだけでなくソースアカウントのロググループも選択できます。1 つのクエリで複数のアカウントのログを一度にクエリできます。 ロググループは、ロググループ名、アカウント ID、またはアカウントラベルでフィルタリングできます。 ロググループを選択すると、標準クラスロググループの場合 CloudWatch Logs Insights はロググループ内のデータフィールドを自動的に検出します。検出されたフィールドを表示するには、ページの右上あたりにある **[Fields]** (フィールド) メニューを選択します。 1. クエリエディタでデフォルトのクエリを削除し、次のコマンドを入力します。 ``` stats count(*) by fieldName ``` 1. *fieldName* を **[Fields]** (フィールド) メニューから検出されたフィールドに置換します。 **[Fields]** (フィールド) メニューはページの右上にあり、CloudWatch Logs Insights がロググループ内で検出したすべての検出フィールドがそこに表示されます。 1. **[Run]** (実行) を選択してクエリの結果を表示します。 クエリの結果には、クエリコマンドに一致するロググループ内のレコード数と、指定したフィールドの値でグループ化された合計数が表示されます。 # チュートリアル: ログフィールド別にグループ化された視覚化を生成するクエリを実行する `stats` 関数を使用するクエリを実行して、返された値をログエントリ内の 1 つ以上のフィールドの値別にグループ化すると、結果を棒グラフ、円グラフ、折れ線グラフ、積み上げ面グラフとして表示できます。これにより、ログの傾向をより効率的に視覚化できます。 **視覚化用のクエリを実行するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。 1. **[Select log group]** (ロググループの選択) ドロップダウンから、クエリを実行するロググループを 1 つ以上選択します。 これが CloudWatch のクロスアカウントオブザーバビリティのモニタリングアカウントの場合は、モニタリングアカウントだけでなくソースアカウントのロググループも選択できます。1 つのクエリで複数のアカウントのログを一度にクエリできます。 ロググループは、ロググループ名、アカウント ID、またはアカウントラベルでフィルタリングできます。 1. クエリエディタで、現在の表示内容を削除し、以下の `stats` 関数を入力して、[**クエリの実行**] を選択します。 ``` stats count(*) by @logStream | limit 100 ``` 結果には、各ログストリームのロググループ内のログイベント数が表示されます。結果は 100 行に制限されます。 1. [**Visualization (視覚化)**] タブを選択します。 1. [**線**] の横にある矢印を選択し、[**バー**] を選択します。 棒グラフが表示され、ロググループ内のログストリームごとに棒が表示されます。 # チュートリアル: 時系列の視覚化を生成するクエリを実行する `bin()` 関数を使用するクエリを実行して、返された値を期間別にグループ化すると、結果を折れ線グラフ、積み上げ面グラフ、円グラフ、棒グラフとして表示できます。これにより、時間の経過に伴うログイベントの傾向をより効率的に視覚化できます。 **視覚化用のクエリを実行するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。 1. **Logs Insights QL** タブが選択されていることを確認します。 1. **[Select log group]** (ロググループの選択) ドロップダウンから、クエリを実行するロググループを 1 つ以上選択します。 これが CloudWatch のクロスアカウントオブザーバビリティのモニタリングアカウントの場合は、モニタリングアカウントだけでなくソースアカウントのロググループも選択できます。1 つのクエリで複数のアカウントのログを一度にクエリできます。 ロググループは、ロググループ名、アカウント ID、またはアカウントラベルでフィルタリングできます。 1. クエリエディタで、現在の表示内容を削除し、以下の `stats` 関数を入力して、[**クエリの実行**] を選択します。 ``` stats count(*) by bin(30s) ``` 結果として、CloudWatch Logs が 30 秒間隔で受信したロググループ内のログイベントの数が表示されます。 1. [**Visualization (視覚化)**] タブを選択します。 結果が折れ線グラフとして表示されます。棒グラフ、円グラフ、積み上げ面グラフに切り替えるには、グラフの右上で [**Line (線)**] を選択します。 # サンプルクエリ このセクションでは、[CloudWatch コンソール](https://console.aws.amazon.com/cloudwatch/)で実行できる一般的で便利なクエリコマンドの一覧を紹介します。クエリコマンドの実行方法については、「Amazon CloudWatch Logs ユーザーガイド**」の「[チュートリアル: サンプルクエリを実行および変更する](https://docs.aws.amazon.com/en_us/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_RunSampleQuery.html)」を参照してください。 クエリ構文の詳細については、「[CloudWatch Logs Insights 言語のクエリ構文](CWL_QuerySyntax.md)」を参照してください。 **Topics** + [一般的なクエリ](#CWL_QuerySyntax-examples-general) + [Lambda ログのクエリ](#CWL_QuerySyntax-examples-Lambda) + [Amazon VPC フローログのクエリ](#CWL_QuerySyntax-examples-VPC) + [Route 53 ログのクエリ](#CWL_QuerySyntax-examples-Route53) + [CloudTrail ログのクエリ](#CWL_QuerySyntax-examples-CloudTrail) + [のクエリ Amazon API Gateway](#CWL_QuerySyntax-examples-APIGateway) + [NAT ゲートウェイに対するクエリ](#CWL_QuerySyntax-examples-NATGateway) + [Apache サーバーのログに対するクエリ](#CWL_QuerySyntax-examples-Apache) + [Amazon EventBridge のクエリ](#CWL_QuerySyntax-examples-EventBridge) + [解析コマンドの例](#CWL_QuerySyntax-examples-parse) ## 一般的なクエリ **最近追加された 25 件のログイベントを検索します。** ``` fields @timestamp, @message | sort @timestamp desc | limit 25 ``` **1 時間あたりの例外数のリストを表示します。** ``` filter @message like /Exception/ | stats count(*) as exceptionCount by bin(1h) | sort exceptionCount desc ``` **例外ではないログイベントのリストを取得します。** ``` fields @message | filter @message not like /Exception/ ``` **`server` フィールドの一意の値ごとに最新のログイベントを表示します。** ``` fields @timestamp, server, severity, message | sort @timestamp asc | dedup server ``` **各 `severity` タイプの、`server` フィールドの一意の値ごとに最新のログイベントを表示します。** ``` fields @timestamp, server, severity, message | sort @timestamp desc | dedup server, severity ``` ## Lambda ログのクエリ **過剰にプロビジョニングされたメモリの量を確認します。** ``` filter @type = "REPORT" | stats max(@memorySize / 1000 / 1000) as provisonedMemoryMB, min(@maxMemoryUsed / 1000 / 1000) as smallestMemoryRequestMB, avg(@maxMemoryUsed / 1000 / 1000) as avgMemoryUsedMB, max(@maxMemoryUsed / 1000 / 1000) as maxMemoryUsedMB, provisonedMemoryMB - maxMemoryUsedMB as overProvisionedMB ``` **レイテンシーレポートを作成します。** ``` filter @type = "REPORT" | stats avg(@duration), max(@duration), min(@duration) by bin(5m) ``` **遅い関数呼び出しを検索し、再試行やクライアント側コードが原因で発生する可能性のある重複リクエストを削除します。このクエリでは、`@duration` はミリ秒単位です。** ``` fields @timestamp, @requestId, @message, @logStream | filter @type = "REPORT" and @duration > 1000 | sort @timestamp desc | dedup @requestId | limit 20 ``` ## Amazon VPC フローログのクエリ **ホスト間での上位 15 件のパケット転送を検索します:** ``` stats sum(packets) as packetsTransferred by srcAddr, dstAddr | sort packetsTransferred desc | limit 15 ``` **特定のサブネットにおけるホストの上位 15 バイトの転送を検索します。** ``` filter isIpv4InSubnet(srcAddr, "192.0.2.0/24") | stats sum(bytes) as bytesTransferred by dstAddr | sort bytesTransferred desc | limit 15 ``` **データ転送プロトコルとして UDP を使用する IP アドレスを検索します。** ``` filter protocol=17 | stats count(*) by srcAddr ``` **キャプチャウィンドウでフローレコードがスキップされた IP アドレスを検索します。** ``` filter logStatus="SKIPDATA" | stats count(*) by bin(1h) as t | sort t ``` **接続のたびに 1 つのレコードを検索し、ネットワークの接続問題の解決を促します。** ``` fields @timestamp, srcAddr, dstAddr, srcPort, dstPort, protocol, bytes | filter logStream = 'vpc-flow-logs' and interfaceId = 'eni-0123456789abcdef0' | sort @timestamp desc | dedup srcAddr, dstAddr, srcPort, dstPort, protocol | limit 20 ``` ## Route 53 ログのクエリ **クエリタイプ別に 1 時間あたりのレコードのディストリビューションを検索します。** ``` stats count(*) by queryType, bin(1h) ``` **リクエスト数が最大である 10 件の DNS リゾルバーを検索します。** ``` stats count(*) as numRequests by resolverIp | sort numRequests desc | limit 10 ``` **サーバーが DNS リクエストを完了できなかったレコード数をドメイン別およびサブドメイン別に検索します。** ``` filter responseCode="SERVFAIL" | stats count(*) by queryName ``` ## CloudTrail ログのクエリ **各サービス、イベントタイプ、 AWS リージョンのログエントリの数を検索します。** ``` stats count(*) by eventSource, eventName, awsRegion ``` **特定の AWS リージョンで開始または停止された Amazon EC2 ホストを検索します。** ``` filter (eventName="StartInstances" or eventName="StopInstances") and awsRegion="us-east-2" ``` **新しく作成した IAM ユーザーの AWS リージョン、ユーザー名、ARNs を検索します。** ``` filter eventName="CreateUser" | fields awsRegion, requestParameters.userName, responseElements.user.arn ``` **API `UpdateTrail` の呼び出し中に例外が発生したレコードの数を検索します。** ``` filter eventName="UpdateTrail" and ispresent(errorCode) | stats count(*) by errorCode, errorMessage ``` **TLS 1.0 または 1.1 が使用されたログエントリを検索します。** ``` filter tlsDetails.tlsVersion in [ "TLSv1", "TLSv1.1" ] | stats count(*) as numOutdatedTlsCalls by userIdentity.accountId, recipientAccountId, eventSource, eventName, awsRegion, tlsDetails.tlsVersion, tlsDetails.cipherSuite, userAgent | sort eventSource, eventName, awsRegion, tlsDetails.tlsVersion ``` **TLS バージョン 1.0 または 1.1 を使用したサービスごとの呼び出し数を検索します。** ``` filter tlsDetails.tlsVersion in [ "TLSv1", "TLSv1.1" ] | stats count(*) as numOutdatedTlsCalls by eventSource | sort numOutdatedTlsCalls desc ``` ## のクエリ Amazon API Gateway 最新の 4XX エラーを 10 件検索します。 ``` fields @timestamp, status, ip, path, httpMethod | filter status>=400 and status<=499 | sort @timestamp desc | limit 10 ``` Amazon API Gateway アクセスロググループ内で最も長く実行されている 10 個の Amazon API Gateway リクエストを特定する ``` fields @timestamp, status, ip, path, httpMethod, responseLatency | sort responseLatency desc | limit 10 ``` Amazon API Gateway  アクセスロググループで最もよく使用されている API パスのリストを返します。 ``` stats count(*) as requestCount by path | sort requestCount desc | limit 10 ``` Amazon API Gateway  アクセスロググループの統合レイテンシーレポートを作成します。 ``` filter status=200 | stats avg(integrationLatency), max(integrationLatency), min(integrationLatency) by bin(1m) ``` ## NAT ゲートウェイに対するクエリ AWS 請求額が通常よりも高い場合は、CloudWatch Logs Insights を使用して上位の寄与要因を見つけることができます。以下のクエリコマンドの詳細については、 AWS プレミアムサポートページの[「VPC の NAT ゲートウェイ経由のトラフィックの上位寄与要因を見つけるにはどうすればよいですか?](https://aws.amazon.com/premiumsupport/knowledge-center/vpc-find-traffic-sources-nat-gateway/)」を参照してください。 **注記** 次のクエリコマンドの「x.x.x.x」の部分をお使いの NAT ゲートウェイのプライベート IP に置き換え、「y.y」を VPC CIDR アドレス範囲の第 1 および 第 2 オクテットの値に置き換えます。 **NAT ゲートウェイ経由で最も多くのトラフィックを送信しているインスタンスを検索します。** ``` filter (dstAddr like 'x.x.x.x' and srcAddr like 'y.y.') | stats sum(bytes) as bytesTransferred by srcAddr, dstAddr | sort bytesTransferred desc | limit 10 ``` **NAT ゲートウェイ内のインスタンスとの間で送受信されているトラフィックを特定します。** ``` filter (dstAddr like 'x.x.x.x' and srcAddr like 'y.y.') or (srcAddr like 'xxx.xx.xx.xx' and dstAddr like 'y.y.') | stats sum(bytes) as bytesTransferred by srcAddr, dstAddr | sort bytesTransferred desc | limit 10 ``` **VPC 内のインスタンスがアップロードとダウンロードの通信で最も頻繁に使用している、インターネット上の送信先を特定します。** *****アップロードの場合***** ``` filter (srcAddr like 'x.x.x.x' and dstAddr not like 'y.y.') | stats sum(bytes) as bytesTransferred by srcAddr, dstAddr | sort bytesTransferred desc | limit 10 ``` *****ダウンロードの場合***** ``` filter (dstAddr like 'x.x.x.x' and srcAddr not like 'y.y.') | stats sum(bytes) as bytesTransferred by srcAddr, dstAddr | sort bytesTransferred desc | limit 10 ``` ## Apache サーバーのログに対するクエリ CloudWatch Logs Insights では Apache サーバーのログにクエリできます。以下のクエリの詳細については、 クラウド AWS オペレーションと移行ブログの「[CloudWatch Logs Insights を使用した Apache サーバーログの簡素化](https://aws.amazon.com/blogs/mt/simplifying-apache-server-logs-with-amazon-cloudwatch-logs-insights/)」を参照してください。 **アクセスログを確認してアプリケーションの */admin* パスでトラフィックをチェックできるよう、最も関連性の高いフィールドを検索します。** ``` fields @timestamp, remoteIP, request, status, filename| sort @timestamp desc | filter filename="/var/www/html/admin" | limit 20 ``` **メインページにアクセスした際のステータスコードが「200」(成功) になっている箇所を探し、一意の GET リクエストの数を見つけます。** ``` fields @timestamp, remoteIP, method, status | filter status="200" and referrer= http://34.250.27.141/ and method= "GET" | stats count_distinct(remoteIP) as UniqueVisits | limit 10 ``` **Apache サービスが再起動した回数を確認します。** ``` fields @timestamp, function, process, message | filter message like "resuming normal operations" | sort @timestamp desc | limit 20 ``` ## Amazon EventBridge のクエリ イベント詳細タイプ別にグループ化された EventBridge イベントの数を取得します。 ``` fields @timestamp, @message | stats count(*) as numberOfEvents by `detail-type` | sort numberOfEvents desc ``` ## 解析コマンドの例 **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 ``` # (diff) を以前の時間範囲と比較する CloudWatch Logs Insights と Logs Insights QL を併用し、ログイベントの変化を経時的に比較できます。最近の時間範囲に取り込まれたログイベントと、直前の期間のログを比較できます。または、同様の過去の期間と比較することもできます。これにより、ログ内のエラーが最近発生したものか、または既に発生していたかを調べることができ、他の傾向を見つけやすくなります。 比較クエリは、未加工のログイベントではなく、結果のパターンのみを返します。返されるパターンを基に、ログイベントの傾向と経時的な変化をすばやく確認できるようになります。比較クエリを実行してパターン結果を取得したら、関心のあるパターンの raw ログイベントのサンプルを確認できます。ログパターンの詳細については、「[パターン分析](CWL_AnalyzeLogData_Patterns.md)」を参照してください。 比較クエリを実行すると、選択した元のクエリ期間と比較期間の 2 つの異なる期間に対してクエリが分析されます。比較期間は、常に元のクエリ期間と同じ長さです。比較のデフォルトの時間間隔は次のとおりです。 + **前の期間** — クエリ期間の直前の期間と比較します。 + **前日** — クエリ期間の 1 日前の期間と比較します。 + **前週** — クエリ期間の 1 週間前の期間と比較します。 + **前月** — クエリ期間の 1 か月前の期間と比較します。 **注記** 比較を使用したクエリでは、組み合わせた時間範囲で単一の CloudWatch Logs Insights クエリを実行する場合と同様の料金が発生します。詳細については、「[Amazon CloudWatch 料金表](https://aws.amazon.com/cloudwatch/pricing/)」をご覧ください。 **比較クエリを実行するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[ログ]**、**[Logs Insights]** を選択します。 デフォルトのクエリがクエリボックスに表示されます。 1. **Logs Insights QL** タブが選択されていることを確認します。 1. デフォルトのクエリを保持するか、別のクエリを入力します。 1. **[ロググループを選択]** ドロップダウンから、クエリを実行するロググループを 1 つ以上選択します。 1. (オプション) 時間間隔セレクタを使用して、クエリを実行する期間を選択します。デフォルトのクエリは、過去 1 時間のログデータです。 1. 時間範囲セレクタで、**[比較]** を選択します。次に、元のログと比較する前の期間を選択し、**[適用]** を選択します。 1. **[Run query]** (クエリの実行) を選択します。 クエリが比較期間からデータを取得できるようにするため、`diff` コマンドがクエリに追加されます。 1. **[パターン]** タブを選択して結果を表示します。 テーブルに表示される情報は、次のとおりです。 + 各 **[パターン]** では、パターンの可変部分が動的トークン記号 `` に置き換えられます。*文字列*は、トークンが表すデータのタイプの説明です。*数値*は、他の動的トークンと比較して、このトークンがパターン内のどこに表示されるかを示します。詳細については、「[パターン分析](CWL_AnalyzeLogData_Patterns.md)」を参照してください。 + **[イベント数]** は、元のより最新の期間にそのパターンを持つログイベントの数です。 + **[イベント数の差異]** は、現在の期間と比較期間の一致するログイベントの数の差です。正の違いは、現在の期間にこのようなイベントが多いことを意味します。 + **[差異の説明]** は、現在の期間と比較期間の間のパターンの変化を簡単に要約します。 + **[重要度タイプ]** は、`FATAL`、`ERROR`、`WARN` などのログイベントで検出された単語に基づいて、このパターンを持つログイベントの推定重要度です。 1. リスト内のパターンの 1 つをさらに検査するには、**[検査]** 列の アイコンを選択してパターンの 1 つを選択します。 **[パターン検査]** ペインが表示され、以下が表示されます。 + **[パターン]**。パターン内のトークンを選択して、そのトークンの値を分析します。 + クエリされた時間範囲におけるパターンの出現回数を示すヒストグラム。これにより、パターンの発生の急増など、興味深い傾向を特定できます。 + **[ログサンプル]** タブには、選択したパターンに一致するログイベントがいくつか表示されます。 + **[トークンの値]** タブには、選択している場合は、選択した動的トークンの値が表示されます。 **注記** トークンごとに最大 10 個のトークン値がキャプチャされます。トークン数は正確ではない可能性があります。CloudWatch Logs は確率カウンターを使用して、絶対値ではなくトークン数を生成します。 + **[関連パターン]** タブには、検査するパターンとほぼ同じ時間に頻繁に発生した他のパターンが表示されます。例えば、`ERROR` メッセージのパターンに通常、追加の詳細を含む `INFO` とマークされた別のログイベントが伴っていた場合、そのパターンがここに表示されます。 # グラフでログデータを視覚化する 棒グラフ、折れ線グラフ、積層型面グラフなどの視覚化を使用して、ログデータのパターンをより効率的に識別できます。CloudWatch Logs Insights は、`stats` 関数と 1 つ以上の集計関数を使用するクエリの視覚化を生成します。詳細については、「[stats](CWL_QuerySyntax-Stats.md)」を参照してください。 # OpenSearch パイプ処理言語 (PPL) このセクションでは、OpenSearch PPL を使用した CloudWatch Logs のクエリの基本的な概要を示します。PPL を使用すると、パイプ集計コマンドを使用してデータを取得、クエリ、分析できるため、複雑なクエリの理解と作成が容易になります。この構文は Unix パイプに基づいており、コマンドを連鎖してデータの変換と処理を行えます。PPL を使用すると、データをフィルターして集計し、豊富な一連の算術、文字列、日付、条件付きなどの関数を用いて分析できます。 PPL クエリ`SOURCE`に を含めることは、ロググループのフィールドインデックスと、 AWS CLI または API を使用してクエリを作成するときにクエリに含めるデータソースを指定するのに役立ちます。`SOURCE` コマンドは、CloudWatch コンソールではなく、 AWS CLI および API でのみサポートされます。CloudWatch コンソールを使用してクエリを開始するときは、コンソールインターフェイスを使用してロググループとデータソースの名前とタイプを指定します。 `aws:fieldIndex` を使用してインデックス付きデータのみを返すには、クエリで指定したフィールドでインデックス付けされたロググループのみをスキャンするようクエリに強制します。関連するロググループは、 `filterIndex` コマンドで指定されたフィールドに基づいて自動的に選択されます。これにより、クエリで指定された フィールドを含むログイベントを持たないロググループをスキップし、このフィールドインデックスのクエリで指定された値と一致するロググループのみをスキャンすることで、スキャンされたボリュームが減少します。`aws:fieldIndex` を使用して、ソースコマンドのフィールド名と値とともにフィールド名を指定し、指定されたフィールドと値を含むインデックス付きデータのみをクエリします。詳細については、[フィールドインデックスを作成してクエリパフォーマンスを改善し、スキャン量を削減する](CloudWatchLogs-Field-Indexing.md)を参照してください。 OpenSearch PPL は、標準ログクラスのロググループのクエリに使用できます。 **注記** CloudWatch Logs でサポートされているすべての OpenSearch PPL クエリコマンドと構文や制限の詳細については、「OpenSearch Service デベロッパーガイド」の「[サポートされている PPL コマンド](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-ppl.html)」を参照してください。 使用できる他のクエリ言語については、「[CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)」、「[OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html)」、「[CloudWatchMetrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)」を参照してください。 | コマンドまたは関数 | クエリの例 | 説明 | | --- | --- | --- | | fields | `fields field1, field2` | 射影が必要な一連のフィールドを表示します。 | | join | `LEFT JOIN left=l, right=r on l.id = r.id `join_right_lg` \| fields l.field_1, r.field_2` | 2 つのデータセットを結合します。 | | where | `where field1="success" \| where field2 != "i-023fe0a90929d8822" \| fields field3, field4, field5,field6 \| head 1000` | 指定した条件に基づいてデータをフィルタリングします。 | | aws:fieldIndex | `source = [`aws:fieldIndex`="region", `region` = "us-west-2"] \| where status = 200 \| head 10` | クエリで指定したフィールドでインデックスが作成されたロググループのみをスキャンするようにクエリに強制することで、インデックスが作成されたデータのみを返します。 | | stats | `stats count(), count(field1), min(field1), max(field1), avg(field1) by field2 \| head 1000` | 集計と計算を実行します。 | | parse | `parse field1 ".*/(?[^/]+$)" \| where field2 = "requestId" \| fields field1, field2 \| head 1000` | 文字列から正規表現 (regex) パターンを抽出し、抽出されたパターンを表示します。抽出されたパターンはその後、新しいフィールドの作成やデータのフィルタリングに使用できます。 | | sort | `stats count(), count(field1), min(field1) as field1Alias, max(`field1`), avg(`field1`) by field2 \| sort -field1Alias \| head 1000` | 表示された結果をフィールド名でソートします。sort -FieldName を使用して降順でソートします。 | | eval | `eval field2 = field1 * 2 \| fields field1, field2 \| head 20` | フィールドの値を変更または処理し、別のフィールドに保存します。これは、列の数学的変更、列への文字列関数の適用、列への日付関数の適用に役立ちます。 | | rename | `rename field2 as field1 \| fields field1;` | 検索結果の 1 つ以上のフィールドの名前を変更します。 | | head | `fields `@message` \| head 20` | 表示されるクエリ結果を最初の N 行に制限します。 | | top | `top 2 field1 by field2` | フィールドの最も頻度の高い値を検索します。 | | dedup | `dedup field1 \| fields field1, field2, field3` | 指定したフィールドに基づいて重複するエントリを削除します。 | | rare | `rare field1 by field2` | フィールドリスト内のすべてのフィールドの最も頻度の低い値を検索します。 | | subquery | `where field_1 IN [ search source= `subquery_lg` \| fields field_2 ] \| fields id, field_1 ` | PPL ステートメント内でネストされた複雑なクエリを実行します。 | | trendline | `trendline sma(2, field1) as field1Alias` | フィールドの移動平均を計算します。 | | eventStats | `eventstats sum(field1) by field2` | 計算されたサマリー統計を使用してイベントデータを強化します。イベント内の指定されたフィールドを分析し、さまざまな統計測定値を計算し、これらの結果を新しいフィールドとして元の各イベントに追加します。 | | expand | `eval tags_array_string = json_extract(`@message`, '$.tags')\| eval tags_array = json_array(json_extract(tags_string, '$[0]'), json_extract(tags_string, '$[1]'))\| expand tags_array as color_tags` | 複数の値を含むフィールドを別々の行に分割し、指定されたフィールドの値ごとに新しい行を作成します。 | | fillnull | `fields `@timestamp`, error_code, status_code \| fillnull using status_code = "UNKNOWN", error_code = "UNKNOWN"` | null フィールドに指定した値を入力します。1 つ以上のフィールドで使用できます。 | | flatten | `eval metadata_struct = json_object('size', json_extract(metadata_string, '$.size'), 'color', json_extract(metadata_string, '$.color')) \| flatten metadata_struct as (meta_size, meta_color) ` | フィールドをフラット化します。フィールドは `struct` または `array>` のタイプである必要があります。 | | cidrmatch | `where cidrmatch(ip, '2003:db8::/32') \| fields ip ` | 指定された IP アドレスが指定された CIDR 範囲内にあるかどうかを確認します。 | | fieldsummary | `where field1 != 200 \| fieldsummary includefields= field1 nulls=true` | 各フィールドの基本統計 (count、distinct count、min、max、avg、stddev、mean) を計算します。 | | grok | `grok email '.+@%{HOSTNAME:host}' \| fields email, host` | grok パターンでテキストフィールドを解析し、検索結果に結果を追加します。 | | 文字列関数 | `eval field1Len = LENGTH(field1) \| fields field1Len` | PPL クエリ内の文字列およびテキストデータを操作および変換できる PPL の組み込み関数。例えば、大文字と小文字の変換、文字列の組み合わせ、パーツの抽出、テキストのクリーニングなどです。 | | 日付および時刻関数 | `eval newDate = ADDDATE(DATE('2020-08-26'), 1) \| fields newDate ` | PPL クエリで日付とタイムスタンプデータを処理および変換するための組み込み関数。例えば、date\$1add、date\$1format、datediff、date-sub、timestampadd、timestampdiff、current\$1timezone、utc\$1timestamp、current\$1date などです。 | | 条件関数 | `eval field2 = isnull(field1) \| fields field2, field1, field3` | 特定のフィールド条件をチェックし、式を条件付きで評価する組み込み関数。例えば、field1 が null の場合、field2 を返します。 | | 数学関数 | `eval field2 = ACOS(field1) \| fields field1` | PPL クエリで数学的計算と変換を実行するための組み込み関数。例えば、abs (絶対値）、round (四捨五入数値）、sqrt (平方根）、pow (出力計算）、ceil (最も近い整数に切り上げ) などです。 | | 暗号化関数 | `eval crypto = MD5(field)\| head 1000` | 指定されたフィールドのハッシュを計算するには | | JSON 関数 | `eval valid_json = json('[1,2,3,{"f1":1,"f2":[5,6]},4]') \| fields valid_json` | 配列、抽出、検証など、JSON を処理するための組み込み関数。例えば、json\$1object、json\$1array、to\$1json\$1string、json\$1array\$1length、json\$1extract、json\$1keys、json\$1valid などです。 | ## クエリスコープ クエリに SOURCE を含めることは、 AWS CLI または API を使用してクエリを作成するときに、クエリに含めるロググループを指定するのに役立ちます。SOURCE コマンドは、CloudWatch コンソールではなく、 AWS CLI および API でのみサポートされています。CloudWatch コンソールを使用してクエリを開始するときは、コンソールインターフェイスを使用してロググループとデータソースの名前とタイプを指定します。 PPL の source コマンドは、それらを指定する複数の方法をサポートするようになりました。 1. ロググループ 1. フィールドインデックス - 新規 1. データソースとタイプ - 新規 ### ロググループ ロググループのソース選択は、検索する必要がある正確なロググループ (複数可) がわかっている場合に使用できます。 ``` source = [lg:`/aws/lambda/my-function`] | where status = 200 | head 10 ``` ### フィールドインデックス フィールドインデックスベースのソース選択は、インデックスが作成されたフィールドをフィルターがターゲットにする場合、インデックスが付けられたデータのみに結果を制限することで、クエリされるデータの量を減らします。関連するロググループは、 `filterIndex` コマンドで指定されたフィールドに基づいて自動的に選択されます。フィールドインデックスとその作成方法の詳細については、「Create [field indexes to improve query performance and reduce scan volume](CloudWatchLogs-Field-Indexing.md)」を参照してください。 `aws:fieldIndex` を使用してインデックス付きデータのみを返すには、クエリで指定したフィールドでインデックス付けされたロググループのみをスキャンするようクエリに強制します。このフィールドでインデックス付けされるこれらのロググループの場合、インデックス付けされたフィールドのクエリで指定されたフィールドを含む任意のログイベントを持たないロググループをスキップすることで、クエリがさらに最適化されます。さらに、このフィールドインデックスのクエリで指定された値に一致するこれらのロググループのログイベントのみをスキャンしようとすることで、スキャンされるボリュームが減少します。フィールドインデックスとその作成方法の詳細については、「Create field indexes to improve query performance and reduce scan volume」を参照してください。 PPL では、 `aws:fieldIndex` を使用して、インデックスとして扱うキーと値のペアを指定します。構文は次のとおりです。 ``` source = [`aws:fieldIndex`="region", `region` = "us-west-2"] | where status = 200 | head 10 ``` 次のとおりです。 1. ``aws:fieldIndex`="region"` はリージョンをフィールドインデックスとして識別します。 1. 注: = の代わりに、顧客は IN を使用して複数のインデックスを指定できます (以下の例を参照) 1. ``region`="us-west-2"` は、適用するフィルター条件を識別します。 1. 注: = の代わりに、顧客は IN を使用して複数の値を指定できます (以下の例) お客様は次のように複数の fieldIndexes を指定できます。 ``` source = [`aws:fieldIndex` IN ("status", "region"), `status` = 200, `region` IN ("us-west-2", "us-east-1")] | head 10 ``` ### データソースとタイプ データソースとタイプベースのソース選択は、クエリが必要なデータソースを正確に把握している場合に使用できます。このクエリは、指定されたデータソースとタイプを含む 1 つ以上のロググループで実行されます。 ``` source = [ds:`data_source.type`] | where status = 200 | head 10 ``` #### データソースクエリでサポートされる PPL PPL でデータソースをクエリするためのユースケースをサポートするには、動的ソースセレクタ句を使用できます。この構文を使用して、検索コマンドでデータソースを指定することで、データソースをクエリできます。最大 10 個のデータソースを指定できます。 **[Syntax]** (構文) ``` source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`, ...ds:`DataSourcen.Typen`] ``` **クエリの例** ``` search source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`] | fields field1, field2 ``` ### 組み合わされた例 お客様はすべてのソース選択演算子を任意の順序で指定でき、結果は適用されるすべての条件の共通部分になります。 たとえば、/aws/lambda/my-function-1 には、さまざまなインデックスを含む複数のデータソースとタイプが含まれている場合があります。次のクエリが実行されると、返される結果にはソースイベントとタイプ DataSource1.Type1 のイベントのみが含まれ、'status' = 200 の基準に一致します。 ``` search source=[ ds:`DataSource1.Type1`, lg:`/aws/lambda/my-function-1`, `aws:fieldIndex` IN ("status"), `status` = 200 ] ``` ## 制限事項 OpenSearch PPL を使用して CloudWatch Logs Insights でクエリを実行する場合、次の制限が適用されます。 + データソースクエリでは、結合コマンドまたはサブクエリコマンドを使用できません。 # OpenSearch 構造化クエリ言語 (SQL) このセクションでは、OpenSearch SQL を使用した CloudWatch Logs のクエリの基本的な概要を示します。リレーショナルデータベースの使用に慣れている場合は、使い慣れたオプションを提供します。OpenSearch SQL は SQL 機能のサブセットを提供するため、アドホッククエリやデータ分析タスクの実行に適しています。OpenSearch SQL では、SELECT、FROM、WHERE、GROUP BY、HAVING、その他のさまざまな SQL コマンドや関数などのコマンドを使用できます。ロググループ間で JOINs を実行し、サブクエリを使用してロググループ間でデータを関連付け、一連の豊富な JSON、算術、文字列、条件付きなどの SQL 関数を使用してログとセキュリティデータに対する強力な分析を実行できます。 `filterIndex` を使用してインデックス付きデータのみを返すには、クエリで指定したフィールドでインデックス付けされたロググループのみをスキャンするようクエリに強制します。クエリで指定された フィールドを含むログイベントを持たないロググループをスキップし、このフィールドインデックスのクエリで指定された値と一致するロググループのみをスキャンすることで、スキャンされたボリュームを減らします。`filterIndex` を使用して、フィールド名と、指定されたフィールドと値を含むインデックス付きデータのみをクエリするフィールド名と値を指定します。 OpenSearch SQL は、標準ログクラスのロググループのクエリに使用できます。SQL は、データソース名とデータソースタイプを使用したクエリもサポートしています。 **注記** 次の表は、CloudWatch Logs でサポートされている SQL コマンドと関数の一覧です。構文を含むすべての OpenSearch SQL コマンドの詳細については、「OpenSearch Service デベロッパーガイド」の「[サポートされている SQL コマンド](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-directquery-sql.html)」を参照してください。 使用できる他のクエリ言語については、「[CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)」、「[OpenSearch Service PPL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_PPL.html)」、「[CloudWatchMetrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)」を参照してください。 ## サポートされている SQL コマンド **注記** クエリの例の列では、クエリするデータソースに応じて、`` を適宜置き換えます。 | コマンドまたは関数 | クエリの例 | 説明 | | --- | --- | --- | | SELECT | `SELECT `@message`, Operation FROM `LogGroupA`` | 射影された値を表示します。 | | FROM | `SELECT `@message`, Operation FROM `LogGroupA`` | データを取得するソーステーブル (複数可) またはビュー (複数可) を指定する組み込み句。さまざまなタイプの結合とサブクエリをサポートします。 | | WHERE | `SELECT * FROM `LogGroupA` WHERE Operation = 'x'` | 指定されたフィールド基準に基づいてログイベントをフィルタリングします。 | | filterIndex | `SELECT * FROM `filterIndex('region' = 'us-east-1')` WHERE status = 200 LIMIT 10;` | クエリで指定したフィールドでインデックスが作成されたロググループのみをスキャンするようにクエリに強制することで、インデックスが作成されたデータのみを返します。 | | グループ化の条件 | `SELECT `@logStream`, COUNT(*) as log_count FROM `LogGroupA` GROUP BY `@logStream`` | グループはカテゴリに基づいてイベントをログに記録し、統計に基づいて平均を見つけます。 | | HAVING | `SELECT `@logStream`, COUNT(*) as log_count FROM `LogGroupA` GROUP BY `@logStream` HAVING log_count > 100` | グループ化条件に基づいて結果をフィルタリングします。 | | ORDER BY | `SELECT * FROM `LogGroupA` ORDER BY `@timestamp` DESC` | ORDER BY 句のフィールドに基づいて結果が並べ替えられます。昇順または降順のいずれかで並べ替えることができます。 | | JOIN | `SELECT A.`@message`, B.`@timestamp`FROM `LogGroupA` as A INNER JOIN `LogGroupB` as B ON A.`requestId` = B.`requestId`` | 共通フィールドに基づいて 2 つのテーブルの結果を結合します。Inner JOIN または Left Outer Join を指定する必要があります。 | | LIMIT | `Select * from `LogGroupA` limit 10` | 表示されるクエリ結果を最初の N 行に制限します。 | | 文字列関数 | `SELECT upper(Operation) , lower(Operation), Operation FROM `LogGroupA`` | SQL クエリ内の文字列およびテキストデータを操作および変換できる SQL の組み込み関数。例えば、大文字と小文字の変換、文字列の組み合わせ、パーツの抽出、テキストのクリーニングなどです。 | | 日付関数 | `SELECT current_date() as today, date_add(current_date(), 30) as thirty_days_later, last_day(current_date()) as month_end FROM `LogGroupA`` | SQL クエリで日付とタイムスタンプデータを処理および変換するための組み込み関数。例えば、date\$1add、date\$1format、datediff、current\$1date などです。 | | 条件関数 | `SELECT Operation, IF(Error > 0, 'High', 'Low') as error_category FROM `LogGroupA`;` | 指定された条件に基づいてアクションを実行するか、式を条件付きで評価する組み込み関数。例えば、CASE と IF が挙げられます。 | | 集計関数 | `SELECT AVG(bytes) as bytesWritten FROM `LogGroupA`` | 複数の行で計算を実行して 1 つの要約値を生成する組み込み関数。例えば、SUM、COUNT、AVG、MAX、MIN などです。 | | JSON 関数 | `SELECT get_json_object(json_column, '$.name') as name FROM `LogGroupA`` | SQL クエリ (from\$1json、to\$1json、get\$1json\$1object、json\$1tuple など) 内の JSON 形式のデータを解析、抽出、変更、クエリするための組み込み関数。データセット内の JSON 構造を操作できます。 | | 配列関数 | `SELECT scores, size(scores) as length, array_contains(scores, 90) as has_90 FROM `LogGroupA`;` | SQL クエリで配列タイプの列を操作するための組み込み関数。配列データ (サイズ、展開、array\$1contains など) に対するアクセス、変更、分析などの操作を可能にします。 | | Window 関数 | `SELECT field1, field2, RANK() OVER (ORDER BY field2 DESC) as field2Rank FROM `LogGroupA`;` | 現在の行 (ウィンドウ) に関連する指定された行セットで計算を実行する組み込み関数。ランキング、合計実行、移動平均などの操作を有効にします。例えば、ROW\$1NUMBER、RANK、LAG、LEAD などです。 | | 変換関数 | `SELECT CAST('123' AS INT) as converted_number, CAST(123 AS STRING) as converted_string FROM `LogGroupA`` | SQL クエリ内でデータをあるタイプから別のタイプに変換するための組み込み関数。データ型変換と形式変換を可能にします。例えば、CAST、TO\$1DATE、TO\$1TIMESTAMP、BINARY などです。 | | 述語関数 | `SELECT scores, size(scores) as length, array_contains(scores, 90) as has_90 FROM `LogGroupA`;` | 条件を評価し、指定された条件またはパターンに基づいてブール値 (true/false) を返す組み込み関数。例えば、IN、LIKE、BETWEEN、IS NULL、EXISTS などです。 | | 複数のロググループを選択する | `SELECT lg1.field1, lg1.field2 from `logGroups( logGroupIdentifier: ['LogGroup1', 'LogGroup2'])` as lg1 where lg1.field3= "Success"` | SELECT ステートメントで複数のロググループを指定できます。 | | 複数のデータソースを選択する | `SELECT ds1.field1, ds1.field2 from `dataSource(['DataSource1', 'DataSource2'])` as ds1 where ds1.field3= "Success"` | SELECT ステートメントで複数のデータソースを指定できます | ## multi-log-group クエリでサポートされている SQL SQL で複数のロググループをクエリするためのユースケースをサポートするには、`logGroups` コマンドを使用できます。この構文を使用し、FROM コマンドでそれらを指定することで複数のロググループをクエリできます。 構文: ``` `logGroups( logGroupIdentifier: ['LogGroup1','LogGroup2', ...'LogGroupn'] ) ``` この構文では、`logGroupIdentifier` パラメータに最大 50 個のロググループを指定できます。モニタリングアカウントのロググループを参照するには、`LogGroup` の名前の代わりに ARN を使用します。 クエリの例: ``` SELECT LG1.Column1, LG1.Column2 from `logGroups( logGroupIdentifier: ['LogGroup1', 'LogGroup2'] )` as LG1 WHERE LG1.Column1 = 'ABC' ``` `FROM` ステートメントの後に複数のロググループを含む次の構文は、CloudWatch Logs のクエリではサポートされていません。 ``` SELECT Column1, Column2 FROM 'LogGroup1', 'LogGroup2', ...'LogGroupn' WHERE Column1 = 'ABC' ``` ## データソースクエリでサポートされている SQL SQL でデータソースをクエリするためのユースケースをサポートするには、dataSource コマンドを使用できます。この構文を使用して、 `FROM` コマンドでデータソースを指定することで、データソースをクエリできます。最大 10 個のデータソースを指定できます。 **[Syntax]** (構文) ``` `dataSource( ['DataSource1', 'DataSource2', ...'DataSourcen'] )` ``` **クエリの例 ** ``` SELECT DS1.Column1, DS1.Column2 from `dataSource( ['DataSource1', 'DataSource2'] )` as DS1 WHERE DS1.Column1 = 'ABC' ``` ## クエリスコープ AWS CLI および API では、ロググループ、データソースとタイプ、フィールドインデックスを使用して、クエリするログを指定できます。 ### ロググループ ロググループのソース選択は、検索する必要がある正確なロググループ (複数可) がわかっている場合に使用できます。 ``` SELECT * FROM `logGroups(logGroupIdentifier: ['/aws/lambda/my-function'])`; ``` ### データソースとタイプ お客様は、データソース名とデータソースタイプを使用してログをクエリできます。 データソースとタイプベースのソース選択は、クエリが必要なデータソースを正確に把握している場合に使用できます。このクエリは、指定されたデータソースとタイプを含む 1 つ以上のロググループで実行されます。 SQL でデータソースをクエリするためのユースケースをサポートするには、dataSource コマンドを使用できます。この構文を使用して、FROM コマンドでデータソースを指定することで、データソースをクエリできます。最大 10 個のデータソースを指定できます。 構文: ``` `dataSource( ['DataSource1.Type1', 'DataSource2.Type2', ...'DataSourcen.Typen'] )` ``` クエリの例: ``` SELECT DS1.Column1, DS1.Column2 from `dataSource( ['DataSource1.Type1', 'DataSource2.Type2'] )` as DS1 WHERE DS1.Column1 = 'ABC' ``` データソースによるクエリの詳細については、「」を参照してください[ファセットを使用してログをグループ化および探索する](CloudWatchLogs-Facets.md)。 ### 組み合わされた例 お客様はバックティック内のすべてのソース選択演算子を任意の順序で指定でき、結果は適用されるすべての条件の共通部分に基づきます。 たとえば、/aws/lambda/my-function-1 には、さまざまなインデックスを含む複数のデータソースとタイプが含まれている場合があります。次のクエリが実行されると、返される結果にはソースイベントとタイプ DataSource1.Type1 のイベントのみが含まれ、'status' = 200 の基準に一致します。 ``` SELECT * FROM ` logGroups(logGroupIdentifier: ['/aws/lambda/my-function']) filterIndex('status' = 200) dataSource(['DataSource1.Type1']) `; ``` ### フィールドインデックス フィールドインデックスベースのソース選択は、フィルターがインデックス付きフィールドをターゲットにするときに、関連するロググループを自動的に識別し、スキャンボリュームとクエリランタイムを減らします。 `filterIndex` を使用してインデックス付きデータのみを返すには、クエリで指定したフィールドでインデックス付けされたロググループのみをスキャンするようクエリに強制します。このフィールドでインデックス付けされるこれらのロググループの場合、インデックス付けされたフィールドのクエリで指定されたフィールドを含む任意のログイベントを持たないロググループをスキップすることで、クエリがさらに最適化されます。さらに、このフィールドインデックスのクエリで指定された値に一致するこれらのロググループのログイベントのみをスキャンしようとすることで、スキャンされるボリュームが減少します。フィールドインデックスとその作成方法の詳細については、「Create [field indexes to improve query performance and reduce scan volume](CloudWatchLogs-Field-Indexing.md)」を参照してください。 SQL では、filterIndex を使用して、インデックスとして扱うキーと値のペアを指定します。構文は次のとおりです。 ``` SELECT * FROM `filterIndex('region' = 'us-east-1')`; ``` 次のとおりです。 1. filterIndex(...) は、キー値をフィールドインデックスとして扱います。各キーと値のペアはカンマで区切られます (以下の例) 1. 「region」 = 「us-east-1」は、適用する実際の条件を指定します。 1. 注: = の代わりに、顧客は IN を使用して複数の値を指定できます (以下の例) 複数の filterIndex を使用すると、「AND」を使用して条件が結合されます。この例では、us-east-1 または us-west-2 の status=200 と region に一致するログがクエリされます。 ``` SELECT * FROM `filterIndex('status' = 200, 'region' IN ['us-east-1', 'us-west-2'])`; ``` ## 制限事項 OpenSearch SQL を使用して CloudWatch Logs Insights でクエリを実行する場合、次の制限が適用されます。 + SELECT ステートメントに含めることができる JOIN は 1 つだけです。 + データソースクエリで JOIN またはサブクエリを使用することはできません。 + ネストされたサブクエリは 1 つのレベルのみサポートされます。 + セミコロン (;) で区切られた複数のステートメントのクエリはサポートされていません。 + フィールド名が同一であるが、大文字や小文字のみが異なる (field1 および FIELD1 など) クエリはサポートされていません。 例えば、次のクエリはサポートされません。 ``` Select AWSAccountId, AwsAccountId from LogGroup ``` ただし、このフィールド名 (`@logStream`) は両方のロググループで同一であるため、次のクエリがサポートされています。 ``` Select a.`@logStream`, b.`@logStream` from Table A INNER Join Table B on a.id = b.id ``` + 関数と式はフィールド名に対して操作し、FROM 句で指定されたロググループを持つ SELECT ステートメントの一部である必要があります。 例として、次のクエリはサポートされていません。 ``` SELECT cos(10) FROM LogGroup ``` このクエリはサポートされています。 ``` SELECT cos(field1) FROM LogGroup ``` + SQL コマンドまたは PPL コマンドを使用する場合は、特定のフィールドをバッククオートで囲んでクエリを正常に実行します。特殊文字 (アルファベットや数字でないもの) を含むフィールドにはバッククオートが必要です。例えば、`@message`、`Operation.Export`、`Test::Field` をバッククォートで囲みます。フィールド名がアルファベットのみの場合はバッククオートで囲む必要はありません。 シンプルなフィールドを含むクエリの例: ``` SELECT SessionToken, Operation, StartTime FROM `LogGroup-A` LIMIT 1000; ``` バッククオートが付け足された類似のクエリ: ``` SELECT `@SessionToken`, `@Operation`, `@StartTime` FROM `LogGroup-A` LIMIT 1000; ``` # 自然言語を使用した CloudWatch Logs Insights クエリの生成と更新 CloudWatch Logs は自然言語クエリ機能をサポートしており、[CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)、[OpenSearch Service PPL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_PPL.html)、[OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html)、[CloudWatch Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html) のクエリを生成し、更新する際に便利です。 この機能を使用すると、どのような CloudWatch Logs データを探しているのかを平易な英語で質問したり、具体的に説明したりすることができます。自然言語機能が働いて、入力したプロンプトに基づいてクエリが生成され、クエリの仕組みを説明した文が 1 行ずつ表示されます。また、さらにデータを詳しく調査できるように、生成されたクエリを更新することもできます。 環境に応じて、「転送されたバイト数で上位 100 のソース IP アドレスは何ですか?」 や「Lambda 関数の最も遅いリクエストを 10 個見つけてください。」などのプロンプトを入力できます。 **注記** 自然言語クエリ機能はリージョン別のサービスです。一部のリージョンでは、この機能は、クエリ プロンプトを処理するために、米国のリージョンに対してクロスリージョン呼び出しを行います。詳細については、「[Amazon CloudWatch が自然言語クエリ結果の要約とクエリ生成のリージョン別サポートを拡張する](https://aws.amazon.com/about-aws/whats-new/2025/08/amazon-cloudwatch-region-support-query-result-summarization-query-generation/)」を参照してください。 この機能を使用して CloudWatch Logs Insights クエリを生成するには、CloudWatch Logs Insights クエリエディタを開き、クエリするロググループを選択し、**[Generate query]** を選択します。 **重要** 自然言語クエリ機能を使用するには、[CloudWatchLogsFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsFullAccess.html)、[CloudWatchLogsReadOnlyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsReadOnlyAccess.html)、[AdministratorAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html)、[ReadOnlyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ReadOnlyAccess.html) の IAM ポリシーでサインインするか、`cloudwatch:GenerateQuery` のアクセス権限が必要です。 ## クエリの例 このセクションの例では、自然言語機能を使用して、クエリを生成し更新する方法について説明します。 **注記** CloudWatch Logs Insights クエリエディタと構文の詳細については、「[CloudWatch Logs Insights query syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)」を参照してください。 ### 例: 自然言語クエリを生成する 自然言語を使用してクエリを生成するには、プロンプトを入力し、**[新しいクエリを生成]** を選択します。これらの例は、基本的な検索を実行するクエリを示しています。 **Prompt** 以下は、最も遅い 10 個の Lambda 関数の呼び出しを検索する機能を指示するプロンプトの例です。 ``` Find the 10 slowest requests ``` **クエリ** 以下は、自然言語機能がプロンプトに基づいて生成した CloudWatch Logs Insights クエリ言語を使用したクエリです。プロンプトがクエリの前にあるコメントにどのように表示されるかに注意してください。クエリの後に、クエリの仕組みを説明した文があります。 ``` # Find the 10 slowest requests fields @timestamp, @message, @duration | sort @duration desc | limit 10 # This query retrieves the timestamp, message and duration fields from the logs and sorts them in descending order by duration to find the 10 slowest requests. ``` **注記** プロンプトとクエリの仕組みを説明した文が表示されないようにするには、エディタの歯車アイコンを使用します。 **Prompt** OpenSearch SQL クエリを生成するには、OpenSearch SQL タブを選択し、クエリジェネレータープロンプトボックスを開いて自然言語プロンプトを入力します。OpenSearch SQL クエリを生成するために自然言語機能が使用するプロンプトの例を以下に示します。 ``` Give me the number of errors and exceptions per hour ``` **クエリ** 以下は、1 時間あたりで集計されたエラーと例外の数を見つけるために使用できる、そのプロンプトによって生成された SQL クエリです。 ``` SELECT DATE_FORMAT(`@timestamp`, 'yyyy-MM-dd HH') AS hour, COUNT(*) AS error_count FROM `/aws/lambda/CloudWatchOdysseyQueryGen` WHERE `@message` LIKE '%error%' OR `@message` LIKE '%exception%' GROUP BY DATE_FORMAT(`@timestamp`, 'yyyy-MM-dd HH') ORDER BY hour ``` **Prompt** OpenSearch PPL クエリを生成するには、OpenSearch PPL タブを選択し、クエリジェネレータープロンプトボックスを開いて自然言語プロンプトを入力します。OpenSearch PPL クエリを生成するために自然言語機能が使用するプロンプトの例を以下に示します。 ``` Give me all unique exception messages ``` **クエリ** 以下は、ログ内の一意の例外メッセージを検索するために使用できる、そのプロンプトによって生成された PPL クエリです。 ``` dedup @message | fields @message ``` ### 例: 自然言語クエリを更新する 生成済みのプロンプトを編集し、**[クエリを更新]** を選択することで、クエリを更新できます。 **プロンプトの更新** 次の例は、先ほどのプロンプトを更新したものを示しています。最も遅い 10 個の Lambda 関数の呼び出しを検索するプロンプトの代わりに、このプロンプトは 最も遅い 20 個の Lambda 関数の呼び出しを検索し、追加のログイベントのために別の列を含めています。 ``` Show top 20 slowest requests instead and display requestId as a column ``` **クエリの更新** 以下は、CloudWatch Logs Insights クエリ言語を使用して更新されたクエリの例です。更新したプロンプトが更新したクエリの前にあるコメントにどのように表示されるかに注意してください。クエリの後に、元のクエリがどのように更新されたかを説明した文があります。 ``` # Show top 20 slowest requests instead and display requestId as a column fields @timestamp, @message, @requestId, @duration | sort @duration desc | limit 20 # This query modifies the original query by replacing the @message field with the @requestId field and changing the limit from 10 to 20 to return the top 20 log events by duration instead of the top 10. ``` ## サービス改善のためのデータ使用をオプトアウトする AI モデルをトレーニングし、該当するクエリを生成するために提供した自然言語プロンプトデータは、サービスを提供して維持するためにのみ使用されます。このデータは、CloudWatch Logs Insights の品質を高めるために使用される可能性があります。お客様の信頼、プライバシー、コンテンツのセキュリティが当社の最優先事項です。詳細については、「[AWS サービス規約](https://aws.amazon.com/service-terms/)」と「[AWS responsible AI policy](https://aws.amazon.com/machine-learning/responsible-ai/policy/)」を参照してください。 自然言語クエリの開発や品質改善に自分のコンテンツが使用されないようにオプトアウトするには、AI サービスオプトアウトポリシーを作成します。クエリ生成機能などのすべての CloudWatch Logs AI 機能データ収集をオプトアウトするには、CloudWatch Logs のオプトアウトポリシーを作成する必要があります。詳細については、「*AWS Organizations ユーザーガイド*」の「[AI サービスオプトアウトポリシー](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html)」を参照してください。 # サポートされるログと検出されるフィールド CloudWatch Logs Insights は、さまざまなタイプのログをサポートします。Amazon CloudWatch Logs の標準クラスロググループに送信されるすべてのログについて、CloudWatch Logs Insights は 5 つのシステムフィールドを自動的に生成します。 + `@message` は、生の未解析のログイベントを示します。これは、[InputLogevent](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_InputLogEvent.html) の `message` フィールドに相当します。 + `@timestamp` には、ログイベントの `timestamp` フィールドに含まれるイベントタイムスタンプが含まれます。これは、[InputLogevent](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_InputLogEvent.html) の `timestamp` フィールドに相当します。 + `@ingestionTime` は、ログイベントが CloudWatch Logs によって受信された時間を示します。 + `@logStream` は、ログイベントの追加先のログストリームの名前を示します。ログストリームは、生成時と同じプロセスでログをグループ化します。 + `@log` は、`account-id:log-group-name` の形式のロググループ識別子です。これは、複数のロググループにクエリを実行する場合に、特定のイベントが属しているロググループを識別するのに役立ちます。 + `@entity` には、[Explore 関連のテレメトリ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ExploreRelated.html)機能のエンティティに関連するフラット化された JSON が含まれています。 例えば、この JSON はエンティティを表すことができます。 ``` { "Entity": { "KeyAttributes": { "Type": "Service", "Name": "PetClinic" }, "Attributes": { "PlatformType": "AWS::EC2", "EC2.InstanceId": "i-1234567890123" } } } ``` このエンティティの場合、抽出されたシステムフィールドは次のとおりです。 ``` @entity.KeyAttributes.Type = Service @entity.KeyAttributes.Name = PetClinic @entity.Attributes.PlatformType = AWS::EC2 @entity.Attributes.EC2.InstanceId = i-1234567890123 ``` **注記** フィールド検出は、標準ログクラスのロググループでのみサポートされます。ログクラスの詳細については、「[ログクラス](CloudWatch_Logs_Log_Classes.md)」を参照してください。 CloudWatch Logs Insights では、生成されるフィールドの先頭に **@** 記号を挿入します。 CloudWatch Logs は、多くのログタイプで、ログ内のログフィールドも自動的に検出します。これらの自動検出フィールドを以下の表に示します。 CloudWatch Logs Insights が自動的に検出しないフィールドを持つ他のログタイプについては、`parse` コマンドを使用して抽出フィールドを抽出および作成してクエリで使用できます。詳細については、「[CloudWatch Logs Insights 言語のクエリ構文](CWL_QuerySyntax.md)」を参照してください。 検出されたログフィールドの名前が `@` 文字で始まる場合は、この名前の先頭に `@` が追加されて CloudWatch Logs Insights に表示されます。たとえば、ログフィールド名が `@example.com` である場合、このフィールド名は `@@example.com` と表示されます。 **注記** `@message`、`@timestamp`、`@log` を除き、検出されたフィールドのフィールドインデックスを作成できます。フィールドインデックスの詳細については、「[フィールドインデックスを作成してクエリパフォーマンスを改善し、スキャン量を削減する](CloudWatchLogs-Field-Indexing.md)」を参照してください。 | ログタイプ | 検出されるログフィールド | | --- | --- | | Amazon VPC フローログ | `@timestamp`, `@logStream`, `@message`, `accountId`, `endTime`, `interfaceId`, `logStatus`, `startTime`, `version`, `action`, `bytes`, `dstAddr`, `dstPort`, `packets`, `protocol`, `srcAddr`, `srcPort` | | Route 53 ログ | `@timestamp`, `@logStream`, `@message`, `edgeLocation`, `ednsClientSubnet`, `hostZoneId`, `protocol`, `queryName`, `queryTimestamp`, `queryType`, `resolverIp`, `responseCode`, `version` | | Lambda ログ | `@timestamp`, `@logStream`, `@message`, `@requestId`, `@duration, ``@billedDuration`, `@type`, `@maxMemoryUsed`, `@memorySize` Lambda ログ行に X-Ray トレース ID が含まれている場合は、`@xrayTraceId` および `@xraySegmentId` フィールドも含まれます。 CloudWatch Logs Insights は、Lambda ログのログフィールドを自動的に検出します。ただし、各ログイベントに埋め込まれている最初の JSON フラグメントのみが検出されます。Lambda ログイベントに複数の JSON フラグメントが含まれている場合は、`parse` コマンドを使用してログフィールドを解析して抽出できます。詳細については、「[JSON ログのフィールド](#CWL_AnalyzeLogData-discoverable-JSON-logs)」を参照してください。 | | CloudTrail ログ JSON 形式のログ | 詳細については、「[JSON ログのフィールド](#CWL_AnalyzeLogData-discoverable-JSON-logs)」を参照してください。 | | その他のログタイプ | `@timestamp`, `@ingestionTime`, `@logStream`, `@message`, `@log`. | ## JSON ログのフィールド CloudWatch Logs Insights では、ドット表記を使用して JSON フィールドを表します。このセクションでは、ドット表記を使用して JSON フィールドにアクセスする方法を、JSON イベントとコードスニペットによる例で説明します。 **例: JSON イベント** ``` { "eventVersion": "1.0", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn: aws: iam: : 123456789012: user/Alice", "accessKeyId": "EXAMPLE_KEY_ID", "accountId": "123456789012", "userName": "Alice" }, "eventTime": "2014-03-06T21: 22: 54Z", "eventSource": "ec2.amazonaws.com", "eventName": "StartInstances", "awsRegion": "us-east-2", "sourceIPAddress": "192.0.2.255", "userAgent": "ec2-api-tools1.6.12.2", "requestParameters": { "instancesSet": { "items": [ { "instanceId": "i-abcde123" } ] } }, "responseElements": { "instancesSet": { "items": [ { "instanceId": "i-abcde123", "currentState": { "code": 0, "name": "pending" }, "previousState": { "code": 80, "name": "stopped" } } ] } } } ``` サンプルの JSON イベントには、`userIdentity` という名前のオブジェクトが含まれています。`userIdentity` には `type` という名前のフィールドが含まれます。ドット表記を使用して `type` の値を表すには、`userIdentity.type` を使用します。 サンプル JSON イベントには、ネストされたフィールド名と値のリストにフラット化された配列が含まれています。`requestParameters.instancesSet` の最初の項目である `instanceId` の値を表すには、`requestParameters.instancesSet.items.0.instanceId` を使用します。`instanceID` フィールドの前にある番号 `0` は、`items` フィールドの値の場所を指します。次の例には、JSON ログイベントでネストされた JSON フィールドにアクセスする方法を示すコードスニペットが含まれています。 **例: クエリ** ``` fields @timestamp, @message | filter requestParameters.instancesSet.items.0.instanceId="i-abcde123" | sort @timestamp desc ``` このコードスニペットは、ネストされた JSON フィールド `instanceId` の値にアクセスする `filter` コマンドと共にドット表記を使用するクエリを示します。このクエリは、`instanceId` の値が `"i-abcde123"` に等しいメッセージをフィルタリングし、指定した値を含むログイベントをすべて返します。 **注記** CloudWatch Logs Insights は、1 つの JSON ログから最大 200 個のログイベントフィールドを抽出できます。抽出されない追加のフィールドについては、`parse` コマンドを使用して、メッセージフィールドの未処理の未解析ログイベントからこれらのフィールドを抽出できます。`parse` コマンドの詳細については、「Amazon CloudWatch ユーザーガイド」の「[クエリ構文](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)」を参照してください。 # フィールドインデックスを作成してクエリパフォーマンスを改善し、スキャン量を削減する ログイベントでフィールドの*フィールドインデックス*を作成して、同等性ベースの検索を効率的に行うことができます。その後、CloudWatch Logs Insights クエリでフィールドインデックスを使用すると、クエリはインデックス付きフィールドを含まないことがわかっているログイベントの処理のスキップを試行します。これによってフィールドインデックスを使用するクエリのスキャン量が減少し、結果をより迅速に返すことができます。これにより、数千のロググループ全体で合計ログのペタバイトをすばやく検索し、関連するログをより迅速に見つけることができます。インデックス付けに適したフィールドは、多くの場合、クエリが必要なフィールドです。値のカーディナリティが高いフィールドは、フィールドインデックスの候補としても適しています。これらのフィールドインデックスを使用するクエリは、一致するログイベントをターゲット値に制限するため、より迅速に完了するからです。 例えば、`requestId` のフィールドインデックスを作成したとします。次に、 `requestId = value`または を含むそのロググループの CloudWatch Logs Insights クエリ`requestId IN [value, value, ...]`は、そのインデックス付きフィールドとクエリされた値を含むことがわかっており、CloudWatch Logs がそのフィールドの値を過去に検出したログイベントのみを処理しようとします。 フィールドインデックスを活用して、多数のロググループの効率的なクエリを作成することもできます。`filter` コマンドの代わりにクエリで `filterIndex` コマンドを使用すると、フィールドインデックスを持つログイベントで選択したロググループに対してクエリが実行されます。これらのクエリは、最大 5 つのロググループ名のプレフィックスを指定することで、最大 10,000 個のロググループをスキャンできます。これが CloudWatch のクロスアカウントオブザーバビリティのモニタリングアカウントの場合は、すべてのソースアカウントを選択するか個々のソースアカウントを指定してロググループを選択できます。 インデックス付きのフィールドでは、大文字と小文字が区別されます。例えば、`RequestId` のフィールドインデックスは、`requestId` を含むログイベントと一致しません。 フィールドインデックスは、JSON ログとサービスログの構造化ログ形式でのみサポートされます。 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)にはカウントされません。 CloudWatch Logs は、インデックスポリシーの作成後に取り込まれたログイベントのみをインデックス化します。ポリシーの作成前に取り込まれたログイベントはインデックス化されません。フィールドインデックスを作成すると、一致する各ログイベントは、ログイベントの取り込み時間から 30 日間インデックスが付いたままになります。 **注記** モニタリングアカウントにフィールドインデックスポリシーを作成する場合、そのポリシーはリンクされたソースアカウントのロググループには使用されません。フィールドインデックスポリシーは、それが作成されたアカウントにのみ適用されます。 このセクションの残りのトピックでは、フィールドインデックスを作成する方法について説明します。クエリでフィールドインデックスを参照する方法については「[filterIndex](CWL_QuerySyntax-FilterIndex.md)」および「[フィルター](CWL_QuerySyntax-Filter.md)」を参照してください。 **Topics** + [フィールドインデックスの構文とクォータ](CloudWatchLogs-Field-Indexing-Syntax.md) + [アカウントレベルのフィールドインデックスポリシーを作成する](CloudWatchLogs-Field-Indexing-CreateAccountLevel.md) + [ロググループレベルのフィールドインデックスポリシーを作成する](CloudWatchLogs-Field-Indexing-CreateLogGroupLevel.md) + [クエリ作成時のロググループの選択オプション](Field-Indexing-Selection.md) + [フィールドインデックスポリシーを削除した場合の影響](CloudWatchLogs-Field-Indexing-Deletion.md) # フィールドインデックスの構文とクォータ フィールドインデックスを作成するには、*フィールドインデックスポリシー*を作成します。アカウント全体に適用されるアカウントレベルのインデックスポリシーを作成できます。また、単一のロググループのみに適用されるポリシーを作成することもできます。アカウント全体のインデックスポリシーでは、アカウント内のすべてのロググループに適用されるインデックスポリシーを設定できます。ロググループ名のプレフィックスによって選択された、アカウントのロググループのサブセットに適用されるアカウントレベルのインデックスポリシーを作成することもできます。同じアカウントに複数のアカウントレベルのポリシーがある場合、これらのポリシーのロググループ名のプレフィックスを重複させることはできません。同様に、特定のデータソース名とタイプの組み合わせに適用されるアカウントレベルのインデックスポリシーを作成できます。データソース名とタイプの組み合わせごとに作成できるアカウントポリシーは 1 つだけです。 ロググループレベルのフィールドインデックスポリシーは、アカウントレベルのフィールドインデックスポリシーを上書きします。これは、ロググループ全体に適用されます (選択基準のないアカウントレベルのポリシーや、ロググループ名のプレフィックスベースの選択基準を持つアカウントレベルのポリシーなど）。ログイベントレベルで一致するアカウントレベルのポリシー (特定のデータソース名とタイプの組み合わせなど) は、ロググループ全体に一致するポリシーに加えて適用されます。ロググループレベルのインデックスポリシーを作成する場合、そのロググループは、ロググループレベルで一致するアカウントレベルのポリシーを使用しません。 ログイベントとフィールドインデックスの名前の一致では、大文字と小文字が区別されます。例えば、`RequestId` のフィールドインデックスは、`requestId` を含むログイベントと一致しません。 最大 40 のアカウントレベルのインデックスポリシーを持つことができ、そのうち 20 はロググループ名のプレフィックス選択基準を使用し、20 はデータソースベースの選択基準を使用できます。ロググループ名のプレフィックスに対してフィルタリングされた複数のアカウントレベルのインデックスポリシーがある場合、同じまたは重複するロググループ名のプレフィックスを 2 つ使用することはできません。例えば、`my-log` で始まるロググループに対してフィルタリングされたポリシーが 1 つある場合、別のフィールドインデックスポリシーを `my-logpprod` または `my-logging` に対してフィルタリングすることはできません。同様に、データソース名とタイプの組み合わせにフィルタリングされた複数のアカウントレベルのインデックスポリシーがある場合、2 つのポリシーで同じデータソース名とタイプを使用することはできません。たとえば、1 つのポリシーをデータソース名`amazon_vpc`とデータソースタイプにフィルタリングした場合`flow`、この組み合わせで別のポリシーを作成することはできません。 名前プレフィックスがなく、すべてのロググループに適用されるアカウントレベルのインデックスポリシーがある場合、ロググループ名プレフィックスフィルターを持つ他のアカウントレベルのインデックスポリシーを作成することはできません。データソース名とタイプフィルターを使用するアカウントレベルのインデックスポリシーを作成できます。 各インデックスポリシーには、次のクォータと制限があります。 + 最大 20 個のフィールドをポリシーに含めることができます。 + 各フィールド名には最大 100 文字を含めることができます。 + `@` で始まるロググループにカスタムフィールドのインデックスを作成するには、フィールド名の先頭に `@` を追加してフィールドを指定する必要があります。例えば、ログイベントに `@userId` という名前のフィールドが含まれている場合は、`@@userId` を指定してこのフィールドのインデックスを作成する必要があります。 データソース名とタイプベースの選択基準を持つアカウントレベルのインデックスポリシーでは、追加の制限が適用されます。すべてのフィールドはプリミティブデータ型でなければならず、ネストされたプリミティブは 構造体でのみサポートされます。 **生成されたフィールドと予約されたフィールド** CloudWatch Logs Insights は、各ログイベントにシステムフィールドを自動的に生成します。これらの生成されたフィールドには `@` のプレフィックスが付きます。生成されたフィールドの詳細については「[サポートされるログと検出されるフィールド](CWL_AnalyzeLogData-discoverable-fields.md)」を参照してください。 これらの生成されたフィールドのうち、フィールドインデックスとして使用するために以下がサポートされています。 + `@logStream` + `@ingestionTime` + `@requestId` + `@type` + `@initDuration` + `@duration` + `@billedDuration` + `@memorySize` + `@maxMemoryUsed` + `@xrayTraceId` + `@xraySegmentId` これらの生成されたフィールドをインデックス付けするには、`@` で始まるカスタムフィールドに対して行う必要があるため、それらを指定するときに `@` を追加する必要はありません。例えば、`@logStream` のフィールドインデックスを作成するには、`@logStream` をフィールドインデックスとして指定します。 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)にはカウントされません。 **JSON ログの子フィールドと配列フィールド** JSON ログのネストされた子フィールドまたは配列フィールドであるフィールドにインデックスを作成できます。 例えば、このログ内の `userIdentity` フィールド内に `accessKeyId` 子フィールドのインデックスを作成できます。 ``` { "eventVersion": "1.0", "userIdentity": { "type": "IAMUser", "principalId": "EXAMPLE_PRINCIPAL_ID", "arn": "arn: aws: iam: : 123456789012: user/Alice", "accessKeyId": "11112222", "accountId": "123456789012", "userName": "Alice" }, "eventTime": "2014-03-06T21: 22: 54Z", "eventSource": "ec2.amazonaws.com", "eventName": "StartInstances", "awsRegion": "us-east-2", "sourceIPAddress": "192.0.2.255", "userAgent": "ec2-api-tools1.6.12.2", "requestParameters": { "instancesSet": { "items": [{ "instanceId": "i-abcde123", "currentState": { "code": 0, "name": "pending" }, "previousState": { "code": 80, "name": "stopped" } }] } } } ``` このフィールドを作成するには、フィールドインデックスを作成する時とクエリでそれを指定する時の両方で、ドット表記 (`userIdentity.accessKeyId`) を使用して参照します。クエリは次のようになります。 ``` fields @timestamp, @message | filterIndex userIdentity.accessKeyId = "11112222" ``` 前の例のイベントの場合、`instanceId` フィールドは `requestParameters.instancesSet.items` 内の配列にあります。フィールドインデックスの作成時とクエリ時の両方でこのフィールドを表すには、`requestParameters.instancesSet.items.0.instanceId` として参照します。0 は配列内のそのフィールドの場所を参照します。 すると、このフィールドのクエリは次のようになります。 ``` fields @timestamp, @message | filterIndex requestParameters.instancesSet.items.0.instanceId="i-abcde123" ``` # アカウントレベルのフィールドインデックスポリシーを作成する このセクションのステップを使用して、アカウント内のすべてのロググループ、または同じ文字列で始まるロググループ名を持つ複数のロググループに適用されるフィールドインデックスポリシーを作成します。 **アカウントレベルのフィールドインデックスポリシーを作成するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[設定]** を選択し、**[ログ]** を選択します。 1. **[アカウントレベルのインデックスポリシー]** セクションで、**[管理]** を選択します。 1. **[インデックスポリシーを作成]** を選択します。 1. **ポリシー名**に、新しいポリシーの名前を入力します。 1. **ポリシーの範囲を選択する**には、次のいずれかを実行します。 + **[すべての標準ロググループ]** を選択して、インデックスポリシーをアカウントのすべての標準クラスロググループに適用します。 + **プレフィックス一致でロググループ**を選択し、同じ文字列で始まる名前を持つロググループのサブセットにポリシーを適用します。次に、これらのロググループのプレフィックスを **[プレフィックス名を入力]** に入力します。 プレフィックスを入力したら、**[プレフィックスが一致したロググループをプレビュー]** を選択して、プレフィックスが期待したロググループと一致することを確認できます。 **データソース別のログデータ**を選択して、ポリシーを特定のデータソース名とタイプの組み合わせに適用します。その後、ドロップダウンメニューから**データソース**と**データ型**を選択できます。 データソース名とタイプを選択したら、**フィールドの取得**を選択して、**フィールドインデックスとファセットの設定**セクションに、使用可能なフィールド、含まれるロググループ、デフォルトフィールドインデックスとカスタムフィールドインデックスなどの関連情報を入力できます。 1. **[カスタムインデックスフィールド設定]** で **[フィールドパスを追加]** を選択し、インデックスを作成する最初のフィールドを入力します。 次に、フィールド名の値として使用する文字列を入力するか、ドロップダウンメニューからフィールドを選択します。これは、ログイベントに表示されるものと完全に一致する必要があります。例えば、ログイベントに `requestId` が含まれている場合は、ここに `requestId` と入力する必要があります。`RequestId`、`requestID`、`request Id` は一致しません。 `@` 文字で始まるカスタムログフィールドにインデックスを作成する場合は、インデックス文字列を入力するときに追加の `@` 文字を含める必要があります。例えば、カスタムログフィールド `@emailname` がある場合は、**[フィールドパスの追加]** ボックスに `@@emailname` と入力します。 CloudWatch Logs が自動的に生成する `@ingestionTime` および `@logStream` フィールドのインデックスを作成することもできます。その場合は、指定するときに `@` を追加する必要はありません。 1. (オプション) フィールドパスを指定するだけでなく、**ファセットとして設定**を選択して、ファセットとしてフィールドを作成できます。 1. 前のステップを繰り返して、最大 20 個のフィールドインデックスを追加します。 1. 終了したら、**[Create]** (作成) を選択します。 # ロググループレベルのフィールドインデックスポリシーを作成する このセクションのステップを使用して、単一のロググループに適用されるフィールドインデックスポリシーを作成します。 **ロググループレベルのフィールドインデックスポリシーを作成するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. 左側のナビゲーションペインで、**[Logs]** (ログ)、**[Log groups]** (ロググループ) の順に選択します。 1. ロググループの名前を選択します。 1. **[フィールドインデックス]** タブを選択します。 1. **[このロググループのフィールドインデックスを管理]** を選択します。 1. **[ロググループレベルのフィールドインデックスを管理]** で **[フィールドパスの追加]** を選択し、インデックスを作成する最初のフィールドを入力します。 次に、フィールド名の値として使用する文字列を入力します。これは、ログイベントに表示されるものと完全に一致する必要があります。例えば、ログイベントに `requestId` が含まれている場合は、ここに `requestId` と入力する必要があります。`RequestId`、`requestID`、`request Id` は一致しません。 `@` 文字で始まるカスタムログフィールドにインデックスを作成する場合は、インデックス文字列を入力するときに追加の `@` 文字を含める必要があります。例えば、カスタムログフィールド `@emailname` がある場合は、**[フィールドパスの追加]** ボックスに `@@emailname` と入力します。 CloudWatch Logs が自動的に生成する `@ingestionTime` および `@logStream` フィールドのインデックスを作成することもできます。その場合は、指定するときに `@` を追加する必要はありません。 1. (オプション) フィールドパスを指定するだけでなく、**ファセットとして設定**を選択して、ファセットとしてフィールドを作成できます。 1. 前のステップを繰り返して、最大 20 個のフィールドインデックスを追加します。 1. 完了したら、[**Save**] を選択します。 # クエリ作成時のロググループの選択オプション このセクションでは、クエリに含めるロググループを選択するさまざまな方法について説明します。 **コンソールでクエリのロググループを選択するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[ログ]**、**[Logs Insights]** を選択します。 1. このクエリに使用するクエリ言語を選択します。**Logs Insights QL**、**OpenSearch PPL**、**OpenSearch SQL** のいずれかを選択できます。 1. クエリのロググループを選択する方法は 3 つあります。 + **[ロググループ名]** ボックスを使用します。これはデフォルトの選択方法です。この方法では、最大 50 個のロググループ名を入力できます。これが CloudWatch のクロスアカウントオブザーバビリティのモニタリングアカウントの場合は、モニタリングアカウントだけでなくソースアカウントのロググループも選択できます。1 つのクエリで複数のアカウントのログを一度にクエリできます。 + **[ロググループの条件]** セクションを使用します。このセクションでは、ロググループ名のプレフィックスに基づいてロググループを選択できます。1 つのクエリに最大 5 つのプレフィックスを含めることができます。これらのプレフィックスが名前に含まれているロググループが選択されます。または、**[すべてのロググループ]** オプションで、アカウントからすべてのロググループを選択します。 + これが CloudWatch クロスアカウントオブザーバビリティのモニタリングアカウントである場合は、アカウントドロップダウンメニューで**[すべてのアカウント]** を選択して、リンクされたすべてのアカウントからロググループを選択できます。または、このクエリに含めるアカウントを個別に選択できます。 選択肢が 10,000 を超えるロググループと一致する場合、選択肢を絞り込むよう求めるエラーが表示されます。 1. クエリのデフォルトのログクラスは **標準** です。**[ログクラス]** を使用して**低頻度アクセス**に変更できます。 **の使用 AWS CLI** コマンドラインからクエリを開始するときにこれらのタイプの選択を行うには、クエリで `source` コマンドを使用できます。詳細な説明と例については、[SOURCE](CWL_QuerySyntax-Source.md) を参照してください。 # フィールドインデックスポリシーを削除した場合の影響 しばらく有効になっているフィールドインデックスポリシーを削除すると、次のようになります。 + ポリシーが削除されてから最大 30 日間、クエリはインデックスが作成されたログイベントから恩恵を受けることができます。 + ロググループレベルのインデックスポリシーを削除し、そのロググループに適用されるアカウントレベルのポリシーがすでに設定されている場合、アカウントレベルのポリシーは最終的にそのロググループに適用されます。 # ファセットを使用してログをグループ化および探索する ファセットは、クエリを実行せずにデータをインタラクティブにフィルタリングおよびグループ化できるため、ログの分析に役立ちます。ファセットは、ロググループ間のフィルタリング、集約、分析を可能にするログ内のフィールド ( `ServiceName`や など`StatusCode`) です。CloudWatch Logs Insights コンソールでファセットフィールドのリストと、選択した時間範囲に基づく各ファセット値のログイベントの数を表示できます。さまざまなファセットと値を選択すると、ファセット値とカウントがリアルタイムで更新されるため、ログをインタラクティブに探索できます。 各ファセットには、選択した時間範囲とクエリスコープに基づいてログ内のフィールドから自動的に抽出され、30 日間保持される使用可能な値とカウントが表示されます。表示されるファセット数は概算です。データソース名やデータソースタイプなどのデフォルトのファセットを使用してログを調べたり、ログの任意のフィールドにカスタムファセットを作成したりできます。データソース名はログを生成する AWS のサービスまたはアプリケーション (Route 53、Amazon VPC、CloudTrail など) であり、データソースタイプはそのサービスによって生成される特定のタイプのログです。デフォルトのファセットは CloudWatch によって作成され`@aws.region`、、`@data_source_name`、`@data_source_type`、および が含まれます`@data_format`。詳細については、「[ログ管理](LogManagement.md)」を参照してください。ファセットは、アカウントに取り込まれたログでのみ使用できます。クロスアカウントオブザーバビリティを設定している場合、モニタリングアカウントはソースアカウントのログに基づいてファセットを表示できません。 追加のファセットを作成するには、トラブルシューティングに関連するログのフィールドを選択し、インデックスポリシーを使用してファセットを設定します。カスタムファセットの場合、低カーディナリティフィールド (Status や ApplicationName など、1 日あたり 100 個未満の一意の値を持つフィールド) にファセットを作成することをお勧めします。1 日あたり 100 個を超える一意の値を持つファセットは高濃度に分類され、これらのファセットの値は表示されません。1 つ以上のファセットを選択し、 をクリックしてログ全体でクエリを実行します。 CloudWatch Logs Insights でファセットの使用を開始するには: 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[ログ]**、**[Logs Insights]** を選択します。 1. (オプション) 時間範囲セレクタを使用して、分析する期間を選択します。選択した時間範囲について、使用可能なファセットと値がパネルに表示されます。 1. ファセットを選択してデータを探索し、ファセット間の値分布のリアルタイム更新を確認します。 100 個を超える一意の値を持つファセットは表示されません。特定の値をクエリするには、代わりにクエリでフィルターを使用します。 ## ファセットベースのクエリを実行するには 1. ファセット間で 1 つ以上の値を選択します。 1. イベント数は、選択したファセットと値に基づいて更新されます。 1. ファセット値を選択すると、クエリスコープが更新されて選択が反映されます。 1. ファセット値を選択したら、実行をクリックしてクエリを実行します。 1. ファセットごとにサポートされる一意の値の最大数は 100 です。たとえば、ファセットの値が 100 を超える場合、すべてのカウントが「-」として表示され、値が不明であることを示します。 ## ファセットベースのクエリを保存するには 1. 1 つ以上のファセット値を使用してクエリを作成します。 1. 残りのステップは、Logs Insights クエリの保存と同じです。[CloudWatch Logs Insights クエリの保存](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_Insights-Saving-Queries.html)」を参照してください。 1. 保存済みクエリは、保存済みクエリセクションで使用できます。保存されたクエリを取得すると、クエリに使用されるファセットと値が自動的に含まれるため、ログの分析が容易になります。 ## アカウントレベルのファセットを作成するには 1. ファセットを作成するには、まずフィールドをインデックスとして作成し、ファセットとして設定する必要があります。ナビゲーションペインで、**設定**、**ログ**、**アカウントレベルのインデックスポリシー**を選択します。または、**ファセットパネルでファセットの管理**を選択することもできます。 1. **新しいインデックスポリシーの作成** を選択します。インデックスポリシーの作成の詳細については、「」を参照してください[アカウントレベルのフィールドインデックスポリシーを作成する](CloudWatchLogs-Field-Indexing-CreateAccountLevel.md)。 1. ファセットを作成するには、インデックスポリシーの作成ページで、選択したフィールドの**ファセットとして設定** を確認します。 ## APIsを使用したファセット管理 ファセット管理は、フィールドインデックスポリシーを使用して実行できます。詳細については、[https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_FieldIndex.html](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_FieldIndex.html)APIs」を参照してください。 **フィールドインデックス APIs** | いいえ。 | 名前 | 説明 | | --- | --- | --- | | 1 | PutIndexPolicy | 特定のロググループのフィールドインデックスポリシーを作成または更新します | | 2 | PutAccountPolicy | アカウント内のすべてのロググループまたはロググループのサブセットに適用されるアカウントレベルのデータ保護ポリシー、サブスクリプションフィルターポリシー、フィールドインデックスポリシー、トランスフォーマーポリシー、またはメトリクス抽出ポリシーを作成します。 | | 3 | DeleteIndexPolicy | 1 つのロググループに適用されたロググループレベルのフィールドインデックスポリシーを削除します。 | | 4 | DeleteAccountPolicy | CloudWatch Logs アカウントポリシーを削除します。 | # パターン分析 CloudWatch Logs Insights は、機械学習アルゴリズムを使用して、ログをクエリするときに*パターン*を検索します。パターンは、ログフィールド間で繰り返される共有テキスト構造です。クエリの結果を表示するときは、**[パターン]**タブを選択して、結果のサンプルに基づいて CloudWatch Logs が検出したパターンを表示できます。または、クエリに `pattern` コマンドを追加して、一致するログイベントのセット全体のパターンを分析することもできます。 多数のログイベントをいくつかのパターンに圧縮することができるため、パターンは大きなログセットを分析する際に役立ちます。 次の 3 つのログイベントの例を検討してください。 ``` 2023-01-01 19:00:01 [INFO] Calling DynamoDB to store for resource id 12342342k124-12345 2023-01-01 19:00:02 [INFO] Calling DynamoDB to store for resource id 324892398123-12345 2023-01-01 19:00:03 [INFO] Calling DynamoDB to store for resource id 3ff231242342-12345 ``` 前のサンプルでは、3 つのログイベントはすべて 1 つのパターンに従っています。 ``` [INFO] Calling DynamoDB to store for resource id ``` パターン内のフィールドは*トークン*と呼ばれます。リクエスト ID やタイムスタンプなど、パターン内の異なるフィールドは*動的トークン*と呼ばれます。個々の動的トークンは `` で表されます。*文字列*は、トークンが表すデータのタイプの説明です。*数値*は、他の動的トークンと比較して、このトークンがパターン内のどこに表示されるかを示します。 動的トークンの一般的な例には、エラーコード、タイムスタンプ、リクエスト ID があります。*トークン値*は、動的トークンの特定の値を表します。例えば、動的トークンが HTTP エラーコードを表す場合、トークン値は `501` になります。 パターン検出は、CloudWatch Logs 異常ディテクターおよび比較機能でも使用されます。詳細については、「[ログ異常検出](LogsAnomalyDetection.md)」および「[(diff) を以前の時間範囲と比較する](CWL_AnalyzeLogData_Compare.md)」を参照してください。 ## パターン分析の開始方法 パターン検出は、CloudWatch Logs Insights クエリで自動的に実行されます。`pattern` コマンドを含まないクエリは、結果にログイベントとパターンの両方を取得します。 `pattern` コマンドをクエリに含めると、一致するログイベントのセット全体に対してパターン分析が実行されます。これにより、より正確なパターン結果が得られますが、`pattern` コマンドの使用時に未加工のログイベントは返されません。クエリに `pattern` が含まれていない場合、パターン結果は、返された最初の 1000 個のログイベント、またはクエリで使用した制限値のいずれかに基づいて返されます。`pattern` をクエリに含めると、**[パターン]** タブに表示される結果は、クエリに一致するすべてのログイベントから取得されます。 **CloudWatch Logs Insights でパターン分析を開始するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[ログ]**、**[Logs Insights]** を選択します。 **[Logs Insights]** (ログのインサイト) ページでは、クエリエディタにデフォルトクエリが表示されます。デフォルトでは、最新の 20 件のログイベントが返されます。 1. クエリボックスの `| limit 20` 行を削除して、クエリを次のようにします。 ``` fields @timestamp, @message, @logStream, @log | sort @timestamp desc ``` 1. **[ロググループを選択]** ドロップダウンから、クエリを実行するロググループを 1 つ以上選択します。 1. (オプション) 時間間隔セレクタを使用して、クエリを実行する期間を選択します。 5 分および 30 分間隔、1 時間、3 時間、12 時間間隔、またはカスタム時間枠を選択できます。 1. **[クエリの実行]** を選択してクエリを開始します。 クエリの実行が完了すると、**[ログ]** タブにクエリによって返されたログイベントのテーブルが表示されます。表の上にあるのは、クエリに一致するレコードの数に関するメッセージです。これは、**一致する 71,101 レコードのうち 10,000 レコードを表示する**というメッセージと似ています。 1. **[パターン]** タブを選択します。 1. テーブルにクエリで検出されたパターンが表示されるようになりました。クエリには `pattern` コマンドが含まれていなかったため、このタブには、**[ログ]** タブのテーブルに表示された 10,000 個のログイベントで検出されたパターンのみが表示されます。 パターンごとに、次の情報が表示されます。 + **[パターン]** では、各動的トークンが `` として表示されます。*文字列*は、トークンが表すデータのタイプの説明です。*数値*は、他の動的トークンと比較して、このトークンがパターン内のどこに表示されるかを示します。 + **[イベント数]** は、クエリされたログイベントにパターンが表示された回数です。**[イベント数]** 列の見出しを選択して、パターンを頻度でソートします。 + **[イベント比率]** は、このパターンを含むクエリされたログイベントの割合です。 + **[重要度タイプ]** は、次のいずれかになります。 + パターンに **Error** という単語が含まれている場合は、**ERROR** です。 + パターンに **Warn** という単語が含まれているが、**Error** が含まれていない場合は **WARN** です。 + パターンに **Warn** または **Error** が含まれていない場合は **INFO** です。 **[Severity info]** 列の見出しを選択して、重要度別にパターンをソートします。 1. 次に、クエリを変更します。クエリの `| sort @timestamp desc` 行を `| pattern @message` に置き換えて、次のような完全なクエリにします。 ``` fields @timestamp, @message, @logStream, @log | pattern @message ``` 1. **[Run query]** (クエリの実行) を選択します。 クエリが終了すると、**[ログ]** タブに結果は表示されません。ただし、**[パターン]** タブには、クエリされたログイベントの合計数に応じて、リストされたパターンの数が多く表示される可能性があります。 1. クエリに `pattern` を含めるかどうかにかかわらず、クエリが返すパターンをさらに検査することができます。これを行うには、いずれかのパターンについて **[検査]** 列のアイコンを選択します。 **[パターン検査]** ペインが表示され、以下が表示されます。 + **[パターン]**。パターン内のトークンを選択して、そのトークンの値を分析します。 + クエリされた時間範囲におけるパターンの出現回数を示すヒストグラム。これにより、パターンの発生の急増など、興味深い傾向を特定できます。 + **[ログサンプル]** タブには、選択したパターンに一致するログイベントがいくつか表示されます。 + **[トークンの値]** タブには、選択している場合は、選択した動的トークンの値が表示されます。 **注記** トークンごとに最大 10 個のトークン値がキャプチャされます。トークン数は正確ではない可能性があります。CloudWatch Logs は確率カウンターを使用して、絶対値ではなくトークン数を生成します。 + **[関連パターン]** タブには、検査するパターンとほぼ同じ時間に頻繁に発生した他のパターンが表示されます。例えば、`ERROR` メッセージのパターンに通常、追加の詳細を含む `INFO` とマークされた別のログイベントが伴っていた場合、そのパターンがここに表示されます。 ## パターンコマンドの詳細 このセクションでは、`pattern` コマンドとその用途について詳しく説明します。 + 前のチュートリアルでは、`sort` コマンドの後に `pattern` コマンドが含まれている場合、クエリは有効ではないため、`pattern` コマンドを追加したときに `sort` コマンドを削除しました。`sort` の前に `pattern` があるのは有効です。 `pattern` 構文の詳細については、「[pattern](CWL_QuerySyntax-Pattern.md)」を参照してください。 + クエリで `pattern` を使用する場合、`@message` は `pattern` コマンドで選択されたフィールドの 1 つである必要があります。 + `pattern` コマンドの前に `filter` コマンドを含めると、フィルタリングされたログイベントのセットのみをパターン分析の入力として使用できます。 + `parse` コマンドから派生したフィールドなど、特定のフィールドのパターン結果を表示するには、`pattern @fieldname` を使用します。 + `stats` コマンドを使用したクエリなど、ログ以外の出力を持つクエリは、パターン結果を返しません。 # CloudWatch Logs Insights クエリの保存と再実行 作成したクエリは、後で再度実行できるように保存できます。保存したクエリは、フォルダ構造が保持されるため、整理された状態を保つことができます。アカウントごとに、リージョンあたり最大 1000 件保存できます。 クエリは、ユーザー固有のレベルではなく、リージョン固有のレベルに保存されます。クエリを作成して保存すると、同じリージョンで CloudWatch Logs にアクセスできる他のユーザーは、リージョンで保存されたすべてのクエリとそのフォルダ構造を表示できます。 クエリを保存するには、アクセス許可 `logs:PutQueryDefinition` を持つロールにログインする必要があります。保存されたクエリのリストを表示するには、アクセス許可 `logs:DescribeQueryDefinitions` を持つロールにログインする必要があります。 **注記** パラメータを使用してクエリを作成および保存できます。名前付きプレースホルダーを持つ再利用可能なテンプレートです。同じクエリの複数のバリエーションを異なる値で保存する代わりに、1 つのテンプレートを作成し、実行時に異なるパラメータ値を指定します。この機能は現在、Logs Insights クエリ言語を使用するクエリでのみサポートされています。詳細については、[「パラメータを使用した保存済みクエリの使用](#CWL_Insights-Parameterized-Queries)」を参照してください。 ------ #### [ Console ] **クエリを保存するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。 1. クエリエディタで、クエリを作成します。 1. **[保存]** を選択します。 1. クエリの名前を入力します。 1. (オプション) クエリを保存するフォルダを選択します。[**新規作成**] を選択して、フォルダを作成します。新しいフォルダを作成した場合、フォルダ名にスラッシュ (/) 文字を使用してフォルダ構造を定義できます。たとえば、新しいフォルダに **folder-level-1/folder-level-2** という名前を付けると、**folder-level-1** という最上位フォルダが作成され、そのフォルダ内に **folder-level-2** という別のフォルダが作成されます。クエリは **folder-level-2** に保存されます。 1. (オプション) クエリのロググループまたはクエリテキストを変更します。 1. (オプション) クエリでパラメータを使用するには、以下の追加ステップに従います。 1. **クエリにパラメータを追加します。**`{{parameter}}` 構文 (パラメータ名の前後に二重括弧) を使用して、静的値をプレースホルダーに置き換えます。 例: 静的な値を持つ元のクエリ: ``` fields @timestamp, @message | filter level = "Error" | filter applicationName = "OrderService" ``` パラメータでクエリを更新しました。 ``` fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}} ``` 1. **クエリで使用されるパラメータを定義します。**プレースホルダーパラメータごとに、以下を指定します。 + **名前**: プレースホルダー名と完全に一致する必要があります (例: `logLevel`、`applicationName`)。 + **デフォルト値** (オプション): パラメータ値が指定されていない場合に使用する値。 + **説明** (オプション): パラメータの目的について説明します。 1. パラメータを含むクエリを実行するには、`$`プレフィックスが付いたクエリ名を使用し、キーと値のペアとしてパラメータ名を渡します。詳細については**、「保存済みクエリを実行するには**」を参照してください。 1. **[保存]** を選択します。 ------ #### [ AWS CLI ] **クエリを保存するには**、 を使用します`put-query-definition`。 ``` aws logs put-query-definition \ --name "ErrorsByLevel" \ --query-string "fields @timestamp, @message | filter level = \"ERROR\"" \ --log-group-names "/aws/lambda/my-function" \ --region us-east-1 ``` (オプション) パラメータを含むクエリを保存するには、 `--parameters`オプションを追加し、クエリ文字列に`{{parameterName}}`プレースホルダーを使用します。 ``` aws logs put-query-definition \ --name "ErrorsByLevel" \ --query-string "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}" \ --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"},{"name":"applicationName","defaultValue":"OrderService","description":"Application name to filter"}]' \ --log-group-names "/aws/lambda/my-function" \ --region us-east-1 ``` クエリをフォルダに保存するには、クエリ名の前にフォルダパスを付けます。 ``` aws logs put-query-definition \ --name "my-folder/ErrorsByLevel" \ --query-string "fields @timestamp, @message | filter level = {{logLevel}}" \ --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"}]' \ --log-group-names "/aws/lambda/my-function" \ --region us-east-1 ``` ------ #### [ API ] **クエリを保存するには**、[PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html) を呼び出します。 ``` { "name": "ErrorsByLevel", "queryString": "fields @timestamp, @message | filter level = \"ERROR\"", "logGroupNames": ["/aws/lambda/my-function"] } ``` (オプション) パラメータを含むクエリを保存するには、 `parameters`フィールドを含め、クエリ文字列に`{{parameterName}}`プレースホルダーを使用します。 ``` { "name": "ErrorsByLevel", "queryString": "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}", "logGroupNames": ["/aws/lambda/my-function"], "parameters": [ { "name": "logLevel", "defaultValue": "ERROR", "description": "Log level to filter" }, { "name": "applicationName", "defaultValue": "OrderService", "description": "Application name to filter" } ] } ``` ------ **ヒント** `PutQueryDefinition` で保存したクエリー用のフォルダを作成することができます。保存したクエリ用のフォルダを作成するには、スラッシュ (/) を使用して、目的のクエリ名の前に目的のフォルダ名を付加します: `/`。このリソースの更新の詳細については、「[PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html)」を参照してください。 ------ #### [ Console ] **保存されたクエリを実行するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。 1. 右側の [**クエリ**] を選択します。 1. **保存済みクエリリストからクエリ**を選択します。クエリテキストがクエリエディタに表示されます。 1. (オプション) パラメータでクエリを使用するには: 1. **保存済みクエリのサイドパネルで、クエリ**名の横にある **\$1** アイコンを選択します。 1. パラメータを含むクエリがクエリエディタに表示されます。たとえば、 の横にある **\$1** アイコンを選択すると`ErrorsByLevel`、クエリエディタに次のように入力されます。 `$ErrorsByLevel(level=, applicationName=)` 1. パラメータの値 (レベル、applicationName) を指定し、クエリを実行します。例: `$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")` 1. **[Run]** (実行) を選択します。 ------ #### [ AWS CLI ] **パラメータを使用して保存されたクエリを実行するには** `$QueryName()` 構文`start-query`で を使用します。 ``` aws logs start-query \ --log-group-names "/aws/lambda/my-function" \ --start-time 1707566400 --end-time 1707570000 \ --query-string '$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")' \ --region us-east-1 ``` ------ #### [ API ] **パラメータを使用して保存されたクエリを実行するには** `queryString` フィールドの`$QueryName()`構文を使用して [StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html) を呼び出します。 ``` { "logGroupNames": ["/aws/lambda/my-function"], "startTime": 1707566400, "endTime": 1707570000, "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")" } ``` ------ **保存したクエリの新しいバージョンを保存するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。 1. 右側の [**クエリ**] を選択します。 1. [**保存されたクエリ**] リストからクエリを選択します。クエリエディタに表示されます。 1. クエリを修正します。作業を確認するために実行する必要がある場合は、[**クエリの実行**] を選択します。 1. 新しいバージョンを保存する準備ができたら、[**アクション**]、[**名前を付けて保存**] の順に選択します。 1. クエリの名前を入力します。 1. (オプション) クエリを保存するフォルダを選択します。[**新規作成**] を選択して、フォルダを作成します。新しいフォルダを作成した場合、フォルダ名にスラッシュ (/) 文字を使用してフォルダ構造を定義できます。たとえば、新しいフォルダに **folder-level-1/folder-level-2** という名前を付けると、**folder-level-1** という最上位フォルダが作成され、そのフォルダ内に **folder-level-2** という別のフォルダが作成されます。クエリは **folder-level-2** に保存されます。 1. (オプション) クエリのロググループまたはクエリテキストを変更します。 1. [**Save**] を選択します。 クエリを削除するには、`logs:DeleteQueryDefinition` アクセス許可を持つロールにログインする必要があります。 **保存したクエリを編集または削除するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。 1. 右側の [**クエリ**] を選択します。 1. [**保存されたクエリ**] リストからクエリを選択します。クエリエディタに表示されます。 1. [**アクション**]、[**編集**]、または [**アクション**]、[**削除**] を選択します。 ## パラメータを使用した保存済みクエリの使用 パラメータを含む保存されたクエリは、名前付きプレースホルダーを持つ再利用可能なクエリテンプレートです。ほぼ同一のクエリの複数のコピーを維持する代わりに、テンプレートを保存し、クエリの実行時に異なるパラメータ値を指定できます。パラメータは CloudWatch Logs Insights クエリ言語でのみサポートされます。 **仕組み** クエリを保存する場合、プレースホルダーはクエリ実行時に指定できる値を識別します。プレースホルダーは `{{parameterName}}`構文を使用します。以下は、 `logLevel`と の 2 つのパラメータ`ErrorsByLevel`を持つ という名前の保存済みクエリの例です`applicationName`。 ``` fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}} ``` 保存済みクエリを実行するには、 というプレフィックスが付いたクエリ名を使用してクエリを呼び出し`$`、パラメータ値を渡します。CloudWatch Logs Insights クエリエンジンは、各プレースホルダーを置き換えます。パラメータにデフォルト値が含まれている場合、他の値が指定されていない場合はそれらの値が使用されます。 ``` # Run query by using query name and passing parameter values explicitly $ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService") # Run query without specifying parameter values - default values are used in this case. $ErrorsByLevel() ``` スペースまたは特殊文字を含む保存されたクエリ名は、バックティックで囲む必要があります。 ``` $`Errors By Level`(logLevel = "WARN") ``` ### パラメータを含む保存済みクエリのサンプル **パラメータとして結果制限を追加する** クエリ名: パラメータ`ErrorsByLevel`付き `logLevel` (デフォルト: `"ERROR"`)、 `applicationName` (デフォルト: `"OrderService"`)、および `maxResults` (デフォルト: `50`) ``` fields @timestamp, @message, @logStream | filter level = {{logLevel}} | filter applicationName = {{applicationName}} | sort @timestamp desc | limit {{maxResults}} ``` ``` # Run the query using the query name and passing parameter values $ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService", maxResults = 100) ``` **パラメータで複数の保存されたクエリを使用する** 以下の例では、 `ErrorsByLevel`および として定義された 2 番目の保存`RecentN`済みクエリ `sort @timestamp desc | limit {{count}}` (パラメータ 、`count`デフォルト ) を使用します`20`。CloudWatch Logs Insights クエリエンジンは、各クエリを実行する前に展開します。 ``` # Using multiple queries with parameters in sequence $ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService") | $RecentN(count = 10) # Each of the queries is expanded, resulting in the following query when it is run. fields @timestamp, @message | filter level = "WARN" | filter applicationName = "OrderService" | sort @timestamp desc | limit 10 ``` ### クォータとエラー処理 **注記** 保存された各クエリには、最大 20 個のパラメータを含めることができます。 展開されたクエリ文字列は 10,000 文字を超えることはできません。パラメータ名は文字またはアンダースコアで始まる必要があります。保存されたクエリは、別の保存されたクエリを参照できません (ネストされた呼び出しはサポートされていません）。 **一般的なエラー** | エラー | 原因 | | --- | --- | | パラメータは CWLI クエリ言語でのみサポートされています | パラメータは CloudWatch Logs Insights クエリ言語でのみサポートされます。 | | queryString にない必須パラメータ | のパラメータ名には、クエリ文字列`{{placeholder}}`に一致するもの`--parameters`がありません。 | | パラメータ数が最大 20 を超えています | 保存されたクエリは現在、20 個のパラメータのみをサポートしています。 | | 重複するパラメータ名 | クエリ定義には、 に重複するパラメータがあります`parameters`。 | **注記** パラメータを使用して保存されたクエリを作成または更新するには、 アクセス`logs:PutQueryDefinition`許可が必要です。これを実行するには、 `logs:StartQuery`と が必要です`logs:DescribeQueryDefinitions`。 # クエリをダッシュボードに追加する、またはクエリ結果をエクスポートする クエリの実行後に、クエリを CloudWatch ダッシュボードに追加したり、クエリ結果をクリップボードにコピーしたりできます。 ダッシュボードに追加したクエリは、ダッシュボードをロードおよび更新するたびに再実行されます。これらのクエリは、100 件の同時 CloudWatch Logs Insights クエリの制限にカウントされます。 **クエリ結果をダッシュボードに追加するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。 1. 1 つ以上のロググループを選択し、クエリを実行します。 1. [**ダッシュボードに追加**] を選択します。 1. ダッシュボードを選択するか、[**新規作成**] を選択して、クエリ結果用のダッシュボードを作成します。 1. クエリ結果に使用するウィジェットの種類を選択します。 1. ウィジェットの名前を入力します。 1. [**ダッシュボードに追加**] を選択します。 **クエリ結果をクリップボードにコピーするか、クエリ結果をダウンロードするには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。 1. 1 つ以上のロググループを選択し、クエリを実行します。 1. [**結果のエクスポート**] を選択し、必要なオプションを選択します。 # 実行中のクエリまたはクエリ履歴を表示する 現在進行中のクエリや最近のクエリ履歴を表示できます。 現在実行中のクエリには、ダッシュボードに追加したクエリも含まれます。ダッシュボードに追加されたクエリを含め、アカウントあたり 100 件の同時 CloudWatch Logs Insights クエリに制限されます。さらに、OpenSearch Service PPL または OpenSearch Service SQL のいずれかに対して 15 OpenSearch の同時クエリを実行できます。 **最近のクエリ履歴を表示するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。 1. CloudWatch Logs コンソールに新しいデザインを使用する場合は、[**History (履歴)**] を選択します。古いデザインを使用している場合は、[**アクション**]、[**このアカウントのクエリ履歴を表示**] の順に選択します。 最近のクエリが一覧表示されます。クエリを選択して [**実行**] を選択すると、それらのいずれかを再度実行できます。 CloudWatch Logs では、[**Status (ステータス)**] の下に、現在実行中のクエリが [**In progress (進行中)**] と表示されます。 # でクエリ結果を暗号化する AWS Key Management Service デフォルトでは、CloudWatch Logs は、デフォルトの CloudWatch Logs サーバー側の暗号化方法を使用して CloudWatch Logs Insights クエリの保存済み結果を暗号化します。代わりに、 AWS KMS キーを使用してこれらの結果を暗号化することもできます。 AWS KMS キーを暗号化結果に関連付けると、CloudWatch Logs はそのキーを使用して、アカウント内のすべてのクエリの保存された結果を暗号化します。 後でクエリ結果からキーの関連付けを解除すると、CloudWatch Logs は、その後のクエリに対してデフォルトの暗号化方法を適用します。しかし、キーが関連付けられていたときに実行されたクエリは、そのキーで暗号化されたままになります。CloudWatch Logs は引き続きキーを参照できるため、KMS キーの関連付けが解除された後も CloudWatch Logs はそれらの結果を返すことができます。ただし、キーを後で無効にすると、CloudWatch Logs はそのキーで暗号化されたクエリ結果を読み取ることができなくなります。 **重要** CloudWatch Logs は、対称 KMS キーのみをサポートします。クエリ結果の暗号化に非対称キーを使用しないでください。詳細については、「[対称キーと非対称キーの使用](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)」を参照してください。 ## 制限 + 以下の手順を実行するには、`kms:CreateKey`、`kms:GetKeyPolicy`、および `kms:PutKeyPolicy` アクセス許可が必要です。 + キーとクエリ結果を関連付けた後、または関連付けを解除した後、オペレーションが有効になるまで最大 5 分かかることがあります。 + 関連付けられたキーへの CloudWatch Logs のアクセスを取り消した場合、または関連付けられた KMS キーを削除した場合、CloudWatch Logs 内の暗号化されたデータを取得できなくなります。 + CloudWatch コンソールを使用してキーを関連付けることはできません。 AWS CLI  または CloudWatch Logs API を使用する必要があります。 ## ステップ 1: を作成する AWS KMS key KMS キーを作成するには、次の [create-key](https://docs.aws.amazon.com/cli/latest/reference/kms/create-key.html) コマンドを使用します。 ``` aws kms create-key ``` 出力には、キーのキー ID と Amazon リソースネーム (ARN) が含まれます。出力例を次に示します。 ``` { "KeyMetadata": { "Origin": "AWS_KMS", "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "Description": "", "KeyManager": "CUSTOMER", "Enabled": true, "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT", "KeyUsage": "ENCRYPT_DECRYPT", "KeyState": "Enabled", "CreationDate": 1478910250.94, "Arn": "arn:aws:kms:us-west-2:123456789012:key/6f815f63-e628-448c-8251-e40cb0d29f59", "AWSAccountId": "123456789012", "EncryptionAlgorithms": [ "SYMMETRIC_DEFAULT" ] } } ``` ## ステップ 2: KMS キーでアクセス許可を設定する デフォルトでは、すべての KMS キーはプライベートです。リソースの所有者のみがその CMK を使用してデータを暗号化および復号できます。ただし、リソース所有者は、他のユーザーとリソースにキーへのアクセス許可を付与することができます。このステップでは、CloudWatch Logs サービスプリンシパルに、キーを使用するアクセス許可を付与します。このサービスプリンシパルは、キーが保存されているリージョンと同じ AWS リージョンにある必要があります。 ベストプラクティスとして、キーの使用は、指定した AWS アカウントのみに制限することをお勧めします。 まず、[get-key-policy](https://docs.aws.amazon.com/cli/latest/reference/kms/get-key-policy.html) コマンドを使用して、KMS キーのデフォルトポリシーを `policy.json` として保存します。 ``` aws kms get-key-policy --key-id key-id --policy-name default --output text > ./policy.json ``` テキストエディタで `policy.json` ファイルを開き、以下のいずれかのステートメントから太字のセクションを追加します。既存のステートメントと新しいステートメントをカンマで区切ります。これらのステートメントでは、 `Condition`セクションを使用して AWS KMS キーのセキュリティを強化します。詳細については、「[AWS KMS キーと暗号化コンテキスト](encrypt-log-data-kms.md#encrypt-log-data-kms-policy)」を参照してください。 この例の `Condition`セクションでは、 AWS KMS キーの使用を、指定されたアカウントの CloudWatch Logs Insights クエリ結果に制限します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "key-default-1", "Statement": [ { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:root" }, "Action": "kms:*", "Resource": "*" }, { "Effect": "Allow", "Principal": { "Service": "logs.region.amazonaws.com" }, "Action": [ "kms:Encrypt*", "kms:Decrypt*", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:Describe*" ], "Resource": "*", "Condition": { "ArnEquals": { "aws:SourceArn": "arn:aws:logs:us-east-1:111122223333:query-result:*" }, "StringEquals": { "aws:SourceAccount": "111122223333" } } } ] } ``` ------ 最後に、次の [put-key-policy](https://docs.aws.amazon.com/cli/latest/reference/kms/put-key-policy.html) コマンドを使用して更新されたポリシーを追加します。 ``` aws kms put-key-policy --key-id key-id --policy-name default --policy file://policy.json ``` ## ステップ 3: KMS キーをクエリ結果に関連付ける **KMS キーをアカウントのクエリ結果に関連付けるには** 次のように、[disassociate-kms-key](https://docs.aws.amazon.com/cli/latest/reference/logs/disassociate-kms-key.html) コマンドを使用します。 ``` aws logs associate-kms-key --resource-identifier "arn:aws:logs:region:account-id:query-result:*" --kms-key-id "key-arn" ``` ## ステップ 4: アカウントのクエリ結果からキーの関連付けを解除する クエリ結果に関連付けられた KMS キーの関連付けを解除するには、次の [disassociate-kms-key](https://docs.aws.amazon.com/cli/latest/reference/logs/disassociate-kms-key.html) コマンドを使用します。 ``` aws logs disassociate-kms-key --resource-identifier "arn:aws:logs:region:account-id:query-result:*" ``` # CloudWatch Logs Insights クエリ結果から自然言語の概要を生成する アプリケーションの動作を理解するにはログデータを分析することが重要ですが、大量のログエントリを解釈するには時間がかかる場合があります。CloudWatch Logs Insights は、複雑なクエリ結果を明確で簡潔な要約に変換する自然言語の要約機能を提供できるようになりました。この機能は、問題をすばやく特定し、ログデータから実用的なインサイトを得るのに役立ちます。 ## 仕組み CloudWatch Logs Insights は、Amazon Bedrock を使用してクエリ結果から人間が読み取れる概要を生成できます。この機能は、すべての CloudWatch Logs Insights クエリ言語をサポートし、ログデータから明確で実用的なインサイトを提供します。 ## リージョンの可用性とデータ処理 **重要** この機能を使用すると、クエリ結果が別の AWS リージョンで処理される場合があります。例えば、米国東部 (バージニア北部) でクエリを実行すると、要約が米国西部 (オレゴン) で発生する可能性があります。 次の表は、クエリ結果機能が使用可能な AWS リージョン さまざまな地域で処理可能な処理の一覧です。 | サポートされている CloudWatch Logs の地域 | 処理される可能性があるリージョン | | --- | --- | | [米国 (US)] | US East (N. Virginia) Region 米国東部 (オハイオ) リージョン 米国西部 (オレゴン) リージョン | | 欧州 | 欧州 (フランクフルト) リージョン 欧州 (アイルランド) リージョン 欧州 (パリ) リージョン 欧州 (ストックホルム) リージョン 欧州 (ロンドン) リージョン | | アジアパシフィック | US East (N. Virginia) Region 米国東部 (オハイオ) リージョン 米国西部 (オレゴン) リージョン | | 南米 | US East (N. Virginia) Region 米国東部 (オハイオ) リージョン 米国西部 (オレゴン) リージョン | ## 開始方法 **自然言語の概要を生成するには** 1. CloudWatch Logs Insights のクエリを実行します。 1. クエリが完了したら、**[結果の要約]** を選択します。 ## アクセス許可 以下のいずれかが必要です。 + `CloudWatchLogsFullAccess` アクセス許可 + `CloudWatchLogsReadOnlyAccess` アクセス許可 + `cloudwatch:GenerateQueryResultsSummary`、`logs:GetQueryResults`、`logs:DescribeQueries`、`logs:FilterLogEvents` アクションを含むカスタム IAM ポリシー ## データプライバシー クエリ結果は安全に処理され、CloudWatch Logs Insights または Amazon Bedrock のトレーニングや改善には使用されません。フィードバックボタンを使用してクエリ結果の概要に関するフィードバックを提供する場合、フィードバックは CloudWatch Logs Insights で提供される機能に対する満足度を示します。