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

列出追蹤記錄 bucket 並管理資料集

您可以使用 Observability API 或 Google Cloud CLI 查看觀測能力 bucket、檢查資料集和檢視表，以及建立連結，以便使用 SQL 分析儲存的追蹤記錄資料。您也可以使用 Terraform 建立連結。

如需概念背景和儲存空間詳細資料，請參閱「Trace 儲存空間總覽」和「Trace 結構定義」。

事前準備

設定專案和 Identity and Access Management (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, 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

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

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

選取要使用的介面

gcloud

安裝 Google Cloud CLI，然後使用聯合身分登入 gcloud CLI。登入後，執行下列指令來初始化 Google Cloud CLI：

gcloud init

Terraform

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

安裝 Google Cloud CLI。
設定 gcloud CLI，使用您的聯合身分。

詳情請參閱「使用聯合身分登入 gcloud CLI」。
為使用者帳戶建立本機驗證憑證：
```
gcloud auth application-default login
```
如果傳回驗證錯誤，請確認您已使用聯合身分登入 gcloud CLI。

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

REST

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

安裝 Google Cloud CLI，然後使用聯合身分登入 gcloud CLI。

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

列出觀測能力 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 參考文件。

列出觀測能力 bucket 中的資料集

本節說明如何列出觀測能力 bucket 中的觀測能力資料集。觀測能力 bucket 是資料集的管理容器，用於儲存資料。Google Cloud Observability 建立 bucket 時，會自動建立資料集。

gcloud

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

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

執行 gcloud observability buckets datasets list 指令：

Linux、macOS 或 Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

gcloud 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

Terraform

您無法使用 Terraform 列出觀測能力資料集。

REST

如要列出觀測能力 bucket 的資料集，請使用 projects.locations.buckets.datasets.list 方法。

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

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

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

回應是 Dataset 物件陣列。每個物件的 name 欄位值格式如下：

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

以下是回應範例：

{
  "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 參考文件。

列出資料集的清單檢視

本節說明如何列出觀測能力檢視畫面。每個觀測能力資料集都會託管一或多個檢視表。檢視表可讓您讀取資料集中的部分項目。Google Cloud Observability 會在建立資料集時建立檢視表。該檢視表包含資料集中的所有資料。

gcloud

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

DATASET_ID：資料集的 ID。追蹤記錄資料會儲存在名為 Spans 的資料集中。
BUCKET_ID：觀測能力值區的 ID。例如，這個 ID 可能是 _Trace。
LOCATION：觀測能力 bucket 的位置。
PROJECT_ID：專案 ID。

執行 gcloud observability buckets datasets views list 指令：

Linux、macOS 或 Cloud Shell

gcloud 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 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 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'

Terraform

您無法使用 Terraform 列出觀測能力檢視畫面。

REST

如要列出資料集的檢視表，請使用 projects.locations.buckets.datasets.views.list 方法。

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

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

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

PROJECT_ID：專案 ID。
LOCATION：觀測能力 bucket 的位置。
BUCKET_ID：觀測能力值區的 ID。例如 _Trace。
DATASET_ID：查詢的資料集 ID。例如，這個 ID 可能是 Spans。

回應是 View 物件陣列。每個物件的 name 欄位值格式如下：

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

在上述運算式中，檢視畫面的 ID 以 OBS_VIEW_ID 表示。舉例來說，這個欄位的值可能是 _AllSpans。

以下是回應範例：

{
  "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 參考文件。

列出資料集的連結

本節說明如何列出觀測能力資料集的連結。連結可讓您使用 BigQuery 服務查詢資料，或讓 Google Cloud 服務查詢該資料的子集。

gcloud

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

DATASET_ID：資料集的 ID。追蹤記錄資料會儲存在名為 Spans 的資料集中。
BUCKET_ID：觀測能力值區的 ID。例如，這個 ID 可能是 _Trace。
LOCATION：觀測能力 bucket 的位置。
PROJECT_ID：專案 ID。

執行 gcloud observability buckets datasets links list 指令：

Linux、macOS 或 Cloud Shell

gcloud 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 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 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

Terraform

您無法使用 Terraform 列出觀測能力資料集的連結。

REST

如要列出資料集的連結，請使用 projects.locations.buckets.datasets.links.list 方法。

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

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

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

PROJECT_ID：專案 ID。
LOCATION：觀測能力 bucket 的位置。
BUCKET_ID：觀測能力值區的 ID。例如 _Trace。
DATASET_ID：查詢的資料集 ID。例如，這個 ID 可能是 Spans。

回應是 Link 物件陣列。每個物件的 name 欄位值格式如下：

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

LINK_ID 是 BigQuery 資料集的名稱。這個欄位在 Google Cloud 專案中不得重複。

以下是回應範例：

{
  "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 參考文件。

建立資料集連結

本節說明如何為觀測能力資料集建立連結的 BigQuery 資料集，以便使用 BigQuery 服務查詢追蹤記錄資料。每個觀測能力資料集都支援一個連結的 BigQuery 資料集。

在觀測能力資料集建立連結時，會發生下列情況：

Google Cloud Observability 可能會建立下列服務帳戶，或修改其 IAM 角色授權：
- 監控服務帳戶：必須具備此角色，才能建立連結至 BigQuery 資料集的連結。必須啟用 Cloud Monitoring API，Google Cloud Observability 才能建立這個服務帳戶。
- Cloud Observability 服務帳戶：必須具備這項權限，才能在觀測能力資料集建立連結。
- Cloud Logging 服務帳戶：必須具備這個角色，才能在記錄檔 bucket 建立連結。
稽核記錄會記錄建立連結的要求，以及服務代理管理員要求授予 Monitoring 服務帳戶 Monitoring 服務代理 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 Cloud Monitoring and Observability APIs, if any are 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 APIs

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

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

建立連結的 BigQuery 資料集

gcloud

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

LINK_ID：BigQuery 資料集的名稱。
DATASET_ID：資料集的 ID。追蹤記錄資料會儲存在名為 Spans 的資料集中。
BUCKET_ID：觀測能力值區的 ID。例如，這個 ID 可能是 _Trace。
LOCATION：觀測能力 bucket 的位置。
PROJECT_ID：專案 ID。

執行 gcloud observability buckets datasets links create 指令：

Linux、macOS 或 Cloud Shell

gcloud 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 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 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].

Terraform

如要在觀測能力資料集上建立連結，請使用 Terraform 資源 google_observability_link，並設定下列欄位：

project：專案 ID。
location：連結的位置，這個位置必須與觀測能力 bucket 的位置相符。
bucket：觀測能力值區的 ID。例如：_Trace。
dataset：觀測能力資料集的 ID。例如：Spans。
link_id：BigQuery 資料集的 ID。

也可以更新及刪除連結。

REST

如要建立 BigQuery 資料集的連結，請傳送要求至 projects.locations.buckets.datasets.links.create 端點。

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

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

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

PROJECT_ID：專案 ID。
LOCATION：觀測能力 bucket 的位置。
BUCKET_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/datasets/DATASET_ID/links/LINK_ID
```
您為 name 欄位提供的值，必須與查詢參數參照的連結 BigQuery 資料集相符。

LINK_ID 欄位是 BigQuery 資料集的名稱。

回應為 Operation 物件。這個物件包含方法的進度資訊。方法完成後，Operation 物件會包含狀態資料。

如需 Observability API 端點的完整清單，請參閱 Observability API 參考文件。

如果在建立連結資料集時遇到權限錯誤，請參閱「排解權限錯誤」。

後續步驟

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

列出追蹤記錄 bucket 並管理資料集 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

設定專案和角色

選取要使用的介面

gcloud

Terraform

REST

列出觀測能力 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

列出資料集的清單檢視

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

列出資料集的連結

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

建立資料集連結

事前準備

建立連結的 BigQuery 資料集

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

後續步驟

列出追蹤記錄 bucket 並管理資料集