トレースストレージを管理する

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

始める前に

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $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

バケット、リンク、ビューを一覧表示するために必要な権限を取得するには、プロジェクトに対する Observability 閲覧者（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 を使用して認証するをご覧ください。

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

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

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

projects/PROJECT_ID/locations/LOCATION

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

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

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

たとえば、親パラメータが 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
    }
  ]
}

他の Observability API エンドポイントにコマンドを発行して、ID が BUCKET_ID のバケットに関する詳細情報を取得できます。たとえば、そのバケットのデータセットと、各データセットのビューとリンクを一覧表示できます。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 エンドポイントにリクエストを送信します。

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

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

たとえば、親パラメータが 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",
    }
  ]
}

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

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

gcloud

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

DATASET_ID: データセットの ID。トレースデータは、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 エンドポイントにリクエストを送信します。

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

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 になります。

たとえば、親パラメータが 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 という名前のデータセットに保存されます。
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 エンドポイントにリクエストを送信します。

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

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 プロジェクトでグローバルに一意です。

たとえば、親パラメータが 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 からトレースデータをクエリできるようにする方法について説明します。

始める前に

サイトリンクを表示するための必須の設定を完了します。
データセットにリンクを作成するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
- オブザーバビリティ編集者（roles/observability.editor）
- BigQuery ユーザー（roles/bigquery.user）
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

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

gcloud

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

LINK_ID: BigQuery データセットの名前。
DATASET_ID: データセットの ID。トレースデータは、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 エンドポイントにリクエストを送信します。

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

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 リファレンスドキュメントをご覧ください。

次のステップ

[Trace エクスプローラ] ページの使用方法の詳細については、トレースを検索して調査するをご覧ください。

SQL を使用してトレーススパンを分析する方法については、トレースをクエリして分析するをご覧ください。

トレース ストレージを管理する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

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

次のステップ

トレースストレージを管理する

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

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