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

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

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

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

始める前に

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

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

他の Observability API エンドポイントにコマンドを発行して、 ID が 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 からトレースデータをクエリできます。また、データセットにアタッチされている Link オブジェクトを削除することもできます。

始める前に

データセットにリンクを作成するために必要な権限を取得するには、プロジェクトに対する次の 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 リファレンスドキュメントをご覧ください。

次のステップ

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

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

始める前に

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

REST

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

REST

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

REST

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

REST

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

始める前に

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

REST

次のステップ

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

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

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