このページは Cloud Translation API によって翻訳されました。

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

このドキュメントでは、OpenTelemetry で計測され、 Google Cloud エクスポータに依存しているアプリケーションを、OpenTelemetry の OTLP エクスポータを使用するように移行する方法について説明します。どちらの構成でも、テレメトリーが Google Cloud プロジェクトに送信されます。このドキュメントの手順は、OpenTelemetry SDK によって実行されるプロセス内エクスポートを対象としています。

このドキュメントでは、手動計測を使用する場合にトレースデータをエクスポートする方法について説明します。このガイダンスは Java、Go、Python 向けに提供されていますが、ログデータや指標データを Google Cloud プロジェクトに送信する場合は対象としていません。

移行が必要な理由

OpenTelemetry SDK は、OTLP 形式でログ、指標、トレースデータを生成します。アプリケーションが Google Cloud エクスポータを使用してそのデータをGoogle Cloud プロジェクトにエクスポートすると、エクスポータは次の手順を実行します。

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

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

始める前に

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

課金と Telemetry API を有効にする

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

権限を構成する

サンプルアプリケーションがログ、指標、トレースデータをプロジェクトに送信するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
- Cloud テレメトリートレース書き込み（roles/telemetry.tracesWriter）
- ログ書き込み（roles/logging.logWriter）
- モニタリング指標の書き込み（roles/monitoring.metricWriter）
注: アプリケーションの構成で、アプリケーションのデフォルト認証情報（ADC）がサービスアカウントに依存するように設定されている場合は、上記の IAM ロールをサービスアカウントに付与します。詳細については、アプリケーションのデフォルト認証情報の仕組みとローカル開発環境用のアプリケーションのデフォルト認証情報（ADC）を設定するをご覧ください。

ログ、指標、トレースデータを表示するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
- ログ閲覧者（roles/logging.viewer）
- モニタリング閲覧者（roles/monitoring.viewer）
- Cloud トレースユーザー（roles/cloudtrace.user）
ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

手動計測の移行ガイド

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

依存関係を追加する

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

Java

Gradle ビルドシステムを使用する Java アプリケーションの場合:

// build.gradle
implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.47.0")

Go

Golang アプリケーションの場合は、go.mod ファイルに次の依存関係があることを確認します。

// go.mod file
require(
  // OTLP exporter that uses grpc protocol for export
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.34.0
  // Alternatively, for export using http/protobuf protocol, use:
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.34.0
)

Python

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

# Requirements.txt - use appropriate versions
#
# OTLP exporter that uses grcp protocol for export
opentelemetry-exporter-otlp-proto-grpc==1.30.0
grpcio==1.70.0
# Alternatively, for export using http/protobuf protocol, use:
opentelemetry-exporter-otlp-proto-http==1.30.0

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

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

Java

import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.export.SpanExporter;
import io.opentelemetry.sdk.trace.samplers.Sampler;

// Initialize OpenTelemetry SDK with OTLP exporters
public static OpenTelemetry initOpenTelemetry() {
    // Initialize the OTLP gRPC exporter
    SpanExporter otlpGrpcSpanExporter =
        OtlpGrpcSpanExporter.builder()
            .setTimeout(2, TimeUnit.SECONDS)
            .build();

    // Initialize OpenTelemetry tracer provider
    SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
        .setResource(resource)
        .setSampler(Sampler.traceIdRatioBased(0.02))
        .addSpanProcessor(
            BatchSpanProcessor.builder(otlpGrpcSpanExporter)
                .setScheduleDelay(100, TimeUnit.MILLISECONDS)
                .build());

    // Configure OpenTelemetry SDK instacne to use the tracer provider
    // configured with OTLP exporter
    OpenTelemetrySdk openTelemetrySdk =
        OpenTelemetrySdk.builder()
            .setTracerProvider(tracerProvider)
            .build();
}

Go

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

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

    // Initialize the OTLP gRPC exporter
    exporter, err := otlptracegrpc.New(ctx)
    if err != nil {
        panic(err)
    }
    // initialize OpenTelemetry tracer provdier
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.02)),
        sdktrace.WithBatcher(exporter)
    )

    // configure OpenTelemetry SDK instance to use the tracer provider
    // configured with OTLP exporter
    otel.SetTracerProvider(tp)
}

Python

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# Initialize OpenTelemetry with OTLP exporters
def init():
    # Initialize the OTLP gRPC or http exporter
    otlp_grpc_exporter = OTLPSpanExporter()

    # Initialize OpenTelemetry TracerProvider
    trace_provider = TracerProvider(resource=resource).add_span_processor(
    BatchSpanProcessor(otlp_grpc_exporter)
    )

    # Configure OpenTelemetry tracing API with the initialized tracer provider
    trace.set_tracer_provider(trace_provider)

認証を構成する

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

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

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

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

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

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

Java

Trace への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

// build.gradle
// Google Auth Library
implementation("com.google.auth:google-auth-library-oauth2-http:1.32.1")

Go

// go.mod file
require (
    // When using gRPC based OTLP exporter, auth is built-in
    google.golang.org/grpc v1.70.0
    // When using http based OTLP exported, use explicit auth library
    golang.org/x/oauth2 v0.26.0
)

Python

# requirements.txt
# Google Auth Library
google-auth==2.38.0

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

Java

OpenTelemetry SDK Autoconfigure モジュールを使用する場合は、Google Cloud 認証拡張機能を使用することをおすすめします。この拡張機能を使用する詳細な例については、Google Auth を使用した OTLP トレースの例をご覧ください。

import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.export.SpanExporter;
import io.opentelemetry.sdk.trace.samplers.Sampler;

import com.google.auth.oauth2.GoogleCredentials;

// Initialize OpenTelemetry SDK with OTLP exporters
public static OpenTelemetry initOpenTelemetry() {
    // Retrieve and store application-default credentials
    GoogleCredentials credentials;
    try {
       credentials = GoogleCredentials.getApplicationDefault();
    } catch (IOException e) {
      // Handle authentication error
      throw new RuntimeException(e);
    }

    // Update gRPC span exporter to add the authorization headers
    // If you are using the Autoconfigure module, we recommend using
    // Google Cloud Authentication Extension.
    // See https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-auth-extension
    SpanExporter otlpGrpcSpanExporter =
        OtlpGrpcSpanExporter.builder()
            .setHeaders(
                () -> {
                  Map<String, List<String>> gcpHeaders;
                  try {
                    credentials.refreshIfExpired();
                    gcpHeaders = credentials.getRequestMetadata();
                  } catch (IOException e) {
                    // Handle authentication error
                    throw new RuntimeException(e);
                  }
                  Map<String, String> flattenedHeaders =
                      gcpHeaders.entrySet().stream()
                          .collect(
                              Collectors.toMap(
                                  Map.Entry::getKey,
                                  entry ->
                                      entry.getValue().stream()
                                          .filter(Objects::nonNull)
                                          .filter(s -> !s.isEmpty())
                                          .collect(Collectors.joining(",")),
                                  (v1, v2) -> v2));
                  return flattenedHeaders;
                })
            .setTimeout(2, TimeUnit.SECONDS)
            .build();

  // Other OpenTelemetry configuration remains unaffected
}

Go

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

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

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

    // Retrieve and store Google application-default credentials
    creds, err := oauth.NewApplicationDefault(ctx)
    if err != nil {
        panic(err)
    }

    // Update the previously created OTLP gRPC span exporter to
    // add authorization headers
    exporter, err := otlptracegrpc.New(
        ctx,
        otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds))
    )

    // Other OpenTelemetry configuration remains unaffected.
}

Python

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

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

# Initialize OpenTelemetry with OTLP exporters
def init():
    # Retrieve and store Google application-default credentials
    credentials, project_id = google.auth.default()
    # Request used to refresh credentials upon expiry
    request = google.auth.transport.requests.Request()

    # Supply the request and credentials to AuthMetadataPlugin
    # AuthMeatadataPlugin inserts credentials into each request
    auth_metadata_plugin = AuthMetadataPlugin(
        credentials=credentials, request=request
    )

    # Initialize gRPC channel credentials using the AuthMetadataPlugin
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Update the previously created OTLP gRPC span exporter to add authorization
    # credentials
    otlp_grpc_exporter = OTLPSpanExporter(credentials=channel_creds)

    # Other OpenTelementry configuration remains unaffected

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

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

例:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_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

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

Trace エクスポータから OTLP エンドポイントに移行する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

移行が必要な理由

始める前に

課金と Telemetry API を有効にする

権限を構成する

手動計測の移行ガイド

依存関係を追加する

Java

Go

Python

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

Java

Go

Python

認証を構成する

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

Java

Go

Python

Java

Go

Python

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

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

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

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

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