Trace エクスポータから OTLP エンドポイントに移行する

手動で計測された Java、Go、Python、Node.js アプリケーションを、 Google Cloud トレース エクスポータからインプロセス OpenTelemetry OTLP エクスポータに移行できます。OTLP エクスポータは、サポートされているエクスポート プロトコル（gRPC または http/protobuf）を使用して、トレースデータを Google Cloud プロジェクトの Telemetry（OTLP）API に直接送信します。

この構成では、トレースデータのみがエクスポートされ、インプロセス エクスポータにのみ適用されます。アプリケーションで OpenTelemetry コレクタを使用している場合は、コレクタベースの計測サンプルのと Google が構築した OpenTelemetry コレクタをご覧ください。

移行が必要な理由

OpenTelemetry SDK は、OpenTelemetry プロトコルで定義された proto ファイルと概ね一致する形式で、ログ、指標、トレースデータを生成します。ただし、フィールドは保存前に OpenTelemetry 固有のデータ型から JSON データ型に変換されることがあります。

アプリケーションが Google Cloud エクスポータを使用してそのデータを Google Cloud プロジェクトにエクスポートすると、エクスポータは次の手順を実行します。

  1. 記録されたデータを OTLP 形式から、Cloud Logging API、Cloud Monitoring API、または Cloud Trace API で定義された独自の形式に変換します。
  2. 変換されたデータを適切な API に送信し、 Google Cloud プロジェクトに保存します。

トレースデータの場合は、データ変換を必要としない Telemetry（OTLP）API を使用してデータをエクスポートするようにアプリケーションを移行することをおすすめします。データ変換により、一部のデータが失われる可能性があります。たとえば、独自形式では特定のフィールドの制限が低い場合や、一部の OTLP フィールドが独自形式のフィールドにマッピングされない場合があります。

利用可能なサンプル

このページで参照されているサンプル アプリケーションは GitHub で入手できます。ほとんどのアプリケーションは、gRPC を使用してトレースデータをエクスポートするように構成されています。つまり、HTTP/2 接続を介して gRPC ワイヤ形式で protobuf でエンコードされたデータを送信します。HTTP 接続を介して protobuf でエンコードされたデータとしてトレースデータをエクスポートするように構成されたアプリケーションのサンプルコードも用意されています。

  • Java アプリケーション

    サンプル アプリケーションは、HTTP 接続を介して protobuf でエンコードされたデータとしてトレースをエクスポートするように構成されています。gRPC を使用する場合は、このサンプルの計測が適用されます。ただし、自動構成モジュールが使用するシステム プロパティを変更する必要があります。サンプル アプリケーションでは、http/protobuf エクスポータを指定します。gRPC を使用するには、この設定を grpc に変更します。

    サンプル アプリケーションと同様に、Java アプリケーションでは OpenTelemetry SDK Autoconfigure モジュールを使用して SDK を構成することをおすすめします。

  • gRPC を使用する Go アプリケーションと HTTP を使用する Go アプリケーション

    Go リポジトリは 2 つあります。1 つのリポジトリでは、サンプル アプリケーションが gRPC を使用します。もう一方のリポジトリのサンプルでは、HTTP 接続を介して protobuf でエンコードされたデータを使用しています。

  • Python リポジトリ

    このリポジトリには、gRPC 用と、HTTP 接続を介して protobuf でエンコードされたデータを使用する用の 2 つのサンプルが含まれています。

  • Node.js アプリケーション

    このリポジトリには、gRPC 用と、HTTP 接続を介して protobuf でエンコードされたデータを使用する用の 2 つのサンプルが含まれています。

始める前に

トレースデータを OTLP エンドポイントに送信するようにアプリケーションを移行する前に、Telemetry API を有効にして、必要な Identity and Access Management（IAM）ロールが付与されていることを確認します。サービス アカウントに IAM ロールを付与する必要がある場合もあります。

課金と Telemetry API を有効にする

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

権限を構成する

手動計測の移行ガイド

このセクションでは、Telemetry API を使用して、トレースデータを Google Cloud プロジェクトに送信するようにアプリケーションを変更する方法について説明します。

依存関係を追加する

最初のステップは、アプリケーションに OpenTelemetry の OTLP トレース エクスポータの依存関係を追加することです。アプリケーションとビルドシステムに適した依存関係のバージョンを選択します。

Java

Java アプリケーションの場合は、build.gradle スクリプトに次の依存関係を追加します。

implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.62.0")
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.62.0")

Go

このセクションでは、エクスポートに gRPC を使用する場合に依存関係に加える必要がある変更について説明します。HTTP 接続を介して protobuf でエンコードされたデータをエクスポートする場合は、otlptracehttp パッケージを依存関係として含めます。詳細については、HTTP を使用する Go アプリケーションをご覧ください。

エクスポートに gRPC を使用する Go アプリケーションの場合は、go.mod ファイルを更新して次の依存関係を追加します。

require (
	// ...
	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.44.0
)

Python

このセクションでは、エクスポートに gRPC を使用する場合に依存関係に加える必要がある変更について説明します。エクスポートに HTTP 接続を介して protobuf でエンコードされたデータを使用する場合は、要件として opentelemetry-exporter-otlp-proto-http パッケージを含めます。詳細については、Python リポジトリをご覧ください。

エクスポートに gRPC を使用する Python アプリケーションの場合は、次の依存関係をインストールするか、requirements.txt ファイルを更新します。

opentelemetry-exporter-otlp-proto-grpc==1.42.1
grpcio==1.80.0

Node.js

このセクションでは、エクスポートに gRPC を使用する場合に依存関係に加える必要がある変更について説明します。HTTP 接続を介して protobuf でエンコードされたデータをエクスポートする場合は、@opentelemetry/exporter-trace-otlp-proto パッケージを依存関係として含めます。詳細については、Node.js アプリケーションをご覧ください。

gRPC を使用してトレースデータをエクスポートする Node.js アプリケーションの場合は、次の依存関係を追加します。

"@opentelemetry/exporter-trace-otlp-grpc": "0.221.0",
"@grpc/grpc-js": "1.14.4"

Google Cloud エクスポータの使用を OTLP エクスポータに置き換える

アプリケーション コードを更新して、 Google Cloud トレース エクスポータではなく OpenTelemetry OTLP エクスポータを使用するように OpenTelemetry SDK を構成します。必要な変更は言語によって異なります。

Java

Java アプリケーションの場合は、次の操作を行います。

  1. 次の import ステートメントを追加します。

    import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

  2. OpenTelemetry SDK Autoconfigure モジュールを使用して SDK を構成するようにアプリケーション コードを更新します。

    public static void main(String[] args) {
  // Configure the OpenTelemetry pipeline with Auto configuration
  openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();

  // ...
}

  3. autoconfig モジュールが実行時に使用するシステム プロパティを構成します。このモジュールは、これらのプロパティを使用して SDK をブートストラップします。システム プロパティの代わりに環境変数を使用することもできます。詳細については、環境変数とシステム プロパティをご覧ください。

    サンプル アプリケーションでは、build.gradle スクリプトでシステム プロパティを定義します。

    // You can switch the desired protocol here by changing `otel.exporter.otlp.protocol`.
def autoconf_config = [
	'-Dotel.exporter.otlp.endpoint=https://telemetry.googleapis.com',
	'-Dotel.traces.exporter=otlp',
	'-Dotel.logs.exporter=none',
	'-Dotel.metrics.exporter=none',
	'-Dotel.service.name=otlptrace-example',
	'-Dotel.exporter.otlp.protocol=http/protobuf',
	'-Dotel.java.global-autoconfigure.enabled=true',
]

    また、構成を JVM 引数として渡します。

    application {
	mainClassName = 'com.google.cloud.opentelemetry.samples.otlptrace.OTLPTraceExample'
	// Pass the config as JVM arguments to the Java application
	applicationDefaultJvmArgs = autoconf_config
}

    gRPC を使用してトレースデータをエクスポートする場合は、OTLP プロトコルを http/protobuf ではなく grpc に設定します。

Go

このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。エクスポートに HTTP 接続を介して protobuf でエンコードされたデータを使用する場合は、otlptracehttp パッケージをインポートし、対応するオプションでエクスポータを構成する必要があります。詳細については、HTTP を使用する Go アプリケーションをご覧ください。

エクスポートに gRPC を使用する Go アプリケーションの場合は、次の import ステートメントを追加します。

import (
	"context"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"

	// ...
)

また、初期化コードを更新して、gRPC エクスポータで TraceProvider を構成します。

// Initializes OpenTelemetry with OTLP exporters
ctx := context.Background()

// Configure gRPC client with Google Application Default Credentials
creds, err := oauth.NewApplicationDefault(ctx)
if err != nil {
	panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
// Configure exporter to use the credentials
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
	panic(err)
}

tp := sdktrace.NewTracerProvider(
	// For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
	// In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
	sdktrace.WithSampler(sdktrace.AlwaysSample()),
	sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

Python

このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。HTTP 接続を介して protobuf でエンコードされたデータをエクスポートに使用する場合は、opentelemetry.exporter.otlp.proto.http パッケージからインポートし、対応するオプションでエクスポータを構成する必要があります。詳細については、Python リポジトリをご覧ください。

エクスポートに gRPC を使用する Python アプリケーションの場合は、次のインポートを追加します。

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)

また、初期化コードを更新して、gRPC エクスポータで TraceProvider を構成します。

# Initialize OpenTelemetry with OTLP exporters
# channel_creds: configure Application Default Credentials
trace_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(
    OTLPSpanExporter(
        credentials=channel_creds,
        endpoint="https://telemetry.googleapis.com:443/v1/traces",
    )
)
trace_provider.add_span_processor(processor)
trace.set_tracer_provider(trace_provider)
tracer = trace.get_tracer("my.tracer.name")

Node.js

このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。エクスポートに HTTP 接続を介して protobuf でエンコードされたデータを使用する場合は、@opentelemetry/exporter-trace-otlp-proto パッケージをインポートします。詳細については、Node.js アプリケーションをご覧ください。

エクスポートに gRPC を使用する Node.js アプリケーションの場合は、次のインポートを追加します。

import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-grpc';

また、初期化コードを更新して、gRPC エクスポータで TraceProvider を構成します。

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    credentials: credentials.combineChannelCredentials(
      credentials.createSsl(),
      credentials.createFromGoogleCredential({
        async getRequestHeaders(
          url?: string,
        ): Promise<{[index: string]: string}> {
          const rawHeaders = await authenticatedClient.getRequestHeaders(url);
          return Object.fromEntries(rawHeaders.entries());
        },
      }),
    ),
  }),
});
sdk.start();

認証を構成する

OpenTelemetry SDK 構成に対する前回の変更により、アプリケーションは gRPC または HTTP を使用して OpenTelemetry OTLP エクスポータでトレースをエクスポートするように構成されています。次に、これらのトレースを Google Cloud プロジェクトに送信するようにエクスポータを構成する必要があります。

認証を構成するには、次の操作を行います。

  1. エクスポート呼び出しの認証ヘッダーを構成する。
  2. 必要な OpenTelemetry リソース属性と OTLP ヘッダーを構成する。
  3. エクスポータ エンドポイントを構成する。

このセクションでは、これらの各ステップについて詳しく説明します。

エクスポート呼び出しの認証ヘッダーを構成する

Google Cloud アプリケーションのデフォルト認証情報（ADC）を使用してエクスポータを構成するために、言語固有の Google Auth ライブラリを追加します。

Java

OpenTelemetry SDK Autoconfigure モジュールを使用する Java アプリケーションの場合は、Google Cloud 認証拡張機能も使用することをおすすめします。

implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.56.0-alpha")

Go

エクスポートに gRPC を使用する Go アプリケーションの場合は、go.mod ファイルを更新して次の依存関係を追加します。

// When using gRPC based OTLP exporter, the auth is built in.
google.golang.org/grpc v1.82.1

エクスポートに HTTP を使用する Go アプリケーションの場合は、go.mod ファイルを更新して次の依存関係を追加します。

// When using http based OTLP exporter, use explicit auth library
golang.org/x/oauth2 v0.36.0

Python

Python アプリケーションの場合は、次の依存関係を requirements.txt ファイルに追加します。

# Google Auth Library
google-auth==2.53.0

Node.js

Node.js アプリケーションの場合は、次の依存関係を追加します。

"google-auth-library": "10.5.0"

次に、ライブラリから取得した認可トークンをヘッダーに追加するように OTLP スパン エクスポータを構築するアプリケーション コードを更新します。このステップは言語固有ですが、実装はすべての言語で類似しています。

Java

OpenTelemetry SDK Autoconfigure モジュールと Google Cloud 認証拡張機能を使用する Java アプリケーションがある場合、アプリケーションの初期化中に特別な手順を行う必要はありません。autoconfigure モジュールは、ADC の構成に必要な手順を自動的に実行します。

Go

このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。HTTP 接続を介して protobuf でエンコードされたデータをエクスポートする場合は、otlptracehttp パッケージをインポートし、エクスポータを otlptracehttp オブジェクトとして構成する必要があります。詳細については、HTTP を使用する Go アプリケーションをご覧ください。

エクスポートに gRPC を使用する Go アプリケーションの場合は、次の import ステートメントを追加します。

"google.golang.org/grpc"
"google.golang.org/grpc/credentials/oauth"

また、gRPC エクスポータをインスタンス化する前に、ADC を構成するように初期化コードを更新します。

// Initializes OpenTelemetry with OTLP exporters
ctx := context.Background()

// Configure gRPC client with Google Application Default Credentials
creds, err := oauth.NewApplicationDefault(ctx)
if err != nil {
	panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
// Configure exporter to use the credentials
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
	panic(err)
}

tp := sdktrace.NewTracerProvider(
	// For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
	// In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
	sdktrace.WithSampler(sdktrace.AlwaysSample()),
	sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

Python

このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。エクスポートに HTTP 接続を介して protobuf でエンコードされたデータを使用する場合は、デフォルトの認証情報を使用します。また、BatchSpanProcessor をインスタンス化するときに、これらの認証情報を渡す必要があります。詳細については、Python リポジトリをご覧ください。

エクスポートに gRPC を使用する Python アプリケーションの場合は、次のインポートを追加します。

import google.auth
import google.auth.transport.grpc
import google.auth.transport.requests
import grpc
from google.auth.transport.grpc import AuthMetadataPlugin

また、gRPC エクスポータをインスタンス化する前に、ADC を構成するように初期化コードを更新します。

credentials, _ = google.auth.default()
request = google.auth.transport.requests.Request()
resource = Resource.create(attributes={SERVICE_NAME: "otlp-gcp-grpc-sample"})

auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
channel_creds = grpc.composite_channel_credentials(
    grpc.ssl_channel_credentials(),
    grpc.metadata_call_credentials(auth_metadata_plugin),
)

Node.js

このセクションでは、エクスポートに gRPC を使用する場合に必要な変更について説明します。エクスポートに HTTP 接続を介して protobuf でエンコードされたデータを使用する場合、必要な変更はここで説明するものとは少し異なります。詳細については、Node.js アプリケーションに含まれている app-http-proto-export.ts ファイルをご覧ください。

エクスポートに gRPC を使用する Node.js アプリケーションの場合は、次のインポートを追加します。

import {AuthClient, GoogleAuth} from 'google-auth-library';
import {credentials} from '@grpc/grpc-js';

また、gRPC エクスポータをインスタンス化する前に、ADC を構成するように初期化コードを更新します。

async function getAuthenticatedClient(): Promise<AuthClient> {
  const auth: GoogleAuth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
  });
  return await auth.getClient();
}

// Express App that exports traces via gRPC with protobuf
async function main() {
  const authenticatedClient: AuthClient = await getAuthenticatedClient();

  // ...
}

必要な OpenTelemetry リソース属性を構成する

プロジェクトを指定する Key-Value ペアを OTEL_RESOURCE_ATTRIBUTES 環境変数に追加します。キーには gcp.project_id を使用します。値には、 Google Cloud プロジェクトの ID を使用します。

例:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

Java を使用し、サンプルの Java アプリケーションと同様に、Google Cloud Authentication Extension を使用するようにアプリケーションを構成する場合は、OpenTelemetry リソース属性の一部としてプロジェクト ID を設定する必要はありません。ただし、この属性を設定しても問題はありません。

OpenTelemetry 環境変数の詳細については、一般的な SDK 構成をご覧ください。

割り当てプロジェクト ID を設定する

割り当てプロジェクトは、API リクエストの使用状況を追跡する Google Cloud プロジェクトです。Telemetry API はクライアント ベースの API であるため、認証方法によって割り当てプロジェクトが自動的に識別されるかどうかが決まります。たとえば、認証にサービス アカウントを使用する場合は、割り当てプロジェクトを指定する必要はありません。ただし、認証にユーザー認証情報を使用する場合は、割り当てプロジェクトを指定する必要があります。

環境変数を使用して割り当てプロジェクトを設定できます。プログラミング言語に設定する環境変数を特定するには、環境変数を使用して割り当てプロジェクトを設定するをご覧ください。

たとえば、Go の場合は、次のように割り当てプロジェクトを設定できます。

export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

認証エラーを解決する方法については、ユーザー認証情報が機能しないをご覧ください。

エクスポータ エンドポイントを構成する

OTEL_EXPORTER_OTLP_ENDPOINT 環境変数の値を Google Cloudの OTLP エンドポイントに設定します。

例:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.googleapis.com

Java と autoconfigure モジュールを使用する場合は、サンプルの Java アプリケーションと同様に、システム プロパティを使用してエクスポータ エンドポイントを設定できます。この構成では、エクスポータの環境変数を設定する必要はありません。

OpenTelemetry 環境変数の詳細については、一般的な SDK 構成をご覧ください。