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

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

始める前に

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

Google Cloud CLI をインストールします。

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して 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 を有効にするには、権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。serviceusage.services.enableロールを付与する方法を確認する。

gcloud services enable observability.googleapis.com

ユーザーアカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。roles/observability.viewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

次のように置き換えます。

PROJECT_ID: プロジェクト ID。
USER_IDENTIFIER: ユーザーアカウントの識別子。例: myemail@example.com。
ROLE: ユーザーアカウントに付与する IAM ロール。

Google Cloud CLI をインストールします。

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して 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 を有効にするために必要なロール

gcloud services enable observability.googleapis.com

ユーザーアカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。roles/observability.viewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

次のように置き換えます。

PROJECT_ID: プロジェクト ID。
USER_IDENTIFIER: ユーザーアカウントの識別子。例: myemail@example.com。
ROLE: ユーザーアカウントに付与する IAM ロール。

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

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

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

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

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

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

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

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 からトレースデータをクエリできます。

始める前に

データセットにリンクを作成するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

オブザーバビリティ編集者（roles/observability.editor）
BigQuery ユーザー（roles/bigquery.user）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

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

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

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 データセット名はプロジェクト内で一意である必要があり、100 文字以内で、英数字とアンダースコアのみを含めることができます。 Google Cloud
リクエスト本文は 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 でトレーススパンを分析する方法については、トレースをクエリして分析するをご覧ください。

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

始める前に

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

REST

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

REST

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

REST

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

REST

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

始める前に

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

REST

次のステップ

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

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

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