本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 计划查询入门
创建计划查询时，您将配置几个关键组件，这些组件定义查询的运行方式和结果的交付位置。了解这些组件将有助于您设置有效的自动日志分析。
每个定时查询都包含以下关键组件：
**查询配置**
用于分析的 Lo CloudWatch gs Insights 查询字符串、目标日志组和查询语言。
**计划表达式**
用于定义查询何时运行的 cron 表达式或频率日历。您可以指定时区设置以确保查询在正确的本地时间运行。控制台会显示人类可读的日程安排描述，例如 “在每周二 15:10 运行查询，时间范围为 5 分钟，在 UTC 立即生效，直至无限期。”
**时间范围**
每次查询执行的回顾周期，由与执行时间的起始时间偏移量定义。这决定了每次执行查询将分析多少历史数据。
**执行计划预览**
控制台显示接下来的三次计划查询运行以及确切的日期和时间（例如，2025/10/28 15:10，UTC；2025/11/04 15:10，UTC；2025/11/11 15:10，UTC），帮助您验证计划配置是否正确。
**目标**
成功执行后传送查询结果的地方。支持的目标包括 Amazon S3 存储桶，默认情况下，结果元数据会发送到默认事件总线。
**执行角色**
L CloudWatch ogs 代入的 IAM 角色来执行查询并将结果传送到指定目的地。
在创建计划查询之前，请确保您已配置必要的权限和资源。
# 创建计划查询
创建计划查询，自动运行 L CloudWatch ogs Insights 查询并将结果传送到您选择的目的地。
## 先决条件
在创建计划查询之前，请确保您具备以下条件：
+ **日志组**-包含要分析的数据的一个或多个日志组
+ **执行 IAM 角色**-具有以下权限的 IAM 角色：
+ `logs:StartQuery`-启动 CloudWatch 日志见解查询的权限
+ `logs:GetQueryResults`-检索查询结果的权限
+ `logs:DescribeLogGroups`-访问日志组信息的权限。只有基于前缀的日志组才需要这样做，以便发现日志组
+ **目的地权限**-您所选目的地的其他 IAM 权限：
+ 对于亚马逊 S3 目的地：`s3:PutObject`
+ **fo AWS CLI r 和 API 用法**-配置了具有调用 CloudWatch 日志权限的 AWS 凭证 APIs
有关详细的 IAM 策略示例，请参阅[Amazon CloudWatch 日志的身份和访问管理](auth-and-access-control-cwl.md)。另外需要注意的是，每个账户只能有 1000 个预定查询。
------
#### [ Console ]
**创建计划查询（控制台）**
1. 在[https://us-east-1.console.aws.amazon.com/cloudwatch/家打开 CloudWatch 日志控制台？ region=us-east-1 \$1logsv2: Logs-Insigh](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights)
1. 在导航窗格中，选择**日志、见解**。
1. 选择 “**创建计划查询”**。
1. 在 “**查询定义**” 部分中：
1. 对于**查询语言**，请从列表中选择要使用的查询语言。
1. 对于**查询字符串**，在框中输入您的 CloudWatch Logs Insights 查询。
1. 对于**日志组**，请从列表中选择要查询的日志组。
1. 在 “**时间表设置**” 部分：
1. 对于**计划表达式**，请配置查询的运行时间。从预定义的选项中选择或输入自定义 cron 表达式。
1. 对于 “**创建时生效**”，请指定计划何时生效。选择立即开始或使用YYYY/MM/DD格式在特定的日期和时间开始。
1. 在 “**时间范围**” 中，指定每次执行查询的回顾周期。输入以分钟为单位的持续时间，该持续时间定义了从执行时间向后多久进行查询。
1. 对于**无限期继续**，请指定计划何时结束。使用YYYY/MM/DD格式选择无限期运行或直到特定的日期和时间运行。
1. 控制台将根据您的配置显示接下来的三次计划查询运行，并以 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 S3 的 IAM 角色**” 部分中，选择以下选项之一：
1. 选择 “**自动创建具有默认权限的新角色**”，以自动设置一个 IAM 角色，该角色具有 CloudWatch 日志将查询结果传送到 Amazon S3 所需的权限。
1. 选择**使用现有角色选择一个现有** IAM 角色，该角色具有将查询结果传送到 Amazon S3 所需的 CloudWatch 日志策略。使用搜索字段从列表中查找并选择相应的 IAM 角色。
1. 在**用于计划查询执行的 IAM 角色**部分，选择以下选项之一：
1. 选择 “**自动创建具有默认权限的新角色”**，以自动设置一个 IAM 角色，该角色具有 CloudWatch 日志执行计划查询所需的权限。
1. 选择**使用现有角色**选择具有 CloudWatch 日志执行计划查询所需策略的现有 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`操作创建新的计划查询。以下示例创建了每小时运行一次的计划查询：
```
{
"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 会显示您的所有计划查询及其名称、创建日期、上次运行状态、上次触发时间和重复频率。
# 查看和管理计划查询
每个查询都有以下信息：
**Name**
您为计划查询分配的唯一名称。选择名称以查看详细的配置和执行历史记录。
**创建日期**
计划查询的创建日期，以 YYYY-MM-DD格式显示。
**上次运行的状态**
最近运行的查询的执行状态。可能的值包括：
+ **完成**-查询成功执行，结果已传送到所有已配置的目的地。
+ **失败**-查询执行或结果传送失败。查看执行历史以了解错误详情。
+ **查询无效**-查询无效且存在语法问题
+ **超时**-查询已超时。查询在 60 分钟后自动超时
**上次触发时间**
上次执行查询的日期和时间，以 YYYY-MM-DD HH: MM: SS 格式显示。如果查询尚未运行，则显示 “**从**不”。
**重复每个**
查询的计划频率。对于使用 cron 表达式的查询，显示**自定义**，对于更简单的日程安排，则显示特定的频率描述。
“**计划查询**” 页面概述了您的所有计划查询，显示了它们的当前状态和执行历史记录，以便您可以从一个集中位置查看、监控和管理所有计划查询。使用此信息来监控查询性能、发现问题并管理您的自动日志分析工作流程。
------
#### [ Console ]
**查看计划查询（控制台）**
1. 在[https://us-east-1.console.aws.amazon.com/cloudwatch/家打开 CloudWatch 日志控制台？ region=us-east-1 \$1logsv2: Logs-Insigh](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights)
1. 在 CloudWatch 日志控制台中，选择**计划查询**、**查看计划查询**。
------
#### [ AWS CLI ]
**列出计划查询 (AWS CLI)**
+ 使用`list-scheduled-queries`命令列出所有计划查询：
```
aws logs list-scheduled-queries --max-results 10
```
------
#### [ API ]
**列出计划查询 (API)**
+ 使用`ListScheduledQueries`操作检索所有计划查询：
```
{
"maxResults": 10
}
```
------
**计划查询**页面标题显示您账户中的计划查询总数，帮助您跟踪使用情况并有效地管理自动日志分析工作流程。
# 查看计划查询执行历史记录
使用执行历史记录来监控计划查询的性能，并解决查询执行或结果交付方面的任何问题。
执行历史记录显示每次查询运行的状态，包括成功执行、失败和目标处理结果。您可以使用这些信息来识别模式、诊断问题并验证查询是否按预期运行。
------
#### [ Console ]
**查看执行历史记录（控制台）**
1. 在 CloudWatch 日志控制台中，选择**计划查询**、**查看计划查询**。
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 日志控制台中，选择**计划查询**、**查看计划查询**。
1. 选择要更新的计划查询。
1. 选择**编辑**。
1. 根据需要修改配置。
1. 选择**保存更改**。
------
#### [ 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"
}
}
}
```
------