Go クライアントライブラリでテレメトリーシグナルを有効にする

Google Cloud は、Go アプリケーションに強力なモニタリング、ロギング、診断機能を提供します。

Go クライアントライブラリは、トレース、指標、ロギングのデータを出力するように計測されています。インストルメンテーションはオプトインです。明示的に有効にする必要があります。このドキュメントでは、利用可能なシグナルとその有効化方法について説明します。

利用可能なシグナル

シグナルには、OpenTelemetry セマンティック規則に準拠した次のテレメトリーデータが含まれます。

トレース: クライアントライブラリによって行われたネットワークリクエストを表す低レベルの HTTP/gRPC トレース。
指標: レイテンシとリクエスト率を追跡するクライアントリクエスト指標。プライマリ指標は gcp.client.request.duration です。
ログ: DEBUG レベル（以上）で実行可能なエラーログ。最終的に再試行が成功した場合でも、トランスポートレイヤで失敗したリクエストの詳細を提供します。

シグナルには、標準の OpenTelemetry 属性（http.response.status_code や rpc.system.name など）と Google Cloud固有のカスタム属性が含まれます。カスタム属性には、次のような属性が含まれる場合があります。

gcp.client.service: サービス名（pubsub、storage など）。
gcp.client.repo: クライアントライブラリリポジトリ（例: googleapis/google-cloud-go）。
gcp.client.version: クライアントライブラリのバージョン。
gcp.client.artifact: 特定のモジュールパス（例: cloud.google.com/go/secretmanager）。
gcp.resource.destination.id: 処理対象のリソースの ID。
gcp.errors.domain: アクション可能なエラーログのエラードメイン。
gcp.errors.metadata.<key>: 失敗したリクエストの追加のエラーメタデータキー（フラット化）。

標準の属性の一覧については、OpenTelemetry HTTP と gRPC のセマンティック規約をご覧ください。

テレメトリーを有効にする

センシティブデータを保護するため、ゴールデンシグナルはデフォルトで無効になっています。有効にするには、明示的にオプトインする必要があります。

Go では、次の環境変数を使用して、 Google Cloud クライアントライブラリ全体でトレース、指標、ログをグローバルに有効にします。

# Enable trace generation (span emission)
export GOOGLE_SDK_GO_TRACING=true

# Enable metrics
export GOOGLE_SDK_GO_METRICS=true

# Enable logging
export GOOGLE_SDK_GO_LOGGING=true

トレースコンテキストの伝播

Go クライアントライブラリは、トレース生成（GOOGLE_SDK_GO_TRACING）が無効になっている場合でも、アクティブなトレースコンテキストをGoogle Cloud サービスに自動的に伝播します。

アプリケーションに、クライアントライブラリメソッドに渡された context.Context にアクティブな OpenTelemetry スパンがある場合、ライブラリはそれを使用して、送信リクエストのトレースコンテキストを提供します。これにより、クライアントサイドのスパンを発行しなくても、アプリケーションレベルのトレースをバックエンドサービスログや動作と関連付けることができます。

アプリケーションでグローバル OpenTelemetry テキストマッププロパゲータを設定して、クライアントライブラリのトレースコンテキストを提供します。

テレメトリーのエクスポート

クライアントライブラリでテレメトリーを有効にしたら、このデータを収集してオブザーバビリティバックエンドにエクスポートするようにアプリケーションを構成する必要があります。

トレースと指標

Go クライアントライブラリで生成されたトレースと指標をエクスポートするには、目的のエクスポータ（OTLP など）で OpenTelemetry SDK を初期化し、main.go でグローバルテキストマッププロパゲータを設定します。

package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "go.opentelemetry.io/otel/propagation"
    "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
    ctx := context.Background()

    // Initialize the exporter
    exporter, err := otlptracegrpc.New(ctx)
    if err != nil {
        log.Fatalf("failed to initialize exporter: %v", err)
    }

    // Set up the tracer provider
    tp := trace.NewTracerProvider(trace.WithBatcher(exporter))
    defer func() {
        // Ensure all spans are flushed before exit
        if err := tp.Shutdown(ctx); err != nil {
            log.Fatalf("failed to shutdown TracerProvider: %v", err)
        }
    }()

    otel.SetTracerProvider(tp)

    // Set up the global propagator
    otel.SetTextMapPropagator(propagation.TraceContext{})

    // ... initialize Google Cloud client libraries ...
}

OpenTelemetry SDK を Cloud Monitoring または Cloud Trace に接続する方法の詳細については、Go 向け Google Cloud Observability ガイドをご覧ください。

ロギング

Go クライアントライブラリは、slog を使用して構造化ロギングを行い、DEBUG レベルで対応可能なエラーを出力します。ロギングフレームワークが context.Context からトレース ID とスパン ID を抽出するように構成されている場合、エクスポートされたログにはトレース ID とスパン ID が自動的に含まれます。

これらのログを受信するには、初期化時に（たとえば option.WithLogger() を使用して）構成済みの *slog.Logger をクライアントに提供する必要があります。

これらの構造化ログを Cloud Logging に転送するには、JSON を標準出力（stdout）に書き込むように slog を構成します。Google Kubernetes Engine や Cloud Run などの環境にデプロイする場合は、組み込みのエージェントがこれらのログを自動的にスクレイピングします。

package main

import (
    "context"
    "log/slog"
    "os"

    "cloud.google.com/go/secretmanager/apiv1"
    "google.golang.org/api/option"
)

func main() {
    ctx := context.Background()

    // Configure slog to output JSON to stdout at the DEBUG level
    opts := &slog.HandlerOptions{Level: slog.LevelDebug}
    logger := slog.New(slog.NewJSONHandler(os.Stdout, opts))

    // Provide the logger to the client
    client, err := secretmanager.NewClient(ctx, option.WithLogger(logger))
    if err != nil {
        // handle error
    }
    defer client.Close()
}

OpenTelemetry トレースコンテキストをマッピングし、Cloud Logging の想定されるペイロードフィールドに合わせて構造化 JSON ログの形式を設定する手順については、Go 用の構造化ロギングを構成するをご覧ください。

Go クライアント ライブラリでテレメトリー シグナルを有効にする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。