管理可觀測性值區

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

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

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

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

安裝 Google Cloud CLI。

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

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
建立專案：如要建立專案，您需要具備專案建立者角色 (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，您需要具備服務使用情形管理員 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：使用者帳戶的 ID。例如：myemail@example.com。
ROLE：授予使用者帳戶的 IAM 角色。

安裝 Google Cloud CLI。

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

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
建立專案：如要建立專案，您需要具備專案建立者角色 (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，您需要具備服務使用情形管理員 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：使用者帳戶的 ID。例如：myemail@example.com。
ROLE：授予使用者帳戶的 IAM 角色。

列出可觀測性 bucket

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 的值區。舉例來說，您可以列出該值區中的資料集，以及每個資料集的檢視畫面和連結。如需 Observability API 端點的完整清單，請參閱 Observability API 參考說明文件。

列出觀測 bucket 中的資料集

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 參考說明文件。

列出資料集中的檢視表

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 參考說明文件。

列出資料集的連結

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 資料集

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 參考說明文件。

後續步驟

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

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

事前準備

列出可觀測性 bucket

REST

列出觀測 bucket 中的資料集

REST

列出資料集中的檢視表

REST

列出資料集的連結

REST

建立資料集連結

事前準備

建立連結的 BigQuery 資料集

REST

後續步驟

管理可觀測性值區