v1.traces の概要

このドキュメントでは、OpenTelemetry Line Protocol を実装する Telemetry（OTLP）API を使用してトレースデータを Google Cloud プロジェクトに送信することをおすすめする理由について説明します。また、アプリケーションの計測方法と、トレースデータを表示できる場所についても説明します。OpenTelemetry SDK のいずれかを使用してアプリケーションを計測する場合や、OpenTelemetry コレクタを使用する場合は、 Telemetry API を使用できます。

Telemetry API をおすすめする理由は次のとおりです。

• この API は、オープンソースの OpenTelemetry エコシステムとの互換性を提供します。また、この API の 上限は、 独自の Google Cloud API である Cloud Trace API の上限よりも柔軟なことがよくあります。

• トレースデータは、 OpenTelemetry Line Protocolで定義された proto ファイルと概ね一致する形式で保存されます。一部のフィールドは、保存前に OpenTelemetry 固有のデータ型から JSON データ型に変換されることがあります。ストレージ形式の詳細については、 トレースデータのスキーマをご覧ください。

• 計測は Google Cloud固有のエクスポータに依存しません。

• アプリケーション モニタリングなどの一部の機能は、トレースデータを Telemetry API に送信した場合にのみ利用可能な情報に依存しています。

OpenTelemetry は、テレメトリーの取り込みと可視化をサポートする Google Cloud エンジニアが常駐する、 Google Cloud-がサポートするオープンソースプロジェクトです。

Google Cloud Observability は、トレースデータを保存する前に、プロジェクトで Cloud Trace API が有効になっていることを確認します。 Google Cloud つまり、Cloud Trace API を無効にすると、Google Cloud Observability は Telemetry API に送信されたトレースデータを破棄します。

ベスト プラクティス

トレースデータを Google Cloud プロジェクトに送信するようにアプリケーションを計測する場合は、OTLP 形式のデータをコレクタに書き込むエクスポータを使用して、トレースデータを Telemetry API に送信することをおすすめします。 コレクタでは、ルート URL のみ指定します。

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry はデータ型を検出し、必要に応じて /v1/traces、/v1/metrics、/v1/logs を自動的に追加します。詳細については、 OTLP/HTTP リクエストをご覧ください。

トレースデータまたは指標データを Telemetry API にエクスポートする例については、次のドキュメントをご覧ください。

• コレクタベースの計測サンプルの概要。
• OTLP 指標の取り込みの概要。

コレクタを使用できない場合は、プロセス内 OTLP エクスポータを含む OpenTelemetry ライブラリを使用して、テレメトリーを Telemetry API に送信できます。 トレースデータを直接エクスポートする方法については、 Cloud Trace エクスポータから OTLP エンドポイントをご覧ください。

認証

プロジェクトにデータを送信するために必要な認証情報を使用してエクスポータを構成する必要があります。 Google Cloud たとえば、コレクタを使用する場合は、通常、googleclientauth 拡張機能を使用して Google 認証情報で認証します。

トレースデータの直接エクスポートを使用する場合の認証の例については、 認証を構成するをご覧ください。 この例では、アプリケーションのデフォルト認証情報（ADC）を使用してエクスポータを構成し、言語固有の Google Auth ライブラリをアプリケーションに追加する方法を示します。 Google Cloud

Telemetry API を使用してテレメトリーデータを Google Cloud プロジェクトに送信するには、 次の操作も行う必要があります。

• 割り当てプロジェクトを構成します。詳細については、 割り当てプロジェクトを設定するをご覧ください。
• アプリケーションが使用するユーザーまたはサービス アカウントに、その割り当てプロジェクトの Service Usage コンシューマー ロール（roles/serviceusage.serviceUsageConsumer）を付与します。

• アプリケーションが使用するユーザーまたはサービス アカウントに、プロジェクトで次のロールを付与します。

  • ログ書き込み（roles/logging.logWriter）
  • モニタリング指標の書き込み（roles/monitoring.metricWriter）
  • Cloud テレメトリー トレース書き込み（roles/telemetry.tracesWriter）

Cloud Trace とデータ所在地

データ所在地または影響レベル 4（IL4）の要件があるためにAssured Workloadsを使用している場合は、Telemetry API を使用してトレーススパンをプロジェクトに送信しないでください。

取り込まれたデータを表示する場所

トレースデータは、[Trace エクスプローラ] ページと [オブザーバビリティ分析] ページで表示できます。詳細については、以下をご覧ください。

• トレースを検索して調査する。
• トレースのクエリと分析を行う。