使用 Log Analytics 查询和分析日志

本文档介绍了如何使用 Log Analytics（提供基于 SQL 的查询界面）查询和分析日志数据。通过使用 SQL，您可以执行以下任务：统计包含与某种模式匹配的字段的日志条目。Log Analytics 提供了一个 SQL 编辑器和一个基于菜单的查询构建系统。 如需查看查询结果，您可以使用表格形式，也可以将数据可视化为图表。您可以将图表保存到自定义信息中心。

您可以查询日志存储桶中的日志视图或分析视图。查询日志视图时，架构对应于 LogEntry 数据结构。由于分析视图的创建者决定了架构，因此分析视图的一个用例是将日志数据从 LogEntry 格式转换为更适合您的格式。

Log Analytics 不会对日志条目进行去重处理，这可能会影响您编写查询的方式。此外，使用 Log Analytics 时还存在一些限制。 如需详细了解这些主题，请参阅以下文档：

关于关联的数据集

Log Analytics 支持创建关联的 BigQuery 数据集，让 BigQuery 能够读取底层数据。如果您选择创建关联的数据集，则可以执行以下操作：

  • 将日志条目数据与其他 BigQuery 数据集联接。
  • 查询来自其他服务（例如 BigQuery Studio页面或 Looker Studio）的日志数据。
  • 通过在 BigQuery 预留槽上运行查询，提升从 Log Analytics 运行的查询的性能。
  • 创建提醒政策，用于监控 SQL 查询的结果。如需了解详情，请参阅使用提醒政策监控 SQL 查询结果。

本文档未介绍如何创建关联的数据集，也未介绍如何配置 Log Analytics 以在预留槽上运行查询。如果您对这些主题感兴趣，请参阅在 BigQuery 中查询关联的数据集。

准备工作

本部分介绍了在使用 Log Analytics 之前必须完成的步骤。

配置日志存储桶

确保您的日志存储桶已升级为使用 Log Analytics：

  1. 在 Google Cloud 控制台中，前往日志存储页面：

    前往日志存储

    如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

  2. 对于包含您要查询的日志视图的每个日志存储桶，请确保 Log Analytics 可用列显示打开。如果显示升级，请点击升级并完成对话框。

配置 IAM 角色和权限

本部分介绍了使用 Log Analytics 所需的 IAM 角色或权限：

  • 如需获得使用 Log Analytics 和查询日志视图所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

    • 查询 _Required 和 _Default 日志存储桶：Logs Viewer (roles/logging.viewer)
    • 查询项目中的所有日志视图：Logs View Accessor (roles/logging.viewAccessor)

    您可以通过以下方式限制主账号只能查看特定日志视图：向项目级别授予的 Logs View Accessor 角色添加 IAM 条件，或者向日志视图的政策文件添加 IAM 绑定。如需了解详情，请参阅控制对日志视图的访问权限。

    这些权限与您在 Logs Explorer 页面上查看日志条目时需要的权限相同。如需了解您需要哪些额外角色才能查询用户定义的存储桶的视图，或者查询 _Default 日志存储桶的 _AllLogs 视图，请参阅 Cloud Logging 角色。

  • 如需获得查询分析视图所需的权限，请让您的管理员为您授予项目的 Observability Analytics User (roles/observability.analyticsUser) IAM 角色。

查询日志数据

本部分介绍了可用于查询日志数据的方法：

  • 加载系统定义的查询，修改此查询，然后运行该查询。
  • 输入并运行自定义查询。例如，您可以粘贴或撰写查询内容。自定义查询可以包含联接、嵌套查询和其他复杂的 SQL 语句。如需查看示例，请参阅示例 SQL 查询。
  • 通过从菜单中进行选择来构建查询，然后运行该查询。 日志分析会将您的选择转换为 SQL 查询，您可以查看和修改该查询。

加载、修改和运行系统定义的查询

  1. 在 Google Cloud 控制台中，前往 Log Analytics 页面：

    转到 Log Analytics

    如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

  2. 在视图菜单中，前往 日志或 分析视图部分，然后选择要查询的视图。

    如需查找要查询的视图，请使用 过滤条件栏，也可以滚动浏览列表：

    • 日志视图按 BUCKET_ID.LOG_VIEW_ID 列出，其中这些字段引用日志存储桶和日志视图的 ID。

    • 分析视图按 LOCATION.ANALYTICS_VIEW_ID 列出，其中这些字段引用分析视图的位置和 ID。分析视图目前为公开预览版。

  3. 执行下列其中一项操作：

    • 如需加载依赖于查询构建器的系统定义的查询，该构建器可让您通过菜单选择来定义查询，请确保查询窗格显示查询构建器。如果系统显示 SQL 编辑器，请点击  构建器。

    • 如需加载提取 JSON 值的系统定义查询，请确保查询窗格显示 SQL 编辑器。如果此窗格显示查询构建器，请点击  SQL。

  4. 在架构窗格中，选择查询，然后点击覆盖。

    查询窗格会显示系统定义的查询。如果您选择了查询构建器模式，但想查看 SQL 查询，请点击  SQL。

  5. 可选：修改查询。

  6. 如需运行查询，请前往工具栏，然后选择运行查询。

    Log Analytics 会以表格形式显示查询结果。不过，您可以创建图表，还可以将表格或图表保存到自定义信息中心。如需了解详情，请参阅将 SQL 查询结果绘制成图表。

    如果工具栏显示在 BigQuery 上运行，则需要切换 Log Analytics 以使用默认查询引擎。如需进行此更改，请在查询窗格的工具栏中，依次点击 设置和 Analytics（默认）。

输入并运行自定义查询

如需输入 SQL 查询，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往 Log Analytics 页面：

    转到 Log Analytics

    如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

  2. 在查询窗格中，点击  SQL。

    • 如需指定时间范围，我们建议您使用时间范围选择器。如果您添加了指定 timestamp 字段的 WHERE 子句，则该值会替换时间范围选择器中的设置，并且该选择器会被停用。

    • 如需查看示例，请参阅示例 SQL 查询。

    • 您可以查询日志视图或分析视图。请使用以下格式来表示 FROM 子句：

      • 日志视图：

        FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

      • Google Analytics 数据视图：

        FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`

      上面表达式中的字段含义如下：

      • PROJECT_ID：项目的标识符。
      • LOCATION：日志视图或分析视图的位置。
      • BUCKET_ID：日志存储桶的名称或 ID。
      • LOG_VIEW_ID：日志视图的标识符，长度不得超过 100 个字符，并且只能包含字母、数字、下划线和连字符。
      • ANALYTICS_VIEW_ID：分析视图的 ID，长度不得超过 100 个字符，且只能包含字母、数字、下划线和连字符。

      如果查询窗格显示引用 FROM 语句的错误消息，则表示找不到相应视图。如需了解如何解决此失败问题，请参阅错误：FROM 子句必须且只能包含一个日志视图。

  3. 如需运行查询，请前往工具栏，然后选择运行查询。

    Log Analytics 会以表格形式显示查询结果。不过，您可以创建图表，还可以将表格或图表保存到自定义信息中心。如需了解详情，请参阅将 SQL 查询结果绘制成图表。

    如果工具栏显示在 BigQuery 上运行，则需要切换 Log Analytics 以使用默认查询引擎。如需进行此更改，请在查询窗格的工具栏中，依次点击 设置和 Analytics（默认）。

构建、修改和运行查询

借助查询构建器界面，您可以通过从菜单中进行选择来构建查询。Log Analytics 会将您的选择转换为 SQL 查询，您可以查看和修改该查询。例如，您可能先使用查询构建器界面，然后切换到 SQL 编辑器来优化查询。

Log Analytics 始终可以将您在查询构建器界面中选择的菜单项转换为 SQL 查询。不过，并非所有 SQL 查询都可以通过查询构建器界面表示。例如，包含联接的查询无法通过此接口表示。

如需构建查询，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往 Log Analytics 页面：

    转到 Log Analytics

    如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

  2. 如果查询窗格显示 SQL 编辑器，请选择 构建器，这会打开查询构建器窗格。

  3. 使用来源菜单选择要查询的视图。您的选择会映射到 SQL 查询中的 FROM 子句。

  4. 可选：使用以下菜单限制或设置结果表的格式：

    • 搜索所有字段：搜索匹配的字符串。您的选择会映射到 SQL 查询中的 WHERE 子句。

    • 列：选择结果表中显示的列。您的选择会映射到 SQL 查询中的 SELECT 子句。

      当您在此菜单中选择某个字段名称时，系统会打开一个对话框。在此对话框中，您可以执行以下操作：

      • 使用菜单汇总或分组数据。

        为防止出现语法错误，您对一列应用的所有聚合和分组也会自动应用于其他列。如需查看如何汇总和分组条目的示例，请参阅使用查询构建器对数据进行分组和汇总。

      • 将任意类型的值转换为其他指定的数据类型。如需了解详情，请参阅 CAST 文档。

      • 使用正则表达式提取值的子字符串。如需了解详情，请参阅 REGEXP_EXTRACT 文档。

    • 过滤条件：如果您想将查询限制为包含特定属性或 span ID 的 span，请添加过滤条件。该菜单会列出所有可用的过滤选项。您的选择会映射到 SQL 查询中的 WHERE 子句。

    • 排序依据：设置排序依据的列，以及排序是升序还是降序。您的选择会映射到 SQL 查询中的 ORDER BY 子句。

    • 限制：设置结果表中的最大行数。您的选择会映射到 SQL 查询中的 LIMIT 子句。

  5. 如需运行查询，请前往工具栏，然后选择运行查询。

    Log Analytics 会以表格形式显示查询结果。不过，您可以创建图表，还可以将表格或图表保存到自定义信息中心。如需了解详情，请参阅将 SQL 查询结果绘制成图表。

    如果工具栏显示在 BigQuery 上运行，则需要切换 Log Analytics 以使用默认查询引擎。如需进行此更改，请在查询窗格的工具栏中，依次点击 设置和 Analytics（默认）。

示例：使用查询构建器对数据进行分组和汇总

在查询构建器中选择列时，每个字段都会包含一个菜单，您可以在其中添加分组和汇总。通过分组，您可以根据一列或多列的值将数据整理成组；通过聚合，您可以对这些组执行计算以返回单个值。

您在列元素中选择的每个字段都有一个附加菜单，其中包含以下选项：

  • 无：不按此字段进行分组或汇总。
  • 汇总：对列元素中列出的字段进行分组，除非该字段已选择汇总。对于这些字段，通过对每个分组中的所有条目执行运算来计算值。该操作可能是计算某个字段的平均值，也可能是统计每个分组中的条目数。
  • Group By：按列元素中列出的所有字段对条目进行分组。

以下示例展示了如何构建对条目进行分组，然后执行某种类型的聚合的查询。

此示例介绍了如何使用查询构建器按严重程度和时间戳对日志条目进行分组，然后计算每个组的 http_request.response_size 字段的平均值。

如需构建用于对数据进行分组和汇总的查询，请从查询构建器菜单中进行以下选择：

  1. 在列菜单中，选择 timestamp、severity 和 http_request.response_size 字段。

    1. 如需对数据进行分组，请点击 timestamp 字段以打开设置对话框。在此对话框中，选择分组依据选项，并将截断粒度设置为 HOUR。然后，系统会自动将分组应用于所有其他字段，以防止出现语法错误。如果存在无法应用分组的无效字段，您会看到一条错误消息。从菜单中移除无效字段，即可解决此错误。

    2. 如需对 http_request.response_size 字段执行聚合，请点击该字段以打开设置对话框。在此对话框中，选择汇总。在聚合菜单中，点击平均值。

  2. 在过滤条件菜单中，添加 http_request.response_size 并将比较器设置为 IS NOT NULL。此过滤条件可匹配包含 response_size 值的日志条目。

    查询构建器菜单如下所示：

    使用查询构建器菜单进行汇总和分组。

  3. 如需运行查询，请前往工具栏，然后选择运行查询。

    此查询的结果如下所示：

    +-----------------------------------+----------+---------------+
| Row | hour_timestamp              | severity | response_size |
|     | TIMESTAMP                   | STRING   | INTEGER       |
+-----+-----------------------------+----------+---------------+
| 1   | 2025-10-06 16:00:00.000 UTC | NOTICE   | 3082          |
| 2   | 2025-10-06 17:00:00.000 UTC | WARNING  | 338           |
| 3   | 2025-10-06 16:00:00.000 UTC | INFO     | 149           |

上例中对应的 SQL 查询如下所示：

SELECT
  -- Truncate the timestamp by hour.
  TIMESTAMP_TRUNC( timestamp, HOUR ) AS hour_timestamp,
  severity,
  -- Compute average response_size.
  AVG( http_request.response_size ) AS average_http_request_response_size
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries that have a response_size.
  http_request.response_size IS NOT NULL
GROUP BY
  -- Group log entries by timestamp and severity.
  TIMESTAMP_TRUNC( timestamp, HOUR ),
  severity
LIMIT
  1000

显示架构

架构定义了数据的存储方式，包括字段及其数据类型。此信息对您非常重要，因为架构决定了您要查询的字段以及是否需要将字段转换为不同的数据类型。例如，若要编写计算 HTTP 请求平均延迟时间的查询，您需要了解如何访问延迟时间字段，以及该字段是存储为整数（如 100）还是存储为字符串（如 "100"）。如果延迟时间数据以字符串形式存储，则查询必须先将值转换为数值，然后才能计算平均值。

如需确定架构，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往 Log Analytics 页面：

    转到 Log Analytics

    如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

  2. 在视图菜单中，前往 日志或 分析视图部分，然后选择要查询的视图。

    架构窗格已更新。当数据类型为 JSON 时，Log Analytics 会自动推理列的字段。 如需查看这些推理字段在您的数据中出现的频率，请点击 选项，然后选择查看信息和说明。

    对于日志视图，架构是固定的，对应于 LogEntry。对于分析视图，您可以修改 SQL 查询来更改架构。

后续步骤