Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

建立可觀測性 bucket

在專案收到追蹤記錄資料之前，您可以手動建立 _Trace 觀測能力 bucket，自訂儲存位置和客戶自行管理的加密金鑰 (CMEK) 設定。如果 Google Cloud 專案在這個 bucket 存在前就擷取追蹤記錄資料，Google Cloud Observability 會使用專案的觀測能力 bucket 預設設定，自動佈建 bucket。

如要瞭解 Google Cloud Observability 如何儲存資料，請參閱「儲存空間總覽」。

與組織政策的互動

建立觀測能力 bucket 的要求會驗證指令參數是否符合組織政策。舉例來說，如果組織政策限制資源位置，則指定受限位置時，建立 bucket 就會失敗。

與觀測能力 bucket 預設設定的互動

Google Cloud Observability 因擷取資料而自動建立觀測能力 bucket 時，會使用適用於 bucket 父項資源的觀測能力 bucket 預設設定。這些預設設定可能定義在父項或父項的階層祖系中，並指定下列項目：

儲存位置。
用於儲存資料的 Cloud KMS 金鑰。

建立觀測能力 bucket 時，必須指定位置。除非您在建立要求中明確指定其他金鑰，否則 Google Cloud Observability 會套用預設設定中定義的 Cloud KMS 金鑰。

如果適用的預設設定指定 Cloud KMS 金鑰，您就無法建立採用 Google 預設加密機制的值區。如要使用 Google 預設加密，請確認預設設定中未設定 Cloud KMS 金鑰。

如要瞭解觀測能力 bucket 的預設設定，請參閱「設定觀測能力 bucket 的預設值」。

限制

相關限制如下：

您必須指定支援的位置。
BUCKET_ID 必須是 _Trace。
顯示名稱不得超過 100 個編碼位元組。
說明不得超過 1000 個編碼位元組。
資料會保存 30 天。您必須省略保留期限，或將其設為 30。
如果提供 Cloud KMS 金鑰，金鑰位置必須與觀測能力 bucket 的上層位置完全一致。
您只能在 Google Cloud 專案中建立觀測能力 bucket。
一個 Google Cloud 專案最多只能有一個名為 _Trace 的觀測能力 bucket。

事前準備

設定專案和 IAM 角色，並選取要使用的介面。

設定專案和角色

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

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

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API, if it is not already enabled.

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

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

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API, if it is not already enabled.

Roles required to enable APIs

Enable the API

如要取得建立觀測能力 bucket 所需的權限，請要求管理員授予您專案的觀測能力編輯者 (roles/observability.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

設定介面

gcloud

在 Google Cloud 控制台啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

Terraform

如要在本機開發環境中使用本頁的 Terraform 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

安裝 Google Cloud CLI。
若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。
如果您使用的是本機殼層，請為使用者帳戶建立本機驗證憑證：
```
gcloud auth application-default login
```
如果您使用的是 Cloud Shell，則不必執行這項操作。

如果系統傳回驗證錯誤，且您使用的是外部識別資訊提供者 (IdP)，請確認您已使用聯合身分登入 gcloud CLI。

詳情請參閱 Google Cloud 驗證說明文件中的「為本機開發環境設定 ADC」。

REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」一節。

設定 Cloud KMS 金鑰

選用。如要建立觀測能力 bucket 並指定 Cloud KMS 金鑰，請按照下列步驟操作：

啟用 Cloud Key Management Service API (如果尚未啟用)。
啟用 API 所需的角色
如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
啟用 API
建立金鑰環和金鑰。

觀測能力 bucket 的位置必須與金鑰位置相符。
將 PROJECT_ID 替換為專案 ID，然後執行下列指令：
```
gcloud observability settings describe \
--location=global --project=PROJECT_ID
```
上述指令會檢查您是否已設定預設儲存位置。如果 Google Cloud Observability 服務帳戶不存在，也會建立該帳戶。指令的回應會列出服務帳戶的 ID。
將 Cloud KMS CryptoKey 加密者/解密者角色授予 Google Cloud Observability 服務帳戶。
```
gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-observability.iam.gserviceaccount.com \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY_NAME
```
執行上述指令前，請先完成下列替換作業：
- KMS_PROJECT_ID：執行 Cloud KMS 的 Google Cloud 專案專屬英數字元 ID，由 Google Cloud 專案名稱和隨機指派的數字組成。如要瞭解如何取得這個 ID，請參閱「識別專案」。
- service-PROJECT_NUMBER：上一個步驟回應中列出的觀測能力服務帳戶名稱。
- 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。

建立觀測能力 bucket

gcloud

使用下列任何指令資料前，請先替換以下項目：

BUCKET_ID：觀測能力值區的 ID。例如，這個 ID 可能是 _Trace。
LOCATION：觀測能力 bucket 的位置。
PROJECT_ID：專案 ID。

gcloud CLI 指令也提供設定顯示名稱、說明和 Cloud KMS 金鑰的選項。詳情請參閱「gcloud observability buckets create」。

執行 gcloud observability buckets create 指令：

Linux、macOS 或 Cloud Shell

gcloud observability buckets create BUCKET_ID \
 --location=LOCATION --project=PROJECT_ID

Windows (PowerShell)

gcloud observability buckets create BUCKET_ID `
 --location=LOCATION --project=PROJECT_ID

Windows (cmd.exe)

gcloud observability buckets create BUCKET_ID ^
 --location=LOCATION --project=PROJECT_ID

create 指令會啟動長時間執行的作業，並封鎖作業，直到作業完成。以下是指令成功時的回應範例：

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

Terraform

如要建立觀測能力 bucket，請使用 Terraform 資源 google_observability_bucket，並設定下列欄位：

project：專案 ID。
location：觀測能力 bucket 的位置。詳情請參閱「位置」。
bucket_id：觀測能力值區的 ID。這個欄位必須設為 _Trace。

您也可以設定說明和顯示名稱，並提供 CMEK。詳情請參閱資源說明文件。

REST

如要建立觀測能力 bucket，請傳送要求至 projects.locations.buckets.create。

您必須指定 parent 參數，格式如下：

projects/PROJECT_ID/locations/LOCATION

上述運算式中的欄位具有下列意義：

PROJECT_ID：專案 ID。
LOCATION：觀測能力 bucket 的位置。

要求主體是 Bucket 物件。填寫下列欄位：

name：將這個欄位設為：

projects/PROJECT_ID/locations/LOCATION/buckets/_Trace

選用：提供 displayName 和 description 欄位的值。
選用：提供 CMEK。指定後，這組金鑰會加密儲存的資料。

如未提供 CMEK，則會根據套用至 bucket 父項資源的預設設定，決定加密金鑰。如果預設設定指定 Cloud KMS 金鑰，則該金鑰會加密儲存的資料。否則，系統會使用 Google 預設加密。

回應為 Operation 物件。輪詢 projects.locations.operations.get 方法，直到 Operation.done 欄位設為 true 為止。Operation 結構中的其他欄位會提供要求成功或失敗的相關資訊。

列出觀測能力 bucket

您可以列出觀測能力 bucket，確認建立要求已成功完成。

本節說明如何列出觀測能力 bucket。觀測能力 bucket 是資料集的管理實體，用於儲存資料。

gcloud

使用下列任何指令資料前，請先替換以下項目：

LOCATION：觀測能力 bucket 的位置。如要列出所有觀測能力 bucket (不限位置)，請將位置設為連字號 (-)。
PROJECT_ID：專案 ID。

執行 gcloud observability buckets list 指令：

Linux、macOS 或 Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

回應會列出各個觀測能力 bucket 的名稱、說明和建立時間。以下是指令成功時的回應範例：

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

Terraform

您無法使用 Terraform 列出觀測能力 bucket。

REST

如要列出專案中特定位置的可觀測性 bucket，請使用 projects.locations.buckets.list 方法。

您必須指定 parent 參數，格式如下：

projects/PROJECT_ID/locations/LOCATION

上述運算式中的欄位具有下列意義：

PROJECT_ID：專案 ID。
LOCATION：觀測能力 bucket 的位置。如果將 LOCATION 設為連字號 (-)，系統會列出專案中的所有觀測能力 bucket。

回應是 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 的 bucket。例如，您可以列出該 bucket 中的資料集，以及每個資料集的檢視表和連結。詳情請參閱Observability API 參考文件。

後續步驟

尋找及探索追蹤記錄
使用 SQL 查詢及分析追蹤記錄
設定觀測能力 bucket 的預設值：設定觀測能力 bucket 的預設儲存位置和預設客戶自行管理的加密金鑰 (CMEK)。

建立可觀測性 bucket 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

與組織政策的互動

與觀測能力 bucket 預設設定的互動

限制

事前準備

設定專案和角色

設定介面

gcloud

Terraform

REST

設定 Cloud KMS 金鑰

建立觀測能力 bucket

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

列出觀測能力 bucket

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

後續步驟

建立可觀測性 bucket