Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

利用可能なシグナル

Rust クライアントライブラリは、次のシグナルを生成するように計測されます。

論理クライアントリクエストごとの INFO スパン。通常、クライアント構造体の単一のメソッド呼び出しでこのようなスパンを取得します（たとえば、SecretManagerService クライアントで access_secret_version を呼び出すなど）。
各論理クライアントリクエストの経過時間を測定するヒストグラム指標。主な指標は gcp.client.request.duration です。
失敗した論理クライアントリクエストごとに WARN ログ。
低レベルの RPC 試行ごとの INFO スパン。通常、クライアント構造体の単一のメソッドがこのようなスパンを 1 つ取得しますが、ライブラリが RPC を再試行する必要がある場合は、複数のスパンを取得することがあります。
失敗した低レベルの試行ごとに DEBUG ログ。

これらのスパンとログは、追加のGoogle Cloud 属性を含む OpenTelemetry セマンティック規約に準拠しています。スパンとログの両方が、本番環境のモニタリングに適している必要があります。

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

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

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

ライブラリには、リクエストごとに DEBUG スパンもあります。これには、リクエストの本文全体、成功したリクエストのレスポンスの本文全体、失敗したリクエストのエラーメッセージ全体（詳細を含む）が含まれます。

リクエストやレスポンスにセンシティブデータが含まれている可能性があるため、本番環境で有効にする前に、これらのリクエストとレスポンスの内容を検討してください。

これらの DEBUG スパンは、クライアントライブラリクレートの後に ::tracing をターゲットとして使用し（例: google_cloud_secretmanager_v1::tracing）、メソッド名をスパン名として使用します（例: access_secret_version）。名前、ターゲット、またはその両方を使用してフィルタを設定できます。

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

センシティブデータを保護するため、テレメトリーシグナルはデフォルトで無効になっています。

Rust では、トレース、指標、ログを出力するようにクライアントを構成し、これらのシグナルを外部サービスに送信するようにサブスクライバーとエクスポータを構成する必要があります。

クライアントを構成するには、次の環境変数を設定します。

export GOOGLE_CLOUD_RUST_LOGGING=true

または、クライアントビルダーの .with_tracing() メソッドを使用してクライアントをビルドするときに、トレースをプログラムで明示的に有効にすることもできます。

use google_cloud_secretmanager_v1::client::SecretManagerService;

let client = SecretManagerService::builder()
    .with_tracing()
    .build()
    .await?;

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

Rust クライアントライブラリは、.with_tracing() を使用してトレース生成が明示的に有効になっていない場合でも、アクティブなトレースコンテキストをGoogle Cloud サービスに自動的に伝播します。

tracing-opentelemetry または opentelemetry クレートを使用して、クライアントライブラリのトレースコンテキストを提供します。

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

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

トレース

Google Cloud クライアントライブラリによって生成された tracing スパンを OpenTelemetry にエクスポートするには、OpenTelemetry エクスポータ（OTLP など）にデータをパイプする Subscriber をアプリケーションで構成する必要があります。

tracing-opentelemetry クレートと opentelemetry-otlp クレートを使用して、エクスポータを構成します。

use google_cloud_secretmanager_v1::client::SecretManagerService;
use opentelemetry::trace::TracerProvider as _;
use tracing_subscriber::Registry;
use tracing_subscriber::layer::SubscriberExt;

pub async fn sample() -> anyhow::Result<()> {
    let exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_tonic()
        .build()?;
    let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_batch_exporter(exporter)
        .build();
    let tracer = provider.tracer("example");

    // Create a tracing layer that sends data to an OpenTelemetry Collector running on localhost.
    let telemetry = tracing_opentelemetry::layer().with_tracer(tracer);

    // Register the subscriber globally
    let subscriber = Registry::default().with(telemetry);
    tracing::subscriber::set_global_default(subscriber)?;

    let _client = SecretManagerService::builder()
        .with_tracing()
        .build()
        .await?;

    Ok(())
}

指標

指標をエクスポートするには、クライアントを初期化する前に、アプリケーションにグローバル OpenTelemetry MeterProvider をインストールする必要があります。クライアントライブラリは、指標データの記録とエクスポートに自動的に使用します。

OpenTelemetry データを収集して Cloud Monitoring または Cloud Trace にエクスポートする方法の詳細については、インストルメンテーションアプローチを選択するをご覧ください。

ロギング

Rust クライアントライブラリは、tracing クレートを使用して、WARN レベルと DEBUG レベルで対応可能なエラーログを出力します。適切なフォーマッタを使用している場合、エクスポートされたログにはトレース ID とスパン ID が含まれ、トレースとのシームレスな関連付けが保証されます。

これらの構造化ログを Cloud Logging に転送するには、トレースサブスクライバーを構成して、イベントを JSON としてフォーマットし、標準出力（stdout）に出力します。Google Kubernetes Engine や Cloud Run などの環境にデプロイする場合は、組み込みのエージェントがこれらのログを自動的にスクレイピングします。

次の例では、WARN レベルのログのみをキャプチャして転送するようにサブスクライバーを構成しています。

use google_cloud_secretmanager_v1::client::SecretManagerService;
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

pub async fn sample() -> anyhow::Result<()> {
    // Enable all `WARN` logs to include failed client requests in all client libraries.
    let filter = tracing_subscriber::EnvFilter::new("warn");

    tracing_subscriber::registry()
        .with(filter)
        .with(tracing_subscriber::fmt::layer().json())
        .init();

    let _client = SecretManagerService::builder()
        .with_tracing()
        .build()
        .await?;

    Ok(())
}

JSON フォーマッタで OpenTelemetry トレース相関データ（logging.googleapis.com/trace など）を構成する手順については、コレクタベースの計測サンプルの概要をご覧ください。

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