本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 创建字段索引以提高查询性能并减少扫描量
<a name="CloudWatchLogs-Field-Indexing"></a>

您可以为日志事件中的字段创建*字段索引*，以便高效地进行基于等式的搜索。然后，当您在 L CloudWatch ogs Insights 查询中使用字段索引时，该查询会尝试跳过处理已知不包含索引字段的日志事件。这样可以减少使用字段索引的查询的扫描量，从而更快地返回结果。这可以帮助您快速搜索数千个日志组中 PB 级的总日志，并更快地找到相关日志。适合编制索引的字段是您经常需要查询的字段。具有高基数值的字段也是字段索引的良好候选对象，因为使用这些字段索引的查询限制了与目标值匹配的日志事件，因此会更快完成。

例如，假设您为 `requestId` 创建了一个字段索引。然后，针对该日志组的任何 CloudWatch Logs Insights 查询，该查询包含`requestId = value`或`requestId IN [value, value, ...]`将尝试仅处理已知包含该索引字段和查询值的 CloudWatch 日志事件，而且 Logs 过去已检测到该字段的值。

您还可以利用字段索引来创建对大量日志组的高效查询。当您在查询中使用 `filterIndex` 命令而不是 `filter` 命令时，查询将针对具有字段索引的日志事件的选定日志组运行。这些查询最多可以扫描 10,000 个日志组，您可以通过指定最多五个日志组名称前缀进行选择。如果这是 CloudWatch 跨账户可观察性的监控账户，则可以选择所有源账户或指定单个源账户来选择日志组”。

索引字段区分大小写。例如，字段索引 `RequestId` 将无法匹配包含 `requestId` 的日志事件。

仅 JSON 和服务日志的结构化日志格式支持字段索引。

CloudWatch 日志为标准日志类中的所有日志组提供默认字段索引。默认字段索引可自动用于以下字段：
+ `@logStream`
+ `@aws.region`
+ `@aws.account`
+ `@source.log`
+ `@data_source_name`
+ `@data_source_type`
+ `@data_format`
+ `traceId`
+ `severityText`
+ `attributes.session.id`

CloudWatch 日志还为某些数据源名称和类型组合提供默认字段索引。默认字段索引自动适用于以下数据源名称和类型组合：


| 数据源名称和类型 | 默认字段索引 | 
| --- | --- | 
|  `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 仅记录创建索引策略后提取的日志事件的索引。它不会对创建策略之前摄取的日志事件编制索引。创建字段索引后，每个匹配的日志事件将从日志事件的摄取时间起保留编制索引 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)

# 字段索引语法和配额
<a name="CloudWatchLogs-Field-Indexing-Syntax"></a>

您可以通过创建*字段索引策略*来创建字段索引。您可以创建适用于整个账户的账户级索引策略，也可以创建仅适用于单个日志组的策略。对于账户范围内的索引策略，您可以设置适用于账户中的所有日志组的索引策略。您还可以创建适用于账户中的部分日志组的账户级索引策略（按日志组名称的前缀选择）。如果在同一个账户中有多个账户级策略，则这些策略的日志组名称前缀不能重叠。同样，您可以创建适用于特定数据源名称和类型组合的账户级索引策略。每个数据源名称和类型组合只能创建一个账户策略。

日志组级别的字段索引策略优先于账户级字段索引策略：这些策略适用于整个日志组（例如，没有选择标准或基于日志组名称前缀的选择标准的账户级策略）。除了与整个日志组匹配的策略外，还将应用在日志事件级别匹配的账户级策略（例如，针对给定的数据源名称和类型组合）。如果您创建日志组级别的索引策略，则该日志组不使用与日志组级别匹配的账户级策略。

日志事件与字段索引名称的匹配区分大小写。例如，字段索引 `RequestId` 将无法匹配包含 `requestId` 的日志事件。

您最多可以有 40 个账户级别的索引策略，其中 20 个可以使用日志组名称前缀选择标准，20 个可以使用基于数据源的选择标准。如果您有多个账户级索引策略，并且它们按日志组名称前缀进行筛选，则其中任何两个策略都不能使用相同或重叠的日志组名称前缀。例如，如果您有一个策略筛选出以 `my-log` 开头的日志组，则不能再有一个字段索引策略筛选出以 `my-logpprod` 或 `my-logging` 开头的日志组。同样，如果您有多个账户级索引策略筛选为数据源名称和类型组合，则其中任何两个策略都不能使用相同的数据源名称和类型。例如，如果您将一个策略筛选为数据源名称`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 日志为标准日志类中的所有日志组提供默认字段索引。默认字段索引可自动用于以下字段：
+ `@logStream`
+ `@aws.region`
+ `@aws.account`
+ `@source.log`
+ `@data_source_name`
+ `@data_source_type`
+ `@data_format`
+ `traceId`
+ `severityText`
+ `attributes.session.id`

CloudWatch 日志还为某些数据源名称和类型组合提供默认字段索引。默认字段索引自动适用于以下数据源名称和类型组合：


| 数据源名称和类型 | 默认字段索引 | 
| --- | --- | 
|  `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"
```

# 创建账户级字段索引策略
<a name="CloudWatchLogs-Field-Indexing-CreateAccountLevel"></a>

请按照本节中的步骤创建适用于账户中的所有日志组或者日志组名称以相同字符串开头的多个日志组的字段索引策略。

**创建账户级字段索引策略**

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`。

   您还可以为 L CloudWatch ogs 自动生成的`@ingestionTime`和`@logStream`字段创建索引。如果这样做，则在指定它们时无需添加额外的 `@`。

1. （可选）除了指定字段路径外，您还可以选择 “**设置为分面**”，将字段创建为分面。

1. 重复上一步，最多可添加 20 个字段索引。

1. 完成后，选择**创建**。

# 创建日志组级字段索引策略
<a name="CloudWatchLogs-Field-Indexing-CreateLogGroupLevel"></a>

请按照本节中的步骤创建适用于单个日志组的字段索引策略。

**创建日志组级字段索引策略**

1. 打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)。

1. 在左侧导航窗格中，依次选择**日志**和**日志组**。

1. 选择日志组的名称。

1. 选择**字段索引**选项卡。

1. 选择**管理此日志组的字段索引**

1. 对于**管理日志组级字段索引**，选择**添加字段路径**以输入要编制索引的第一个字段。

   然后输入要用作字段名称值的字符串。这必须与日志事件中出现的内容的大小写完全匹配。例如，如果您的日志事件包含 `requestId`，则必须在此处输入 `requestId`。`RequestId`、`requestID` 和 `request Id` 匹配。

   如果要为以 `@` 字符开头的自定义日志字段编制索引，则在输入索引字符串时必须包含一个额外的 `@` 字符。例如，如果您有一个自定义日志字段 `@emailname`，请在**添加字段路径**框中输入 `@@emailname`。

   您还可以为 L CloudWatch ogs 自动生成的`@ingestionTime`和`@logStream`字段创建索引。如果这样做，则在指定它们时需要添加额外的 `@`。

1. （可选）除了指定字段路径外，您还可以选择 “**设置为分面**”，将字段创建为分面。

1. 重复上一步，最多可添加 20 个字段索引。

1. 完成后，选择 **Save**。

# 创建查询时的日志组选择选项
<a name="Field-Indexing-Selection"></a>

本节介绍了选择要包含在查询中的日志组的各种方法。

**在控制台中选择用于查询的日志组**

1. 打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)。

1. 在导航窗格中，依次选择**日志**、**Logs Insights**。

1. 选择要用于此查询的查询语言。您可以选择：**日志 Insights QL**、**OpenSearchPPL** 或 **OpenSearch SQL**。

1. 可通过三种方式选择要用于查询的日志组：
   + 使用**日志组名称**框。这是默认选择方法。使用此方法，您最多可以输入 50 个日志组名称。如果这是 CloudWatch跨账户可观察性的监控账户，则可以在源账户和监控账户中选择日志组。单个查询可以同时查询来自不同账户的日志。
   + 使用**日志组条件**部分。在此部分，您可以根据日志组名称的前缀选择日志组。一个查询最多可以包含五个前缀。名称中包含这些前缀的日志组将被选中。或者，**所有日志组**选项会选择账户中的所有日志组。
   + 如果这是 CloudWatch 跨账户可观察性的监控账户，则可以在账户下拉菜单中选择**所有账户**，从所有关联账户中选择日志组。或者，您可以单独选择要包含在此查询中的账户。

   如果您的选择与超过 10,000 个日志组匹配，您将看到一个错误，提示您缩小选择范围。

1. 查询的默认日志类为**标准**。您可以使用**日志类**将其更改为**不频繁访问**。

**使用 AWS CLI**

要在从命令行启动查询时进行此类选择，可以在查询中使用 `source` 命令。有关更多信息以及示例，请参阅 [SOURCE](CWL_QuerySyntax-Source.md)。

# 删除字段索引策略的影响
<a name="CloudWatchLogs-Field-Indexing-Deletion"></a>

如果删除已生效一段时间的字段索引策略，则会发生以下情况：
+ 在删除策略后的 30 天内，查询仍然可以从索引日志事件中受益。
+ 如果您删除了日志组级索引策略，并且已存在适用于该日志组的账户级策略，则账户级策略最终将适用于该日志组。