Go と OpenTelemetry

このページは、OpenTelemetry を使用して Go アプリケーション用の Cloud Trace データを収集するアプリケーション開発者を対象としています。OpenTelemetry は、トレースデータと指標データを収集するための一連のインストルメンテーション ライブラリです。これらのライブラリは複数のバックエンドで動作します。このページで説明するように、OpenTelemetry と Go を使用してトレースを収集するには、次のことを実施します。

  • OpenTelemetry パッケージをインストールする。
  • Cloud Trace にスパンをエクスポートするようにアプリケーションを構成する。
  • プラットフォームを構成する。

リリース情報については、以下をご覧ください。

OpenTelemetry のリファレンス コンテンツについては、以下をご覧ください。

追加のドキュメントとサンプルを含め、Go の OpenTelemetry に関する最新情報については、OpenTelemetry をご覧ください。

始める前に

Google Cloud プロジェクトで Cloud Trace API が有効になっていることを確認します。

  1. 次のボタンをクリックするか、Google Cloud Console で [API とサービス]、[Cloud Trace API] の順に選択します。

    Trace API に移動

  2. [Cloud Trace API] ページで、[有効にする] というボタンが表示されている場合は、それをクリックします。このボタンが表示されない場合、Cloud Trace API は、選択したプロジェクトで有効になっています。

クライアントのインストール、初期化、使用

Compute Engine と Google Kubernetes Engine で Go アプリケーションを計測するには、次の手順をご覧ください。OpenTelemetry を使用する一般的な例については、Go 用の OpenTelemetry GitHub リポジトリをご覧ください。

Compute Engine

OpenTelemetry パッケージをインストールします。

go get go.opentelemetry.io/otel
go get github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace

OpenTelemetry と Cloud Trace のエクスポート パッケージをインポートします。

import (
	"context"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/contrib/detectors/gcp"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.7.0"
)

エクスポータとトレース プロバイダを作成します。

func main() {
	// Create exporter.
	ctx := context.Background()
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.New(texporter.WithProjectID(projectID))
	if err != nil {
		log.Fatalf("texporter.New: %v", err)
	}

	// Identify your application using resource detection
	res, err := resource.New(ctx,
		// Use the GCP resource detector to detect information about the GCP platform
		resource.WithDetectors(gcp.NewDetector()),
		// Keep the default detectors
		resource.WithTelemetrySDK(),
		// Add your own custom attributes to identify your application
		resource.WithAttributes(
			semconv.ServiceNameKey.String("my-application"),
		),
	)
	if err != nil {
		log.Fatalf("resource.New: %v", err)
	}

	// Create trace provider with the exporter.
	//
	// By default it uses AlwaysSample() which samples all traces.
	// In a production environment or high QPS setup please use
	// probabilistic sampling.
	// Example:
	//   tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.0001)), ...)
	tp := sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(exporter),
		sdktrace.WithResource(res),
	)
	defer tp.ForceFlush(ctx) // flushes any pending spans
	otel.SetTracerProvider(tp)

	// Create custom span.
	tracer := otel.GetTracerProvider().Tracer("example.com/trace")
	err = func(ctx context.Context) error {
		ctx, span := tracer.Start(ctx, "foo")
		defer span.End()

		// Do some work.

		return nil
	}(ctx)
}

エクスポータを作成するときは、Google Cloud プロジェクト ID に関する情報を指定します。この例では、ID が環境変数 GOOGLE_CLOUD_PROJECT に格納されます。

サンプル アプリケーションは、WithBatcher 関数を呼び出して、トレース プロバイダがバックグラウンド プロセスを使用して Cloud Monitoring にスパンを送信するように構成します。このサンプルは、アプリの終了時にエクスポータの Shutdown 関数を呼び出すように構成されています。Shutdown が実行されると、保留中のすべてのスパンが Cloud Monitoring に送信されます。サンプルに示されている構成は、コンテナをいつでもシャットダウンできる Cloud Run を含め、すべての運用環境で推奨される実施例です。

Tracer インスタンスを作成するときは、名前を指定します。この例では、名前は example.com/trace です。この方法では、複数のインスタンスを持つことができるので、これらのインスタンスにはトレースするコンポーネントの名前を付けることをお勧めします。

このサンプルが実行されると、foo という名前の単一のトレースが作成されます。

GKE

Dockerfile に次の行を追加します。

RUN go get go.opentelemetry.io/otel
RUN go get github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace

OpenTelemetry と Cloud Trace のエクスポート パッケージをインポートします。

import (
	"context"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/contrib/detectors/gcp"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.7.0"
)

エクスポータとトレース プロバイダを作成します。

func main() {
	// Create exporter.
	ctx := context.Background()
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.New(texporter.WithProjectID(projectID))
	if err != nil {
		log.Fatalf("texporter.New: %v", err)
	}

	// Identify your application using resource detection
	res, err := resource.New(ctx,
		// Use the GCP resource detector to detect information about the GCP platform
		resource.WithDetectors(gcp.NewDetector()),
		// Keep the default detectors
		resource.WithTelemetrySDK(),
		// Add your own custom attributes to identify your application
		resource.WithAttributes(
			semconv.ServiceNameKey.String("my-application"),
		),
	)
	if err != nil {
		log.Fatalf("resource.New: %v", err)
	}

	// Create trace provider with the exporter.
	//
	// By default it uses AlwaysSample() which samples all traces.
	// In a production environment or high QPS setup please use
	// probabilistic sampling.
	// Example:
	//   tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.0001)), ...)
	tp := sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(exporter),
		sdktrace.WithResource(res),
	)
	defer tp.ForceFlush(ctx) // flushes any pending spans
	otel.SetTracerProvider(tp)

	// Create custom span.
	tracer := otel.GetTracerProvider().Tracer("example.com/trace")
	err = func(ctx context.Context) error {
		ctx, span := tracer.Start(ctx, "foo")
		defer span.End()

		// Do some work.

		return nil
	}(ctx)
}

エクスポータを作成するときは、Google Cloud プロジェクト ID に関する情報を指定します。この例では、ID が環境変数 GOOGLE_CLOUD_PROJECT に格納されます。

サンプル アプリケーションは、WithBatcher 関数を呼び出して、トレース プロバイダがバックグラウンド プロセスを使用して Cloud Monitoring にスパンを送信するように構成します。このサンプルは、アプリの終了時にエクスポータの Shutdown 関数を呼び出すように構成されています。Shutdown が実行されると、保留中のすべてのスパンが Cloud Monitoring に送信されます。サンプルに示されている構成は、コンテナをいつでもシャットダウンできる Cloud Run を含め、すべての運用環境で推奨される実施例です。

Tracer インスタンスを作成するときは、名前を指定します。この例では、名前は example.com/trace です。この方法では、複数のインスタンスを持つことができるので、これらのインスタンスにはトレースするコンポーネントの名前を付けることをお勧めします。

このサンプルが実行されると、foo という名前の単一のトレースが作成されます。

カスタムスパンの作成方法

カスタムスパンを作成することで、システムが作成したトレースに別の情報を追加できます。

foo という名前のカスタムスパンを作成するには、次のコードをソースコードに追加します。

// Create custom span.
tracer := otel.GetTracerProvider().Tracer("example.com/trace")
err = func(ctx context.Context) error {
	ctx, span := tracer.Start(ctx, "foo")
	defer span.End()

	// Do some work.

	return nil
}(ctx)

ここで、example.com/trace はトレーサー インスタンスの名前です。

プラットフォームの構成

Cloud Trace は Google Cloud と他のプラットフォームで使用できます。

Google Cloud での実行

アプリケーションが Google Cloud で実行されている場合、認証情報をサービス アカウントの形式でクライアント ライブラリに提供する必要はありません。ただし、Google Cloud Platform で Cloud Trace API のアクセス スコープが有効になっている必要があります。

サポートされている Google Cloud 環境の一覧については、環境サポートをご覧ください。

次の構成では、デフォルトのアクセス スコープ設定により Cloud Trace API が有効化されます。

カスタム アクセス スコープを使用する場合は、Cloud Trace API のアクセス スコープを有効にする必要があります。

  • Google Cloud Console を使用して環境のアクセス スコープを構成する方法については、Google Cloud プロジェクトの構成をご覧ください。

  • gcloud ユーザーの場合は、--scopes フラグを使用してアクセス スコープを指定し、trace.append Cloud Trace API アクセス スコープを含めます。たとえば、Cloud Trace API のみを有効にして GKE クラスタを作成するには、次のようにします。

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

ローカルやその他の場所での実行

アプリケーションが Google Cloud の外部で実行されている場合は、認証情報をサービス アカウントの形式でクライアント ライブラリに提供する必要があります。サービス アカウントには Cloud Trace エージェント ロールが含まれている必要があります。手順については、サービス アカウントの作成をご覧ください。

Google Cloud クライアント ライブラリは、アプリケーションのデフォルト認証情報（ADC）を使用してアプリケーションの認証情報を検索します。

これらの認証情報を指定するには、次の 3 つの方法があります。

  • 実行 gcloud auth application-default login

  • オペレーティング システムのデフォルトパスにサービス アカウントを配置します。以下に、Windows と Linux のデフォルトのパスを一覧表示します。

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • GOOGLE_APPLICATION_CREDENTIALS 環境変数をサービス アカウントへのパスに設定します。

Linux / macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

トレースの表示

デプロイ後は、Google Cloud コンソール Trace Viewer でトレースを表示できます。

Trace Viewer のページに移動

トラブルシューティング

Cloud Trace に関する問題のトラブルシューティングについては、トラブルシューティング ページをご覧ください。