View a markdown version of this page

lookup - 亚马逊 CloudWatch 日志
创建和管理查找表用于查询的查询语法
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

lookup

lookup用于使用查询表中的参考数据丰富您的查询结果。您可以使用上传到 Amazon Logs 的 CSV 数据或已完成或取消的 CloudWatch 日志查询的结果填充查询表。当查询运行时，该lookup命令将您的日志事件中的字段与查找表中的字段进行匹配，并将指定的输出字段附加到结果中。

使用查找表来丰富数据，例如将用户 ID 映射到用户详细信息、将产品代码映射到产品信息，或将错误代码映射到错误描述。

创建和管理查找表

必须先创建查询表，然后才能在查询中使用该lookup命令。您可以通过 CloudWatch 控制台或使用 Amazon L CloudWatch ogs API 创建和管理查询表。

创建查询表（控制台）

  1. 在处打开 CloudWatch 控制台https://console.aws.amazon.com/cloudwatch/。

  2. 在导航窗格中，选择 “设置”，然后选择 “日志” 选项卡。

  3. 滚动到查询表，然后选择管理。

  4. 选择 “创建查找表” 。

  5. 输入查询表的名称。该名称只能包含字母数字字符和下划线。

  6. （可选）输入描述。

  7. 上传 CSV 文件。该文件必须包含带有列名的标题行，使用 UTF-8 编码，且不超过 10 MB。

  8. （可选）指定用于加密表数据的 Amazon KMS 密钥。

  9. 选择创建。

创建查询表后，可以在 CloudWatch 日志见解查询编辑器中查看该查询表。选择 “查找表” 选项卡以浏览可用表及其字段。

要更新查找表，请选择该表，然后选择操作，更新。上传新的 CSV 文件以替换所有现有内容。要删除查找表，请选择操作，删除。

除了上传 CSV 数据，您还可以根据您在日志分析控制台或 Amazon CloudWatch Logs API 中运行的已完成或取消的日志查询的结果创建或更新查询表。使用CreateLookupTable或 UpdateLookupTable API 的queryId参数指定查询 ID。取消的查询会在表中填充查询停止时可用的部分结果。必须指定 CSV 内容或查询 ID，但不能同时指定。更新表格是一项全面的替换操作——无论来源如何，所有现有内容都将被替换。要按计划使用查询结果自动刷新查找表，请使用带有查找表目标的计划查询。有关更多信息，请参阅 为计划查询配置查找表目的地。

注意

每个账户最多可以创建 100 个查询表 Amazon Web Services 区域。CSV 文件的最大容量为 10 MB。您还可以使用亚马逊 CloudWatch 日志 API 管理查询表。有关更多信息，请参阅CreateLookupTable《亚马逊 CloudWatch 日志 API 参考》。

注意

如果查询表使用 KMS 密钥加密，则调用者必须拥有该密钥（用于加密查找表的 KMS 密钥）的kms:Decrypt权限，才能将 StartQuery API 用于引用该查询表的查询。有关更多信息，请参阅 使用加密 CloudWatch 日志中的查找表 Amazon Key Management Service。

用于查询的查询语法

命令结构

以下显示了此命令的格式。

lookup table match-fields output-mode output-field[,...]

该命令使用以下参数：

  • table— 要使用的查询表的名称。

  • match-fields— 指定一个或多个字段以将日志事件与查找表进行匹配。您可以使用以下任一形式：

    • lookup-field as log-field [,...]— as 当查询表列名不同于日志事件字段名称时使用。例如，将查找表中的ip_address列与日志事件中的srcAddr字段进行ip_address as srcAddr匹配。

    • lookup-field [,...]— 当日志事件字段名称与查询表列名称相同时，可以省略as并直接指定字段名称。例如，将两列与同名的日志事件字段进行department, role匹配。

    指定多个匹配字段时，查找表中的一行必须匹配所有字段才能生成结果（AND 逻辑）。

  • output-mode— 指定如何将输出字段添加到结果中。使用以下值之一：

    • OUTPUT— 将输出字段添加到结果中。如果日志事件中已经存在同名字段，则该字段将被查找表值覆盖。如果未找到匹配项，则将该字段设置为空。

    • OUTPUTNEW— 仅当日志事件中不存在输出字段时，才将输出字段添加到结果中。如果该字段已经有值，则保留原始值。如果未找到匹配项，则该字段保持不变。

  • output-field— 查找表中的一个或多个字段添加到结果中。

示例：使用用户详细信息丰富日志事件

假设您有一个日志组，其中包含包含id字段的事件，以及一个user_data以列idnameemail、和命名的查询表department。以下查询使用查询表中的用户名、电子邮件和部门来丰富每个日志事件。

fields action, status, name, email, department
| lookup user_data id OUTPUT name, email, department
示例：使用带聚合的查询

您可以将查询输出字段与聚合函数一起使用。以下查询使用用户详细信息丰富了日志事件，然后统计了按电子邮件地址分组的事件。

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"
示例：使用 OUTPUTNEW 在不覆盖的情况下进行丰富

如果您的日志事件已包含字hostname段，但有时为空，则使用OUTPUTNEW在不覆盖现有值的情况下填写缺失值。

fields srcAddr, hostname
| lookup known_hosts ip_address as srcAddr OUTPUTNEW hostname, region
示例：对多个匹配字段使用查询

你可以在多个字段上进行匹配。以下查询dstPort对照表进行匹配srcAddr和匹配，以识别已知的网络服务。

fields @timestamp, srcAddr, dstAddr, dstPort
| lookup network_services ip_address as srcAddr, port as dstPort OUTPUT service_name, owner
| filter ispresent(service_name)
示例：使用具有匹配字段名称的查询

当您的日志事件字段名称与查询表列名称完全匹配时，可以省略as关键字。以下查询直接将department和role字段与查找表进行匹配。

fields @timestamp, department, role
| lookup employees department, role OUTPUT office, manager