Go での OpenTelemetry の使用

OpenTelemetric を使用することにより Go アプリケーション用に Cloud Trace を有効にできます。OpenTelemetry は、複数のバックエンドで機能するトレースと指標データを収集するための、一連の計測ライブラリです。Go の OpenTelemetry に関する最新情報、その他のドキュメントや例については、https://opentelemetry.io/ をご覧ください。

インストールと構成

トレースを収集するには、次のことを行う必要があります。

  • OpenTelemetric クライアント ライブラリのインストール。
  • OpenTeleometry トレース パッケージのインポート。
  • スパンを Cloud Trace にエクスポートするように OpenTelemetric を構成。
  • Cloud Trace API アクセス スコープの有効化。

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

Compute Engine と Google Kubernetes Engine で Go アプリケーションを計測する手順は次のとおりです。

Compute Engine

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

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

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

import (
	"context"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/otel/api/global"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

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

func main() {
	// Create exporter.
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.NewExporter(texporter.WithProjectID(projectID))
	if err != nil {
		log.Fatalf("texporter.NewExporter: %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
	// ProbabilitySampler set at the desired probability.
	// Example:
	//   config := sdktrace.Config{DefaultSampler:sdktrace.ProbabilitySampler(0.0001)}
	//   tp, err := sdktrace.NewProvider(sdktrace.WithConfig(config), ...)
	tp, err := sdktrace.NewProvider(sdktrace.WithSyncer(exporter))
	if err != nil {
		log.Fatal(err)
	}
	global.SetTraceProvider(tp)

	ctx := context.Background()
	// Create custom span.
	tracer := global.TraceProvider().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 はトレーサー インスタンスの名前、foo はスパンの名前です。複数のトレーサー インスタンスを持つ可能性があるため、トレーサー インスタンスには、トレース対象のコンポーネントの名前を付ける必要があります。

GKE

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

RUN go get -u go.opentelemetry.io/otel

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

import (
	"context"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/otel/api/global"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

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

func main() {
	// Create exporter.
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.NewExporter(texporter.WithProjectID(projectID))
	if err != nil {
		log.Fatalf("texporter.NewExporter: %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
	// ProbabilitySampler set at the desired probability.
	// Example:
	//   config := sdktrace.Config{DefaultSampler:sdktrace.ProbabilitySampler(0.0001)}
	//   tp, err := sdktrace.NewProvider(sdktrace.WithConfig(config), ...)
	tp, err := sdktrace.NewProvider(sdktrace.WithSyncer(exporter))
	if err != nil {
		log.Fatal(err)
	}
	global.SetTraceProvider(tp)

	ctx := context.Background()
	// Create custom span.
	tracer := global.TraceProvider().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 はトレーサー インスタンスの名前、foo はスパンの名前です。複数のトレーサー インスタンスを持つ場合に備えて、トレーサー インスタンスには、トレース対象のコンポーネントに基づいて名前が付けられます。

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

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

カスタムスパンを作成するには、ソースコードに次の内容を追加します。

ctx := context.Background()
// Create custom span.
tracer := global.TraceProvider().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 はトレーサー インスタンスの名前、foo はスパンの名前です。複数のトレーサー インスタンスを持つ場合に備えて、トレーサー インスタンスには、トレース対象のコンポーネントに基づいて名前が付けられます。

プラットフォームの構成

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

Google Cloud での実行

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

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

  • App Engine フレキシブル環境
  • App Engine スタンダード環境

  • Google Kubernetes Engine(GKE)

  • Compute Engine

カスタム アクセス スコープを使用する場合は、Cloud Trace API のアクセス スコープを有効にする必要があります。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)を使用してアプリケーションの認証情報を検索します。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"

パフォーマンスの最適化

トレースデータの通知によるパフォーマンスへの影響を軽減するには、バックグラウンド プロセスを使用してこのデータを送信します。トレースデータのバックグラウンド通知を構成するには、transport=AsyncTransport を含めて StackdriverExporter を初期化します。

トレースの表示

デプロイ後は、Cloud Console Trace Viewer でトレースを表示できます。

Trace Viewer のページに移動

トラブルシューティング

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