v1.traces の概要

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

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

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

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

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

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

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

Google Cloud Observability は、トレースデータを保存する前に、 Google Cloud プロジェクトで Cloud Trace API が有効になっていることを確認します。つまり、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 エクスポータを含む OpenTelemetry ライブラリを使用して、テレメトリーを Telemetry API に送信できます。トレースデータを直接エクスポートする方法については、Cloud Trace エクスポータから OTLP エンドポイントへをご覧ください。

認証

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

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

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

  • 割り当てプロジェクトを構成します。詳細については、割り当てプロジェクトを設定するをご覧ください。

  • アプリケーションが使用するユーザーまたはサービス アカウントに、次の Identity and Access Management（IAM）ロールを付与します。

    • 割り当てプロジェクトに対するService Usage コンシューマーのロール（roles/serviceusage.serviceUsageConsumer）。
    • プロジェクトに対する Cloud Telemetry 書き込みロール（roles/telemetry.writer）。このロールにより、アプリケーションはログ、指標、トレースデータを書き込むことができます。

Cloud Trace とデータ所在地

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

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

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

割り当て

Telemetry API に関連する割り当てについては、Telemetry API の上限をご覧ください。