管理可觀測性值區

本文說明如何使用 Observability API 取得觀測值 bucket 的相關資訊。此外，還會說明如何列出資料集、連結和檢視畫面。如要進一步瞭解 Google Cloud Observability 如何儲存資料，請參閱儲存空間總覽。

追蹤記錄資料會儲存在可觀測性 bucket 中。本文說明如何管理追蹤資料的儲存空間，但不會說明儲存資料的格式。如要瞭解該主題，請參閱「追蹤結構定義」。

本文不適用於記錄或指標資料的儲存。記錄和指標資料不會儲存在可觀測性 bucket 中。

事前準備

登入 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.

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

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.

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

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

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。
選取這個頁面上的分頁，瞭解如何使用範例：
gcloud

在 Google Cloud 控制台中啟用 Cloud Shell。

啟用 Cloud Shell

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

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。
詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

列出可觀測性 bucket

gcloud

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

LOCATION：可觀測性 bucket 的位置。如要列出所有可觀測性值區 (不論位置為何)，請將位置設為連字號 (-)。
PROJECT_ID：專案的 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

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

---
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：專案的 ID。
LOCATION：可觀測性 bucket 的位置。如果將 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 的 bucket。舉例來說，您可以列出該值區中的資料集，以及每個資料集的檢視畫面和連結。如需 Observability API 端點的完整清單，請參閱 Observability API 參考文件。

列出觀測 bucket 中的資料集

gcloud

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

BUCKET_ID：可觀測性 Bucket 的 ID。舉例來說，這個 ID 可能是 _Trace。
LOCATION：可觀測性 bucket 的位置。
PROJECT_ID：專案的 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

如要列出可觀測性 bucket 的資料集，請將要求傳送至 projects.locations.buckets.datasets.list 端點。

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

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

PROJECT_ID：專案的 ID。
LOCATION：可觀測性 bucket 的位置。
BUCKET_ID：可觀測性 Bucket 的 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：可觀測性 Bucket 的 ID。舉例來說，這個 ID 可能是 _Trace。
LOCATION：可觀測性 bucket 的位置。
PROJECT_ID：專案的 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 端點。

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

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

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

PROJECT_ID：專案的 ID。
LOCATION：可觀測性 bucket 的位置。
BUCKET_ID：可觀測性 Bucket 的 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：可觀測性 Bucket 的 ID。舉例來說，這個 ID 可能是 _Trace。
LOCATION：可觀測性 bucket 的位置。
PROJECT_ID：專案的 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 端點傳送要求。

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

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

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

PROJECT_ID：專案的 ID。
LOCATION：可觀測性 bucket 的位置。
BUCKET_ID：可觀測性 Bucket 的 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 角色：
- 可觀測性編輯者 (roles/observability.editor)
- BigQuery 使用者 (roles/bigquery.user)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

建立連結的 BigQuery 資料集

gcloud

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

LINK_ID：BigQuery 資料集的名稱。
DATASET_ID：資料集 ID。您的追蹤資料會儲存在名為 Spans 的資料集中。
BUCKET_ID：可觀測性 Bucket 的 ID。舉例來說，這個 ID 可能是 _Trace。
LOCATION：可觀測性 bucket 的位置。
PROJECT_ID：專案的 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 端點。

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

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

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

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

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

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

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

後續步驟

如要瞭解如何查詢遙測資料，請參閱「查看及分析遙測資料」。

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

事前準備

gcloud

REST

列出可觀測性 bucket

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

列出觀測 bucket 中的資料集

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

後續步驟

管理可觀測性值區