Trace 的 SQL 查询示例

您可以在 Observability Analytics 中使用示例 SQL 查询来分析 您的 Cloud Trace 数据、识别延迟时间离群值，以及计算各项服务的 span 性能百分位数。

这些示例演示了如何过滤、分组和汇总存储在 _AllSpans 视图中的 span。如果您尚未在 Observability Analytics 中编写查询， 请先参阅查询和分析跟踪记录。

SQL 语言支持

Observability Analytics 页面中使用的查询支持 GoogleSQL 函数，但有一些例外情况。

以下 SQL 命令不支持通过 Observability Analytics 页面发出的 SQL 查询：

  • DDL 和 DML 命令
  • JavaScript 用户定义的函数
  • BigQuery ML 函数
  • SQL 变量

仅当您使用 BigQuery Studio 和 Looker Studio 页面或使用 bq 命令行工具查询关联的 BigQuery 数据集时，系统才支持以下各项：

  • JavaScript 用户定义的函数
  • BigQuery ML 函数
  • SQL 变量

最佳做法

如需设置查询的时间范围，我们建议您使用时间范围选择器。例如，如需查看过去一周的数据，请从时间范围选择器中选择过去 7 天 。您还可以使用时间范围选择器来指定开始时间和结束时间、指定要查看的时间范围，以及更改时区。

如果您在 WHERE 子句中添加了 start_time 字段，则系统不会使用时间范围选择器设置。以下示例说明了如何按时间戳进行过滤：

-- Matches trace spans whose start_time is within the most recent 1 hour.
WHERE start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

如需详细了解如何按时间进行过滤，请参阅 时间函数 和时间戳函数。

准备工作

  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. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the 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. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

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

    • Observability View Accessor (roles/observability.viewAccessor) ，用于您要查询的可观测性视图。此角色支持 IAM 条件，可让您将授予的权限限制为仅针对特定视图。如果您未为角色授予添加条件，则主账号可以访问所有可观测性视图。
    • Observability Analytics User (roles/observability.analyticsUser) ，用于您的项目。此角色包含保存和运行私有查询以及运行共享查询所需的权限。

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

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

如何使用本页面上的查询

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

    前往 Observability Analytics

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

  2. 在查询 窗格中，点击  SQL，然后将查询复制并粘贴 到 SQL 查询窗格中。

    以下内容显示了用于查询 _AllSpans 视图的 FROM 子句的格式：

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

    FROM 子句包含以下字段：

    • PROJECT_ID：项目的标识符。
    • LOCATION：可观测性存储桶的位置。
    • _Trace 是可观测性存储桶的名称
    • Spans 是数据集的名称。
    • _AllSpans 是视图名称。

如需在 BigQuery Studio 页面上使用本文档中显示的查询，或 使用 bq 命令行工具，请 修改 FROM 子句并输入 关联的 BigQuery 数据集的路径。 例如，如需查询项目 myproject 中名为 my_linked_dataset 的关联 BigQuery 数据集上的 _AllSpans视图，路径为 `myproject.my_linked_dataset._AllSpans`。

常见使用场景

本部分列出了一些常见使用场景，这些场景可能有助于您创建自定义查询。

显示所有跟踪记录数据

如需查询 _AllSpans 视图，请运行以下查询：

-- Display all data.
SELECT *
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
-- Limit to 10 entries.
LIMIT 10

显示常见的 span 信息

如需显示常见的 span 信息（例如开始时间和持续时间），请运行以下查询：

SELECT
  start_time,
  -- Set the value of service name based on the first non-null value in the list.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,
  name AS span_name,
  duration_nano,
  status.code AS status,
  trace_id,
  span_id
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
LIMIT 10

如需了解详情，请参阅条件表达式。

显示 span 延迟时间的第 50 百分位和第 99 百分位

如需显示每个 rpc 服务的延迟时间的第 50 百分位和第 99 百分位，请运行以下查询：

SELECT
  -- Compute 50th and 99th percentiles for each service
  STRING(attributes['rpc.service']) || '/' || STRING(attributes['rpc.method']) AS rpc_service_method,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS duration_nano_p50,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS duration_nano_p99
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans whose kind field has a value of 2 (SPAN_KIND_SERVER).
  kind = 2
GROUP BY rpc_service_method

如需详细了解枚举，请参阅 OpenTelemetry：SpanKind 文档。

如需以图形方式查看结果，您可以创建一个图表，并将维度设置为 rpc_service_method。您可以添加两个指标，一个用于 duration_nano_p50 值的平均值，另一个用于 duration_nano_p99 字段的平均值。

过滤跟踪记录条目

如需将过滤条件应用于查询，请添加 WHERE 子句。在此子句中使用的语法取决于字段的数据类型。本部分提供了针对不同数据类型的多个示例。

按字符串数据类型过滤

name 字段存储为 String。

  • 如需仅分析指定了 name 的 span，请使用以下子句：

    -- Matches spans that have a name field.
WHERE name IS NOT NULL

  • 如需仅分析 name 值为 "POST" 的 span， 请使用以下子句：

    -- Matches spans whose name is POST.
WHERE STRPOS(name, "POST") > 0

  • 如需仅分析 name 包含值 "POST" 的 span， 请结合使用 LIKE 运算符和通配符：

    -- Matches spans whose name contains POST.
WHERE name LIKE "%POST%"

按整数数据类型过滤

kind 字段是一个整数，可以取介于 0 到 5 之间的值：

  • 如需仅分析指定了 kind 的 span，请使用以下子句：

    -- Matches spans that have field named kind.
WHERE kind IS NOT NULL

  • 如需分析 kind 值为 1 或 2 的 span，请使用以下子句：

    -- Matches spans whose kind value is 1 or 2.
WHERE kind IN (1, 2)

按 RECORD 数据类型过滤

跟踪记录架构中的某些字段的数据类型为 RECORD。这些字段可以存储一个或多个数据结构，也可以存储同一数据结构的重复条目。

按状态或状态代码过滤

status 字段是数据类型为 RECORD 的字段的示例。此 字段存储一个数据结构，其成员标记为 code 和 message。

  • 如需仅在 status.code 字段的值为 1 时分析 span，请添加以下子句：

    -- Matches spans that have a status.code field that has a value of 1.
WHERE status.code = 1

    status.code 字段存储为整数。

  • 如需分析 status 字段不是 EMPTY 的 span，请添加以下子句：

    -- Matches spans that have status field. When the status field exists, it
-- must contain a subfield named code.
-- Don't compare status to NULL, because this field has a data type of RECORD.
WHERE status.code IS NOT NULL

events 和 links 字段存储的数据类型为 RECORD，但这些是重复字段。

  • 如需匹配至少有一个事件的 span，请使用以下子句：

    -- Matches spans that have at least one event. Don't compare events to NULL.
-- The events field has data type of RECORD and contains a repeated fields.
WHERE