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

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

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

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

始める前に

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

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

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Google Cloud プロジェクトを作成または選択します。

プロジェクトの選択または作成に必要なロール

プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。ロールを付与する方法を確認する。

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 を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。ロールを付与する方法を確認する。

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 ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。ロールを付与する方法を確認する。

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

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

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 のバケットに関する詳細情報を取得できます。たとえば、そのバケットのデータセットと、各データセットのビューとリンクを一覧表示できます。モニタリング API エンドポイントの一覧については、モニタリング API リファレンスドキュメントをご覧ください。

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

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 のデータセットに関する情報を取得できます。たとえば、各データセットのビューとリンクを一覧表示できます。モニタリング API エンドポイントの一覧については、モニタリング 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_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",
    }
  ]
}

モニタリング API エンドポイントの一覧については、モニタリング API リファレンスドキュメントをご覧ください。

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

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

モニタリング API エンドポイントの一覧については、モニタリング 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_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 オブジェクトにステータスデータが含まれます。

モニタリング API エンドポイントの一覧については、モニタリング API リファレンスドキュメントをご覧ください。

次のステップ

テレメトリーのクエリについては、テレメトリーを表示して分析するをご覧ください。

オブザーバビリティ バケットを管理する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

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

REST

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

REST

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

REST

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

REST

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

始める前に

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

REST

次のステップ

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

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

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