创建可观测性存储分区

您可以在项目接收跟踪记录数据之前手动创建 _Trace 可观测性存储桶，以自定义其存储位置和客户管理的加密密钥 (CMEK) 设置。如果您的 Google Cloud 项目 在此存储桶存在之前提取跟踪记录数据，则 Google Cloud Observability 会使用项目的 可观测性存储桶的默认设置自动 预配该存储桶。

如需了解 Google Cloud Observability 如何存储数据，请参阅 存储概览。

与组织政策互动

创建可观测性存储桶的请求会验证命令参数是否符合组织政策。例如，如果组织政策限制了资源位置，那么如果您指定了受限位置，则创建存储桶会失败。

与可观测性存储桶的默认设置互动

当 Google Cloud Observability 因提取数据而自动创建可观测性存储桶时，它会使用适用于存储桶父资源的可观测性存储桶的默认设置。这些默认设置可能在父资源中或父资源的分层祖先中定义，它们指定了以下内容：

  • 存储位置。
  • 用于存储数据的 Cloud KMS 密钥。

创建可观测性存储桶时，您必须指定位置 。 除非您在创建请求中明确指定其他密钥，否则 Google Cloud Observability 会应用在默认设置中定义的 Cloud KMS 密钥。

如果适用的默认设置指定了 Cloud KMS 密钥，则您无法使用 Google 默认加密创建存储桶。如需使用 Google 默认加密，请确保您的默认设置中未配置 Cloud KMS 密钥。

如需了解可观测性存储桶的默认设置，请参阅 设置可观测性存储桶的默认值。

限制

需要遵循以下限制：

  • 您必须指定受 支持的位置。
  • BUCKET_ID 必须是 _Trace。
  • 显示名称不得超过 100 个编码字节。
  • 说明不得超过 1000 个编码字节。
  • 数据存储 30 天。您必须省略保留期限，或将其设置为 30。
  • 如果您提供 Cloud KMS 密钥，则密钥的位置必须与可观测性存储桶的父位置完全一致。
  • 您只能在 Google Cloud 项目中创建可观测性存储桶。
  • 一个 Google Cloud 项目最多只能有一个名为_Trace的可观测性存储桶。

准备工作

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

配置项目和角色

  1. 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

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

  3. 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

  4. 如要获得创建可观测性存储桶所需的权限，请让您的管理员为您授予项目的 Observability Editor (roles/observability.editor) 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 时进行身份验证。

配置 Cloud KMS 密钥

可选。如果您计划创建可观测性存储桶并指定 Cloud KMS 密钥，请执行以下操作：

  1. 启用 Cloud Key Management Service API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。了解如何授予角色。

    启用 API

  2. 创建密钥环和密钥。

    可观测性存储桶的位置必须与密钥的位置一致。

  3. 将 PROJECT_ID 替换为您的项目 ID，然后运行以下 命令：

    gcloud beta observability settings describe \
--location=global --project=PROJECT_ID

    上述命令会检查您是否已配置默认存储位置。如果 Google Cloud Observability 服务帐号不存在，该命令还会创建该账号。该命令的响应会列出服务帐号的 ID。

  4. 将 Cloud KMS CryptoKey Encrypter/Decrypter 角色授予 Google Cloud Observability 服务帐号。

    gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-observability. \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY_NAME

    在运行上述命令之前，请进行以下替换：

    • KMS_PROJECT_ID：运行 Cloud KMS 的 Google Cloud 项目的唯一字母数字 标识符，由 Google Cloud 项目名称和随机分配的编号组成。 如需了解如何获取此标识符，请参阅 标识项目。
    • service-PROJECT_NUMBER：在上一步的响应中列出的 Observability 服务 账号的名称。
    • KMS_KEY_LOCATION：Cloud KMS 密钥的区域。
    • KMS_KEY_RING：Cloud KMS 密钥环的名称。
    • KMS_KEY_NAME：Cloud KMS 密钥的名称。其格式如下所示： projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY。

创建可观测性存储桶

REST

如需创建可观测性存储桶，请向 projects.locations.buckets.create发送请求。

您必须指定父参数，其格式如下：

projects/PROJECT_ID/locations/LOCATION

上一个表达式中的字段具有以下含义：

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

请求正文是一个 Bucket 对象。填写以下字段：

  • name：将此字段设置为以下内容：

    projects/PROJECT_ID/locations/LOCATION/buckets/_Trace

  • 可选：为 displayName 和 description 字段提供值。

  • 可选：提供 CMEK。指定后，此密钥会对存储的数据进行加密。

    如果您未提供 CMEK，则适用于存储桶父资源的默认设置会确定加密密钥。如果默认设置指定了 Cloud KMS 密钥，则该密钥会对存储的数据进行加密。否则，系统会使用 Google 默认加密。

响应是一个 Operation 对象。轮询 projects.locations.operations.get 方法，直到 Operation.done 字段设置为 true。Operation 结构中的其他字段提供有关请求成功或失败的信息。

列出可观测性存储桶

您可以列出可观测性存储桶，以验证创建请求是否已成功完成。

本部分介绍如何列出可观测性存储桶。可观测性存储桶是存储数据的数据集的管理实体。

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 方法。

您必须指定父参数，其格式如下：

projects/PROJECT_ID/locations/LOCATION

上一个表达式中的字段具有以下含义：

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

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

以下显示了一个示例响应：

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

后续步骤