オブザーバビリティバケットを管理する

このドキュメントでは、Observability API を使用してオブザーバビリティバケットに関する情報を取得する方法について説明します。また、データセット、リンク、ビューを一覧表示する方法についても説明します。 Google Cloud Observability でデータが保存される仕組みについては、ストレージの概要をご覧ください。

トレースデータはオブザーバビリティバケットに保存されます。このドキュメントでは、トレースデータのストレージを管理する方法について説明しますが、保存されたデータの形式については説明しません。このトピックについては、トレーススキーマをご覧ください。

このドキュメントは、ログデータまたは指標データのストレージには適用されません。ログデータと指標データはオブザーバビリティバケットに保存されません。

始める前に

アカウントにログインします。 Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。 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

バケット、リンク、ビューを一覧表示するために必要な権限を取得するには、プロジェクトに対するオブザーバビリティ閲覧者（roles/observability.viewer）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
このページのサンプルをどのように使うかに応じて、タブを選択してください。
gcloud

コンソールで Cloud Shell をアクティブにします。 Google Cloud

Cloud Shell をアクティブにする

コンソールの下部にある Google Cloud Cloud Shell セッションが開始し、コマンドラインプロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
REST

このページの REST API サンプルをローカル開発環境で使用するには、 gcloud CLI に指定した認証情報を使用します。
詳細については、 REST を使用して認証する認証ドキュメントの Google Cloud をご覧ください。

オブザーバビリティバケットを一覧表示する

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

LOCATION: オブザーバビリティバケットのロケーション。ロケーションに関係なくすべてのオブザーバビリティバケットを一覧表示するには、ロケーションをハイフン（-）に設定します。
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

レスポンスには、各オブザーバビリティバケットの名前、説明、作成時刻が表示されます。コマンドが成功した場合のレスポンスの例を次に示します。

---
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 エンドポイントにリクエストを送信します。

次の形式の parent パラメータを指定する必要があります。

projects/PROJECT_ID/locations/LOCATION

前の式のフィールドの意味は次のとおりです。

PROJECT_ID: プロジェクトの ID。
LOCATION: オブザーバビリティバケットのロケーション。 LOCATION をハイフン (-) に設定すると、プロジェクト内のすべてのオブザーバビリティバケットが一覧表示されます。

レスポンスは Bucket オブジェクトの配列です。各オブジェクトの name フィールドの値の形式は次のとおりです。

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

たとえば、parent パラメータを projects/my-project/locations/us に設定して buckets.list エンドポイントにコマンドを発行した場合、レスポンスは次のようになります。

{
  "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
    }
  ]
}

BUCKET_ID の ID を持つバケットの詳細情報を取得するには、他の Observability API エンドポイントにコマンドを発行します。たとえば、そのバケットのデータセット、各データセットのビューとリンクを一覧表示できます。Observability API エンドポイントの一覧については、 Observability API リファレンスドキュメントをご覧ください。

オブザーバビリティバケットのデータセットを一覧表示する

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

BUCKET_ID: オブザーバビリティバケットの ID。たとえば、この ID は _Trace になります。
LOCATION: オブザーバビリティバケットのロケーション。
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

オブザーバビリティバケットのデータセットを一覧表示するには、 projects.locations.buckets.datasets.list エンドポイントにリクエストを送信します。

次の形式の parent パラメータを指定する必要があります。

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

前の式のフィールドの意味は次のとおりです。

PROJECT_ID: プロジェクトの ID。
LOCATION: オブザーバビリティバケットのロケーション。
BUCKET_ID: オブザーバビリティバケットの ID。たとえば、この ID は _Trace になります。

レスポンスは Dataset オブジェクトの配列です。各オブジェクトの name フィールドの値の形式は次のとおりです。

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

たとえば、parent パラメータを projects/my-project/locations/us/buckets/_Trace に設定して buckets.datasets.list エンドポイントにコマンドを発行した場合、レスポンスは次のようになります。

{
  "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",
    }
  ]
}

DATASET_ID の ID を持つデータセットに関する情報を取得するには、他の Observability API エンドポイントにコマンドを発行します。DATASET_IDたとえば、各データセットのビューとリンクを一覧表示できます。 Observability API エンドポイントの一覧については、 Observability API リファレンスドキュメントをご覧ください。

データセットのビューを一覧表示する

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

DATASET_ID: データセットの ID。トレースデータは `Spans` Spansという名前のデータセットに保存されます。
BUCKET_ID: オブザーバビリティバケットの ID。たとえば、この ID は _Trace になります。
LOCATION: オブザーバビリティバケットのロケーション。
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 エンドポイントにリクエストを送信します。

次の形式の parent パラメータを指定する必要があります。

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

前の式のフィールドの意味は次のとおりです。

PROJECT_ID: プロジェクトの ID。
LOCATION: オブザーバビリティバケットのロケーション。
BUCKET_ID: オブザーバビリティバケットの 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 になります。

たとえば、parent パラメータを projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views に設定して buckets.datasets.views.list エンドポイントにコマンドを発行した場合、レスポンスは次のようになります。

{
  "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` Spansという名前のデータセットに保存されます。
BUCKET_ID: オブザーバビリティバケットの ID。たとえば、この ID は _Trace になります。
LOCATION: オブザーバビリティバケットのロケーション。
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 エンドポイントにリクエストを送信します。

次の形式の parent パラメータを指定する必要があります。

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

前の式のフィールドの意味は次のとおりです。

PROJECT_ID: プロジェクトの ID。
LOCATION: オブザーバビリティバケットのロケーション。
BUCKET_ID: オブザーバビリティバケットの 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

たとえば、parent パラメータを projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links に設定して buckets.datasets.links.list エンドポイントにコマンドを発行した場合、レスポンスは次のようになります。

{
  "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` Spansという名前のデータセットに保存されます。
BUCKET_ID: オブザーバビリティバケットの ID。たとえば、この ID は _Trace になります。
LOCATION: オブザーバビリティバケットのロケーション。
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 エンドポイントにリクエストを送信します。

次の形式の parent パラメータを指定する必要があります。

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

前の式のフィールドの意味は次のとおりです。

PROJECT_ID: プロジェクトの ID。
LOCATION: オブザーバビリティバケットのロケーション。
BUCKET_ID: オブザーバビリティバケットの 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

オブザーバビリティ バケットを一覧表示する

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

データセットのリンクを一覧表示する

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

REST

データセットにリンクを作成する

始める前に

リンクされた BigQuery データセットを作成する

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

REST

次のステップ

オブザーバビリティバケットを管理する

オブザーバビリティバケットを一覧表示する

オブザーバビリティバケットのデータセットを一覧表示する