管理可观测性存储分区

本文档介绍了如何使用 Observability API 获取有关可观测性存储分区的信息。此外，还包含有关如何列出数据集、链接和视图的信息。如需详细了解 Google Cloud Observability 如何存储数据，请参阅存储概览。

您的轨迹数据存储在可观测性存储分区中。本文档介绍了如何管理轨迹数据的存储，但未介绍所存储数据的格式。如需了解该主题，请参阅轨迹架构。

本文档不适用于日志或指标数据的存储。日志和指标数据不会存储在可观测性存储分区中。

准备工作

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

安装 Google Cloud CLI。

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

创建或选择 Google Cloud 项目。

选择或创建项目所需的角色

选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
创建项目：如需创建项目，您需要拥有 Project Creator 角色 (roles/resourcemanager.projectCreator)，该角色包含 resourcemanager.projects.create 权限。了解如何授予角色。

创建 Google Cloud 项目：
```
gcloud projects create PROJECT_ID
```
将 PROJECT_ID 替换为您要创建的 Google Cloud 项目的名称。
选择您创建的 Google Cloud 项目：
```
gcloud config set project PROJECT_ID
```
将 PROJECT_ID 替换为您的 Google Cloud 项目名称。

验证是否已为您的 Google Cloud 项目启用结算功能。

启用 Observability API：

启用 API 所需的角色

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

gcloud services enable observability.googleapis.com

向您的用户账号授予角色。对以下每个 IAM 角色运行以下命令一次： roles/observability.viewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

替换以下内容：

PROJECT_ID：您的项目 ID。
USER_IDENTIFIER：您的用户账号的标识符。例如，myemail@example.com。
ROLE：您授予用户账号的 IAM 角色。

安装 Google Cloud CLI。

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

创建或选择 Google Cloud 项目。

选择或创建项目所需的角色

选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
创建项目：如需创建项目，您需要拥有 Project Creator 角色 (roles/resourcemanager.projectCreator)，该角色包含 resourcemanager.projects.create 权限。了解如何授予角色。

创建 Google Cloud 项目：
```
gcloud projects create PROJECT_ID
```
将 PROJECT_ID 替换为您要创建的 Google Cloud 项目的名称。
选择您创建的 Google Cloud 项目：
```
gcloud config set project PROJECT_ID
```
将 PROJECT_ID 替换为您的 Google Cloud 项目名称。

验证是否已为您的 Google Cloud 项目启用结算功能。

启用 Observability API：

启用 API 所需的角色

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

gcloud services enable observability.googleapis.com

向您的用户账号授予角色。对以下每个 IAM 角色运行以下命令一次： roles/observability.viewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

替换以下内容：

PROJECT_ID：您的项目 ID。
USER_IDENTIFIER：您的用户账号的标识符。例如，myemail@example.com。
ROLE：您授予用户账号的 IAM 角色。

列出可观测性存储分区

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 参考文档。

列出观测桶中的数据集

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 参考文档。

列出数据集中的视图

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 参考文档。

列出数据集中的链接

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 查询轨迹数据。您还可以删除附加到数据集的 Link 对象。

准备工作

如需获得在数据集上创建关联所需的权限，请让管理员向您授予项目的以下 IAM 角色：

Observability Editor (roles/observability.editor)
BigQuery User (roles/bigquery.user)

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

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

创建关联的 BigQuery 数据集

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 参考文档。

后续步骤

如需了解如何查询遥测数据，请参阅查看和分析遥测数据。

管理可观测性存储分区 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

列出可观测性存储分区

REST

列出观测桶中的数据集

REST

列出数据集中的视图

REST

列出数据集中的链接

REST

创建数据集的链接

准备工作

创建关联的 BigQuery 数据集

REST

后续步骤

管理可观测性存储分区