Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

管理轨迹存储空间

本文档介绍了如何使用 Observability API 获取有关存储轨迹数据的可观测性存储桶的信息。其中包含有关如何列出数据集、链接和视图的信息。如需详细了解跟踪记录数据的存储方式，请参阅跟踪记录存储概览。

准备工作

配置项目、IAM 角色，然后选择您计划使用的界面。

配置项目和角色

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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Observability API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API

如需获得列出存储分区、链接和视图所需的权限，请让您的管理员为您授予项目的 Observability Viewer (roles/observability.viewer) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

选择您计划使用的界面

gcloud

安装 Google Cloud CLI，然后使用联合身份登录 gcloud CLI。登录后，运行以下命令来初始化 Google Cloud CLI：

gcloud init

REST

如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭证。

安装 Google Cloud CLI，然后使用联合身份登录 gcloud CLI。

如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

列出可观测性存储分区

gcloud

在使用下面的命令数据之前，请先进行以下替换：

LOCATION：可观测性存储分区的位置。如需列出所有可观测性存储分区（无论其位置如何），请将位置设置为连字符 (-)。
PROJECT_ID：项目的标识符。

执行 gcloud beta observability buckets list 命令：

Linux、macOS 或 Cloud Shell

gcloud beta observability buckets list \
 --location=LOCATION --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets list `
 --location=LOCATION --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets list ^
 --location=LOCATION --project=PROJECT_ID

响应会列出每个可观测性存储分区的名称、说明和创建时间。以下是命令成功执行时的响应示例：

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Bucket for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace

REST

如需列出项目和特定位置中的可观测性存储分区，请向 projects.locations.buckets.list 端点发送请求。

您必须指定 parent 参数，该参数采用以下形式：

projects/PROJECT_ID/locations/LOCATION

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

PROJECT_ID：项目的标识符。
LOCATION：可观测性存储桶的位置。如果您将 LOCATION 设置为连字符 (-)，则系统会列出项目中的所有可观测性存储分区。

响应是一组 Bucket 对象。对于每个对象，name 字段的值采用以下格式：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

例如，当向 buckets.list 端点发出命令并将父参数设置为 projects/my-project/locations/us 时，响应如下：

{
  "buckets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace",
      "description": "Trace Bucket",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
      "retentionDays": 30
    }
  ]
}

您可以向其他 Observability API 端点发出命令，以获取有关 ID 为 BUCKET_ID 的存储桶的更多信息。例如，您可以列出相应存储桶中的数据集，以及每个数据集中的视图和链接。如需查看完整的 Observability API 端点列表，请参阅 Observability API 参考文档。

列出可观测性存储桶中的数据集

gcloud

在使用下面的命令数据之前，请先进行以下替换：

BUCKET_ID：可观测性存储桶的 ID。例如，此 ID 可能是 _Trace。
LOCATION：可观测性存储分区的位置。
PROJECT_ID：项目的标识符。

执行 gcloud beta observability buckets datasets list 命令：

Linux、macOS 或 Cloud Shell

gcloud beta observability buckets datasets list \
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets list `
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets list ^
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

响应会列出每个数据集的名称、说明和创建时间。以下是命令成功执行时的响应示例：

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Dataset for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace/datasets/Spans

REST

如需列出可观测性存储桶的数据集，请向 projects.locations.buckets.datasets.list 端点发送请求。

您必须指定 parent 参数，该参数采用以下形式：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

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

PROJECT_ID：项目的标识符。
LOCATION：可观测性存储桶的位置。
BUCKET_ID：可观测性存储桶的 ID。例如，此 ID 可能是 _Trace。

响应是一个 Dataset 对象数组。对于每个对象，name 字段的值采用以下格式：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID

例如，当向 buckets.datasets.list 端点发出命令并将父参数设置为 projects/my-project/locations/us/buckets/_Trace 时，响应如下：

{
  "datasets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans",
      "description": "Trace Spans",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
    }
  ]
}

您可以向其他 Observability API 端点发出命令，以获取 ID 为 DATASET_ID 的数据集的相关信息。例如，您可以列出每个数据集中的视图和链接。如需查看完整的 Observability API 端点列表，请参阅 Observability API 参考文档。

列出数据集中的视图

gcloud

在使用下面的命令数据之前，请先进行以下替换：

DATASET_ID：数据集的 ID。您的轨迹数据存储在名为 Spans 的数据集中。
BUCKET_ID：可观测性存储桶的 ID。例如，此 ID 可能是 _Trace。
LOCATION：可观测性存储分区的位置。
PROJECT_ID：项目的标识符。

执行 gcloud beta observability buckets datasets views list 命令：

Linux、macOS 或 Cloud Shell

gcloud beta observability buckets datasets views list \
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID \
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets views list `
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID `
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets views list ^
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID ^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

响应会列出每个可观测性视图的名称、创建时间和更新时间。以下是命令成功执行时的响应示例：

---
createTime: '2026-01-21T21:39:22.381083860Z'
displayName: _AllSpans
name: projects/pamstestproject1/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans
updateTime: '2026-01-21T21:39:22.381083860Z'

REST

如需列出数据集中的视图，请向 projects.locations.buckets.datasets.views.list 端点发送请求。

您必须指定 parent 参数，该参数采用以下形式：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views

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

PROJECT_ID：项目的标识符。
LOCATION：可观测性存储桶的位置。
BUCKET_ID：可观测性存储桶的 ID。例如，此 ID 可能是 _Trace。
DATASET_ID：要查询的数据集的 ID。例如，此 ID 可能为 Spans。

响应是一个 View 对象数组。对于每个对象，name 字段的值采用以下格式：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/views/OBS_VIEW_ID

在上面的表达式中，视图的 ID 由 OBS_VIEW_ID 表示。例如，此字段的值可能为 _AllSpans。

例如，当向 buckets.datasets.views.list 端点发出命令且父参数设置为 projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views 时，响应如下：

{
  "views": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans",
      "filter": "",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
    }
  ]
}

如需查看完整的 Observability API 端点列表，请参阅 Observability API 参考文档。

列出数据集中的链接

gcloud

在使用下面的命令数据之前，请先进行以下替换：

DATASET_ID：数据集的 ID。您的轨迹数据存储在名为 Spans 的数据集中。
BUCKET_ID：可观测性存储桶的 ID。例如，此 ID 可能是 _Trace。
LOCATION：可观测性存储分区的位置。
PROJECT_ID：项目的标识符。

执行 gcloud beta observability buckets datasets links list 命令：

Linux、macOS 或 Cloud Shell

gcloud beta observability buckets datasets links list \
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID\
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets links list `
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID`
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets links list ^
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

响应会列出每个链接的名称和创建时间。以下是命令成功执行时的响应示例：

---
createTime: '2026-04-02T21:23:09.272323714Z'
name: projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links/mydataset

REST

如需列出数据集中的链接，请向 projects.locations.buckets.datasets.links.list 端点发送请求。

您必须指定 parent 参数，该参数采用以下形式：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

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

PROJECT_ID：项目的标识符。
LOCATION：可观测性存储桶的位置。
BUCKET_ID：可观测性存储桶的 ID。例如，此 ID 可能是 _Trace。
DATASET_ID：要查询的数据集的 ID。例如，此 ID 可能为 Spans。

响应是一个 Link 对象数组。对于每个对象，name 字段的值采用以下格式：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/links/LINK_ID

LINK_ID 是 BigQuery 数据集的名称。此字段对于您的 Google Cloud 项目是全局唯一的。

例如，当向 buckets.datasets.links.list 端点发出命令且父参数设置为 projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links 时，响应如下：

{
  "links": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links/my_link",
      "description": "My link for traces to BigQuery",
      "createTime": "2025-01-12T15:42:30.988919645Z"
    }
  ]
}

如需查看完整的 Observability API 端点列表，请参阅 Observability API 参考文档。

创建数据集的链接

本部分介绍了如何创建数据集链接，以便从 BigQuery 查询轨迹数据。

创建关联数据集时发生的系统操作

创建关联的数据集时，您会启动一项长时间运行的操作。该操作会触发以下几项操作：

审核日志会记录创建关联的请求以及操作的完成情况。
如果 Monitoring 服务账号不存在，Google Cloud Observability 会创建该账号。

必须先启用 Cloud Monitoring API，才能创建此服务账号。
Google Cloud Observability 需要服务账号，然后才能创建关联的数据集。在必要时，系统会创建服务账号：
- Cloud Observability 服务账号：对于观测数据集的关联是必需的。
- Cloud Logging 服务账号：日志存储桶关联所需的账号。
审核日志会记录服务代理管理器授予 Monitoring 服务账号 Monitoring Service Agent IAM 角色的请求。

准备工作

完成列出链接所需的设置。
启用 Cloud Monitoring API。
启用 API 所需的角色
如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。
启用 API
如需获得在数据集上创建关联所需的权限，请让管理员向您授予项目的以下 IAM 角色：
- Observability Editor (roles/observability.editor)
- BigQuery User (roles/bigquery.user)
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

创建关联的 BigQuery 数据集

gcloud

在使用下面的命令数据之前，请先进行以下替换：

LINK_ID：BigQuery 数据集的名称。
DATASET_ID：数据集的 ID。您的轨迹数据存储在名为 Spans 的数据集中。
BUCKET_ID：可观测性存储桶的 ID。例如，此 ID 可能是 _Trace。
LOCATION：可观测性存储分区的位置。
PROJECT_ID：项目的标识符。

执行 gcloud beta observability buckets datasets links create 命令：

Linux、macOS 或 Cloud Shell

gcloud beta observability buckets datasets links create \
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID \
 --dataset=DATASET_ID\
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets links create `
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID `
 --dataset=DATASET_ID`
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets links create ^
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID ^
 --dataset=DATASET_ID^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

create 命令会启动长时间运行的操作。以下是命令成功执行时的响应示例：

Create request issued for: [mydataset]
Waiting for operation [projects/my-project/locations/us/operations/operation-1775164903749-64e80c9817833-9ff804b6-c3e9cbe7] to complete...done.
Created link [mydataset].

REST

如需创建指向 BigQuery 数据集的链接，请向 projects.locations.buckets.datasets.links.create 端点发送请求。

您必须指定 parent 参数，该参数采用以下形式：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

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

PROJECT_ID：项目的标识符。
LOCATION：可观测性存储桶的位置。
BUCKET_ID：可观测性存储桶的 ID。例如，此 ID 可能是 _Trace。
DATASET_ID：要查询的数据集的 ID。例如，此 ID 可能为 Spans。

此命令需要查询参数和请求正文：

必须指定查询参数 linkId，并将其设置为 BigQuery 数据集的名称。例如 linkId="my_link"。BigQuery 数据集名称必须在您的 Google Cloud 项目中保持唯一，长度上限为 100 个字符，并且只能包含字母、数字和下划线。
请求正文是一个 Link 对象。name 字段的值采用以下格式：
```
projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID/links/LINK_ID
```
您为 name 字段提供的值必须与查询参数引用的关联 BigQuery 数据集相匹配。

LINK_ID 字段是 BigQuery 数据集的名称。

响应是一个 Operation 对象。此对象包含有关该方法的进度的信息。当该方法完成时，Operation 对象会包含状态数据。

如需查看完整的 Observability API 端点列表，请参阅 Observability API 参考文档。

如果您在创建关联数据集时遇到权限错误，请参阅排查权限错误。

后续步骤

如需详细了解如何使用 Trace 探索器页面，请参阅查找和探索跟踪记录。
如需了解如何使用 SQL 分析跟踪记录范围，请参阅查询和分析跟踪记录。
如需了解如何设置默认存储位置以及如何为可观测性存储分区配置客户管理的加密密钥 (CMEK)，请参阅为可观测性存储分区设置默认值。

管理轨迹存储空间 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

配置项目和角色

选择您计划使用的界面

gcloud

REST

列出可观测性存储分区

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

列出可观测性存储桶中的数据集

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

列出数据集中的视图

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

列出数据集中的链接

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

创建数据集的链接

创建关联数据集时发生的系统操作

准备工作

创建关联的 BigQuery 数据集

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

后续步骤

管理轨迹存储空间