翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# スケジュールされたクエリの開始方法
スケジュールされたクエリを作成するときは、クエリの実行方法と結果の配信場所を定義するいくつかの主要なコンポーネントを設定します。これらのコンポーネントを理解することは、効果的な自動ログ分析を設定するのに役立ちます。
スケジュールされた各クエリは、次の主要なコンポーネントで構成されます。
**クエリ設定**
分析に使用する CloudWatch Logs Insights クエリ文字列、ターゲットロググループ、およびクエリ言語。
**スケジュール式**
クエリが実行されるタイミングを定義する cron 式または頻度カレンダー。タイムゾーン設定を指定して、クエリが正しい現地時刻に実行されるようにできます。コンソールには、「毎週火曜日の 15:10 にクエリを 5 分間実行し、すぐに UTC で無期限に有効」など、人間が読めるようにスケジュールの説明が表示されます。
**時間範囲**
各クエリ実行のルックバック期間。実行時間と開始時間のオフセットで定義されます。これにより、各クエリ実行が分析する履歴データの量を決定します。
**実行スケジュールのプレビュー**
コンソールには、正確な日付と時刻 ( 15:10、UTC、2025/10/28 2025/11/0415:10、UTC、2025/11/11 15:10、UTC など) を含む次の 3 つのスケジュールされたクエリ実行が表示され、スケジュールが正しく設定されていることを確認するのに役立ちます。
**送信先**
ここで、クエリ結果は正常に実行された後に配信されます。サポートされている送信先には Amazon S3 バケットが含まれ、デフォルトでは結果メタデータがデフォルトのイベントバスに送信されます。
**実行ロール**
CloudWatch Logs がクエリを実行し、指定された送信先に結果を配信するために引き受ける IAM ロール。
スケジュールされたクエリを作成する前に、必要なアクセス許可とリソースが設定されていることを確認してください。
# スケジュールされたクエリの作成
CloudWatch Logs Insights クエリを自動的に実行し、選択した送信先に結果を配信するスケジュールされたクエリを作成します。
## 前提条件
スケジュールされたクエリを作成する前に、以下があることを確認してください。
+ **ロググループ** - 分析するデータを含む 1 つ以上のロググループ
+ **実行 IAM ロール** - 次のアクセス許可を持つ IAM ロール。
+ `logs:StartQuery` - CloudWatch Logs Insights クエリを開始するアクセス許可
+ `logs:GetQueryResults` - クエリ結果を取得するアクセス許可
+ `logs:DescribeLogGroups` - ロググループ情報にアクセスするためのアクセス許可。これは、ロググループ検出のプレフィックスベースのロググループにのみ必要です。
+ **送信先アクセス**許可 - 選択した送信先に対する追加の IAM アクセス許可:
+ Amazon S3 の送信先の場合: `s3:PutObject`
+ ** AWS CLI および API の使用** - CloudWatch Logs APIsを呼び出すアクセス許可を持つ AWS 認証情報を設定
IAM ポリシーの詳細な例については、「」を参照してください[Amazon CloudWatch Logs の Identity and Access Management](auth-and-access-control-cwl.md)。また、アカウントごとにスケジュールされたクエリは 1,000 件のみです。
------
#### [ Console ]
**スケジュールされたクエリを作成するには (コンソール)**
1. で CloudWatch Logs コンソールを開きますか? [https://us-east-1.console.aws.amazon.com/cloudwatch/homeregion=us-east-1\$1logsV2:logs-insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights)。
1. ナビゲーションペインで、**Logs Insights** を選択します。
1. **スケジュールされたクエリの作成**を選択します。
1. **クエリ定義**セクションで、次の操作を行います。
1. **クエリ言語** で、リストから使用するクエリ言語を選択します。
1. **クエリ文字列**には、ボックスに CloudWatch Logs Insights クエリを入力します。
1. **ロググループ**で、リストからクエリするロググループを選択します。
1. **「スケジュール設定**」セクションで、次の操作を行います。
1. **スケジュール式**では、クエリが実行されるタイミングを設定します。事前定義されたオプションから選択するか、カスタム cron 式を入力します。
1. **「作成時に有効**」で、スケジュールがいつアクティブになるかを指定します。すぐに開始するか、YYYY/MM/DD 形式を使用して特定の日時から開始するかを選択します。
1. **時間範囲**には、各クエリ実行のルックバック期間を指定します。実行時間からクエリまでの時間を定義する時間を分単位で入力します。
1. **「無期限に続行する**」で、スケジュールの終了時刻を指定します。無期限に実行するか、YYYY/MM/DD 形式を使用して特定の日時まで実行するかを選択します。
1. コンソールには、設定に基づいて次の 3 つのスケジュールされたクエリ実行が表示され、クエリが実行される正確な日時が UTC で表示されます。
1. 「クエリ**結果を S3 に投稿する - オプション**」セクション (S3 送信先を使用している場合):
1. **S3 バケット**の場合、送信先バケットが同じアカウントにある場合は**この** AWS アカウントを選択し、バケットが別の AWS アカウントにある場合は**別の**アカウントを選択し、バケット所有アカウントのアカウント ID を入力として指定します。
1. **Amazon S3 URI** の場合は、結果が保存される Amazon S3 バケットとプレフィックス (例: ) を入力します`s3://my-bucket/query-results/`。**このアカウント**を選択した場合は、**Amazon S3 の参照**を選択して移動し、既存の Amazon S3 の場所を選択できます。
1. (オプション) **KMS キー ARN** には、カスタマーマネージド AWS KMS キーの ARN を入力して、SSE-KMS を使用してクエリ結果を暗号化します。キーは、送信先の Amazon S3 バケットと同じ AWS リージョンにある必要があります。
1. Amazon **Amazon S3ロール**セクションで、次のいずれかのオプションを選択します。
1. **デフォルトのアクセス許可を持つ新しいロールの自動作成**を選択すると、CloudWatch Logs がクエリ結果を Amazon S3 に配信するために必要なアクセス許可を持つ IAM ロールが自動的に設定されます。
1. **既存のロールを使用して**、CloudWatch Logs がクエリ結果を Amazon S3 に配信するために必要なポリシーを持つ既存の IAM ロールを選択します。検索フィールドを使用して、リストから適切な IAM ロールを検索して選択します。
1. **スケジュールされたクエリ実行の IAM ロール**セクションで、次のいずれかのオプションを選択します。
1. **デフォルトのアクセス許可を持つ新しいロールを自動作成**を選択して、CloudWatch Logs がスケジュールされたクエリを実行するために必要なアクセス許可を持つ IAM ロールを自動的にセットアップします。
1. **既存のロールを使用して**、CloudWatch Logs がスケジュールされたクエリを実行するために必要なポリシーを持つ既存の IAM ロールを選択します。検索フィールドを使用して、リストから適切な IAM ロールを検索して選択します。
1. **スケジュールの作成**を選択して、スケジュールされたクエリを作成します。
------
#### [ AWS CLI ]
**スケジュールされたクエリを作成するには (AWS CLI)**
+ `create-scheduled-query` コマンドを使用して、新しいスケジュールされたクエリを作成します。
```
aws logs create-scheduled-query \
--name "ErrorAnalysisQuery" \
--query-language "CWLI" \
--query-string "fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m)" \
--schedule-expression "cron(8 * * * ? *)" \
--execution-role-arn "arn:aws:iam::123456789012:role/CloudWatchLogsScheduledQueryRole" \
--log-group-identifiers "/aws/lambda/my-function" "/aws/apigateway/my-api" \
--state "ENABLED"
```
------
#### [ API ]
**スケジュールされたクエリを作成するには (API)**
+ `CreateScheduledQuery` アクションを使用して、新しいスケジュールされたクエリを作成します。次の例では、1 時間ごとに実行されるスケジュールされたクエリを作成します。
```
{
"name": "ErrorAnalysisQuery",
"queryLanguage": "CWLI",
"queryString": "fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m)",
"scheduleExpression": "cron(8 * * * ? *)",
"executionRoleArn": "arn:aws:iam::123456789012:role/CloudWatchLogsScheduledQueryRole",
"logGroupIdentifiers": ["/aws/lambda/my-function", "/aws/apigateway/my-api"],
"state": "ENABLED"
}
```
------
スケジュールされたクエリを作成したら、**スケジュールされたクエリ**ページから ListScheduledQueries API を使用してクエリを表示および管理できます。この API には、スケジュールされたすべてのクエリの名前、作成日、最終実行のステータス、最終トリガー時間、繰り返し頻度が表示されます。
# スケジュールされたクエリの表示と管理
クエリごとに以下の情報を使用できます。
**名前**
スケジュールされたクエリに割り当てた一意の名前。詳細設定と実行履歴を表示するには、名前を選択します。
**作成日**
スケジュールされたクエリが作成された日付。YYYY-MM-DD 形式で表示されます。
**最終実行のステータス**
最新のクエリ実行の実行ステータス。可能な値は以下のとおりです:
+ **完了** - クエリが正常に実行され、結果が設定されたすべての送信先に配信されました。
+ **Failed** - クエリの実行または結果の配信に失敗しました。エラーの詳細については、実行履歴を確認してください。
+ **無効なクエリ** - クエリが無効で構文上の問題があります
+ **タイムアウト** - クエリがタイムアウトしました。クエリは 60 分後に自動的にタイムアウトします
**最後にトリガーされた時刻**
クエリが最後に実行された日時。YYYY-MM-DD HH:MM:SS 形式で表示されます。クエリがまだ実行されていない場合は****「Never」と表示されます。
**ごとに繰り返す**
クエリのスケジュール頻度。cron 式を使用するクエリの**カスタム**、またはより簡単なスケジュールの特定の頻度の説明を表示します。
**スケジュールされたクエリ**ページには、スケジュールされたすべてのクエリの概要が表示され、現在のステータスと実行履歴が表示されるため、スケジュールされたすべてのクエリを一元的に表示、モニタリング、管理できます。この情報を使用して、クエリのパフォーマンスのモニタリング、問題の特定、自動ログ分析ワークフローの管理を行います。
------
#### [ Console ]
**スケジュールされたクエリを表示するには (コンソール)**
1. で CloudWatch Logs コンソールを開きますか? [https://us-east-1.console.aws.amazon.com/cloudwatch/homeregion=us-east-1\$1logsV2:logs-insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights)。
1. CloudWatch Logs コンソールで、**スケジュールされたクエリ**、**スケジュールされたクエリの表示**を選択します。
------
#### [ AWS CLI ]
**スケジュールされたクエリを一覧表示するには (AWS CLI)**
+ `list-scheduled-queries` コマンドを使用して、スケジュールされたすべてのクエリを一覧表示します。
```
aws logs list-scheduled-queries --max-results 10
```
------
#### [ API ]
**スケジュールされたクエリを一覧表示するには (API)**
+ `ListScheduledQueries` アクションを使用して、スケジュールされたすべてのクエリを取得します。
```
{
"maxResults": 10
}
```
------
**スケジュールされたクエリ**ページヘッダーには、アカウントでスケジュールされたクエリの合計数が表示され、使用状況を追跡し、自動ログ分析ワークフローを効果的に管理できます。
# スケジュールされたクエリ実行履歴の表示
実行履歴を使用して、スケジュールされたクエリのパフォーマンスをモニタリングし、クエリの実行または結果配信に関する問題をトラブルシューティングします。
実行履歴には、成功した実行、失敗、送信先処理結果など、各クエリ実行のステータスが表示されます。この情報を使用して、パターンの特定、問題の診断、クエリが正常に実行されていることの検証を行うことができます。
------
#### [ Console ]
**実行履歴を表示するには (コンソール)**
1. CloudWatch Logs コンソールで、**スケジュールされたクエリ**、**スケジュールされたクエリの表示**を選択します。
1. 検査するスケジュールされたクエリを選択します。
1. [**Execution history (実行履歴の表示)**] タブを選択します。
------
#### [ AWS CLI ]
**実行履歴を表示するには (AWS CLI)**
1. `get-scheduled-query-history` コマンドを使用して、スケジュールされたクエリの実行履歴を取得します。
```
aws logs get-scheduled-query-history \
--identifier "DailyErrorMonitoring" \
--start-time 1743379200 \
--end-time 1743465600 \
--max-results 10
```
1. 実行ステータスでフィルタリングするには、 `--execution-statuses`パラメータを追加します。
```
aws logs get-scheduled-query-history \
--identifier "DailyErrorMonitoring" \
--start-time 1743379200 \
--end-time 1743465600 \
--max-results 1 \
--execution-statuses "SUCCEEDED"
```
------
#### [ API ]
**実行履歴を表示するには (API)**
+ `GetScheduledQueryHistory` アクションを使用して実行履歴を取得します。
```
{
"identifier": "DailyErrorMonitoring",
"startTime": 1743379200,
"endTime": 1743465600,
"maxResults": 10,
"executionStatuses": ["SUCCEEDED", "FAILED"]
}
```
------
実行履歴には以下が表示されます。
+ **実行ステータス** - 実行中、完了、失敗、タイムアウト、または InvalidQuery
+ **トリガー時間** - クエリが実行された時刻
+ **送信先** - S3 や EventBridge など、設定された各送信先の処理ステータス
+ **エラーメッセージ** - クエリの実行または送信先処理の失敗に関する詳細
# スケジュールされたクエリの更新
スケジュールされたクエリ設定を変更して、要件の進化に応じてクエリ文字列、スケジュール、送信先、または実行ロールを変更します。
クエリ文字列、スケジュール式、送信先、実行ロールなど、スケジュールされたクエリの任意の側面を更新できます。変更は、今後の実行ですぐに有効になります。
------
#### [ Console ]
**スケジュールされたクエリを更新するには (コンソール)**
1. CloudWatch Logs コンソールで、**スケジュールされたクエリ**、**スケジュールされたクエリの表示**を選択します。
1. 更新するスケジュールされたクエリを選択します。
1. **[編集]** を選択します。
1. 必要に応じて設定を変更します。
1. **[Save changes]** (変更の保存) をクリックします。
------
#### [ AWS CLI ]
**スケジュールされたクエリを更新するには (AWS CLI)**
+ `update-scheduled-query` コマンドを使用して、既存のスケジュールされたクエリを変更します。
```
aws logs update-scheduled-query \
--identifier "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f" \
--description "Monitor for ERROR level logs daily" \
--query-language "LogsQL" \
--query-string "fields @timestamp, @message | filter @message like /ERROR/" \
--log-group-identifiers "/aws/lambda/my-function-1" "/aws/lambda/my-function-2"
```
------
#### [ API ]
**スケジュールされたクエリを更新するには (API)**
1. `UpdateScheduledQuery` アクションを使用して、スケジュールされたクエリ設定を変更します。
```
{
"identifier": "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f",
"queryString": "fields @timestamp, @message | filter @message like /WARNING|ERROR/ | stats count() by bin(5m)",
"scheduleExpression": "cron(0 */2 * * ? *)",
"state": "ENABLED"
}
```
1. 複数の設定パラメータを一度に更新するには:
```
{
"identifier": "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f",
"queryString": "fields @timestamp, @message, @level | filter @level = 'ERROR'",
"scheduleExpression": "cron(0 8,12,16 * * ? *)",
"executionRoleArn": "arn:aws:iam::111122223333:role/UpdatedScheduledQueryRole",
"logGroupIdentifiers": ["/aws/lambda/my-function", "/aws/lambda/another-function"],
"destinationConfiguration": {
"s3Configuration": {
"destinationIdentifier": "s3://111122223333-sqn-results-bucket/processed-results",
"roleArn": "arn:aws:iam::111122223333:role/Admin"
}
}
}
```
------