保存并重新运行 L CloudWatch ogs Insights 查询

创建查询后，可以将其保存，以便稍后再次运行查询。查询将以文件夹结构保存，因此您可以组织它们。每个账户每个区域可以保存多达 1000 个查询。

查询保存在某个 Region-specific 级别上，而不是用户特定的级别上。如果您创建并保存查询，则有权访问同一区域中的 CloudWatch 日志的其他用户可以查看该区域中所有保存的查询及其文件夹结构。

要保存查询，您必须登录到具有 logs:PutQueryDefinition 权限的角色。要查看已保存查询的列表，您必须登录到具有 logs:DescribeQueryDefinitions 权限的角色。

注意

您可以创建和保存带有参数的查询，即带有命名占位符的可重复使用的模板。与其使用不同的值保存同一个查询的多个变体，不如创建一个模板并在运行时提供不同的参数值。目前，仅使用 Logs Insights 查询语言的查询支持此功能。有关更多信息，请参阅使用带参数的已保存查询。

Console

保存查询

在处打开 CloudWatch 控制台https://console.aws.amazon.com/cloudwatch/。
在导航窗格中，选择 Logs（日志），然后选择 Logs Insights（日志洞察）。
在查询编辑器中，创建查询。
选择保存。
输入查询的名称。
（可选）选择要保存查询的文件夹。选择 Create new（新建）以创建文件夹。如果创建新文件夹，则可以在文件夹名称中使用斜杠（/）字符来定义文件夹结构。例如，命名新文件夹 folder-level-1/folder-level-2 会创建一个名为 folder-level-1 的顶级文件夹，并在该文件夹中创建另一个名为 folder-level-2 的文件夹。查询保存在 folder-level-2 中。
（可选）更改查询的日志组或查询文本。
（可选）要在查询中使用参数，请执行以下额外步骤：
1. 为您的查询添加参数。使用{{parameter}}语法（参数名称前后的双大括号）将静态值替换为占位符。
  
  示例：带有静态值的原始查询：
```
fields @timestamp, @message
| filter level = "Error"
| filter applicationName = "OrderService"
```
  使用参数更新了查询：
```
fields @timestamp, @message
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}
```
2. 定义查询中使用的参数。对于每个占位符参数，指定：
  - 名称：必须与占位符名称完全匹配（例如，logLevel，applicationName）。
  - 默认值（可选）：未提供参数值时使用的值。
  - 描述（可选）：解释参数的用途。
3. 通过使用带$前缀的查询名称并将参数名称作为键值对传递，可以运行带参数的查询。有关详细信息，请参见运行已保存的查询。
选择保存。

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：


{
  "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 为保存的查询创建文件夹。要为保存的查询创建文件夹，请使用正斜杠（/）在所需的查询名称前加上所需的文件夹名称：<folder-name>/<query-name>。有关此操作的更多信息，请参阅PutQueryDefinition。

Console

运行保存的查询

在处打开 CloudWatch 控制台https://console.aws.amazon.com/cloudwatch/。
在导航窗格中，选择 Logs（日志），然后选择 Logs Insights（日志洞察）。
在右侧，选择 Queries（查询）。
从 “保存的查询” 列表中选择您的查询。查询文本出现在查询编辑器中。
（可选）要使用带参数的查询，请执行以下操作：
1. 在 “已保存的查询” 侧面板中，选择查询名称旁边的 + 图标。
2. 带参数的查询出现在查询编辑器中。例如，如果您选择旁边的 + 图标ErrorsByLevel，则查询编辑器将填充：$ErrorsByLevel(level=, applicationName=)
3. 提供参数（级别、应用程序名称）的值并运行查询。例如：$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")
选择运行。

AWS CLI

使用参数运行已保存的查询

start-query使用以下$QueryName()语法：


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

使用参数运行已保存的查询

StartQuery使用queryString字段中的$QueryName()语法调用：


{
  "logGroupNames": ["/aws/lambda/my-function"],
  "startTime": 1707566400,
  "endTime": 1707570000,
  "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")"
}

保存已保存查询的新版本

在处打开 CloudWatch 控制台https://console.aws.amazon.com/cloudwatch/。
在导航窗格中，选择 Logs（日志），然后选择 Logs Insights（日志洞察）。
在右侧，选择 Queries（查询）。
从 Saved queries（已保存的查询）列表中选择您的查询。它显示在查询编辑器中。
修改查询。如果您需要运行它来检查您的工作，请选择 Run query（运行查询）。
准备好保存新版本后，选择 Actions（操作）、Save as（另存为）。
输入查询的名称。
（可选）选择要保存查询的文件夹。选择 Create new（新建）以创建文件夹。如果创建新文件夹，则可以在文件夹名称中使用斜杠（/）字符来定义文件夹结构。例如，命名新文件夹 folder-level-1/folder-level-2 会创建一个名为 folder-level-1 的顶级文件夹，并在该文件夹中创建另一个名为 folder-level-2 的文件夹。查询保存在 folder-level-2 中。
（可选）更改查询的日志组或查询文本。
选择保存。

要删除查询，您必须登录到具有 logs:DeleteQueryDefinition 权限的角色。

编辑或删除已保存的查询

在处打开 CloudWatch 控制台https://console.aws.amazon.com/cloudwatch/。
在导航窗格中，选择 Logs（日志），然后选择 Logs Insights（日志洞察）。
在右侧，选择 Queries（查询）。
从 Saved queries（已保存的查询）列表中选择您的查询。它显示在查询编辑器中。
选择 Actions（操作）、Edit（编辑）或 Actions（操作）、Delete（删除）。

使用带有参数的已保存查询

保存的带参数的查询是带有命名占位符的可重复使用的查询模板。您可以保存模板并在运行查询时提供不同的参数值，而不必维护几乎相同的查询的多个副本。仅 CloudWatch 日志见解查询语言支持参数。

工作原理

保存查询时，占位符用于标识您在执行查询时可以提供的值。占位符使用{{parameterName}}语法。以下是ErrorsByLevel使用两个参数logLevel和命名的已保存查询的示例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了另一个已保存的查询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 日志见解查询语言支持参数。
在 QueryString 中找不到必需的参数	中的参数名称在查询字符串`{{placeholder}}`中`--parameters`不匹配。
参数数超过最大值 20	保存的查询目前仅支持 20 个参数。
重复的参数名称	查询定义中有重复的参数`parameters`。

注意

要使用参数创建或更新已保存的查询，您需要logs:PutQueryDefinition权限。要运行一个，你需要logs:StartQuery和logs:DescribeQueryDefinitions。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

模式分析

将查询添加到控制面板或导出查询结果