使用 Log Analytics 查询和分析遥测数据

本文档介绍如何使用 Log Analytics 查询和分析日志及轨迹数据，Log Analytics 提供基于 SQL 的查询界面。借助 SQL，您可以执行汇总分析，这有助于您生成数据分析和发现趋势。如需查看查询结果，请使用表格形式，或通过图表直观呈现数据。 您还可以将这些表格和图表保存到自定义信息中心。

关联的 BigQuery 数据集简介

使用 Log Analytics 页面时，您无需关联 BigQuery 数据集即可查询日志数据、轨迹数据或这两种数据。

如果您要执行以下任何操作，则需要关联的 BigQuery 数据集：

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

本文档未介绍如何创建关联的数据集，这需要一个特定于数据类型的流程。如需了解如何创建关联的数据集，请参阅使用关联的数据集查询日志数据或使用关联的数据集查询轨迹数据。

准备工作

  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 启用 Observability API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

    启用 API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. 启用 Observability API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

    启用 API

    8.

  8. 如需获得加载 Log Analytics 页面、在跟踪记录数据上撰写、运行和保存私密查询所需的权限，请让管理员为您授予以下 IAM 角色：

    • Observability View Accessor (roles/observability.viewAccessor) 在您要查询的可观测性视图上。此角色支持 IAM 条件，可让您将授予的权限限制为仅针对特定视图。如果您未为角色授予附加条件，则正文可以访问所有可观测性视图。可观测性视图目前为公开预览版。
    • 针对项目的 Observability Analytics User (roles/observability.analyticsUser)。此角色包含保存和运行专用查询以及运行共享查询所需的权限。
    • 项目的 Logs Viewer (roles/logging.viewer)
    • 存储您要查询的日志视图的项目的 Logs View Accessor (roles/logging.viewAccessor)。

    如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

    您也可以通过自定义角色或其他预定义角色来获取所需的权限。

查询日志和轨迹数据

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

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

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

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

    转到 Log Analytics

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

  2. 在视图菜单中，选择一个视图。

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

    • 日志视图列在 日志部分，并按存储桶和视图 ID 排序。

    • 分析视图列在 分析视图部分，并按视图的位置和 ID 排序。可观测性视图目前为公开预览版。

    • 有一个轨迹视图，列在 轨迹部分中。可观测性视图目前为公开预览版。

      如果您没有看到名为 _Trace.Spans._AllSpans 的视图，则表示您的Google Cloud 项目不包含名为 _Trace 的可观测性存储桶。如需了解如何解决此故障，请参阅跟踪存储初始化失败。

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

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

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

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

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

  5. 可选：修改查询。

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

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

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

输入并运行自定义查询

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

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

    转到 Log Analytics

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

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

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

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

    • 您查询的视图决定了 FROM 子句的格式：

      日志数据

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

      • 日志视图：

        FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

      • 分析视图：

        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 子句必须且只能包含一个日志视图。

      跟踪记录数据

      SQL 编辑器会显示 _Trace.Spans._AllSpans 视图的完全限定名称，其格式如下：

      FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`

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

      • PROJECT_ID：项目的标识符。
      • LOCATION：可观测性存储桶的位置。

      如果查询窗格显示引用 FROM 语句的错误消息，则表示找不到相应视图。如需了解如何解决此失败问题，请参阅显示视图不存在的错误消息。

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

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

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

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

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

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

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

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

日志数据

此示例介绍了如何使用查询构建器按严重程度和时间戳对日志条目进行分组，然后计算每个组的 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

跟踪记录数据

此示例介绍了如何使用查询构建器按开始时间、span 名称和 span 类型对 span 进行分组。然后，查询会针对每个组计算平均时长（以纳秒为单位）。

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

  1. 在列菜单中，选择 start_time、name、kind 和 duration_nano 字段。
  2. 如需将开始时间截断到小时，请展开 start_time 列中的菜单，然后选择分组依据。确保粒度菜单设置为小时。

  3. 点击应用。

    如果您为任何列选择分组依据，系统会按所有列对条目进行分组。在此示例中，条目按截断的 start_time 值、span 名称、span 种类和时长值进行分组。

    不过，此示例的目标是按截断的时间、span 名称和 span 种类对条目进行分组，然后针对每个组计算平均时长。在下一步中，您将修改分组并添加汇总。

  4. 展开 duration_nano 字段中的菜单，选择汇总，然后将汇总字段设置为平均值。

    运行查询时，每一行都对应一个组，该组包含截断的时间、span 名称和 span 类型。每行中的最后一个条目是相应组中所有条目的平均时长。

    此查询的结果如下所示：

    +-----------------------------------+----------------+----------+-----------------------+
| Row | hour_timestamp              | span_name      | kind     | average_duation_nano  |
|     | TIMESTAMP                   | STRING         | INTEGER  | FLOAT                 |
+-----+-----------------------------+-----------+---------------+-----------------------+
| 1   | 2025-10-09 13:00:00.000 EDT | http.receive   | 3        | 122138.22813990474
| 2   | 2025-10-09 13:00:00.000 EDT | query.request  | 1        | 6740819304.390297
| 3   | 2025-10-09 13:00:00.000 EDT | client.handler | 2        | 6739339098.409376

  5. 您的查询可以包含多个聚合。例如，如需添加一个用于统计每个组中条目数量的列，请执行以下操作：

    1. 在列元素中，点击添加列。
    2. 选择全部 (*)。
    3. 在对话框中，选择汇总，为汇总选择计数，然后选择应用。

    进行此更改后，分组保持不变。条目按截断的开始时间、span 名称和 span 种类分组。不过，对于每个组，查询都会计算平均时长和条目数。

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

WITH
  scope_query AS (
  SELECT
    *
  FROM
    `PROJECT_ID.global._Trace._AllSpans` )
SELECT
  -- Report the truncated start time, span name, span kind, average duration and number
  -- of entries for each group.
  TIMESTAMP_TRUNC( start_time, HOUR ) AS hour_start_time,
  name AS span_name,
  kind,
  AVG( duration_nano ) AS average_duration_nano,
  COUNT( * ) AS count_all
FROM
  scope_query
GROUP BY
  TIMESTAMP_TRUNC( start_time, HOUR ),
  name,
  kind
LIMIT
  100

显示架构

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

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

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

    转到 Log Analytics

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

  2. 在视图菜单中，选择一个视图。

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

    日志数据

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

    跟踪记录数据

    如需了解架构，请参阅跟踪记录数据的存储架构。

    如果您没有看到名为 _Trace.Spans._AllSpans 的视图，则表示您的Google Cloud 项目不包含名为 _Trace 的可观测性存储桶。如需了解如何解决此故障，请参阅跟踪存储初始化失败。

限制

如果您想查询多个视图，则这些视图必须位于同一位置。例如，如果您在 us-east1 位置存储了两个视图，则一个查询可以同时查询这两个视图。您还可以查询存储在 us 多区域中的两个视图。不过，如果视图的位置为 global，则该视图可以位于任何实际位置。因此，位置为 global 的两个视图之间的联接可能会失败。

如需查看适用于日志数据的限制列表，请参阅 Log Analytics：限制。

后续步骤