Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

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

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

使用可能なシグナル

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

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

これらのスパンとログは、追加の Google Cloud 属性を持つOpenTelemetry Semantic Conventionsに準拠しています。スパンとログはどちらも、本番環境のモニタリングに適しています。

シグナルには、標準の 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 クライアントライブラリは、トレース生成が明示的に有効になっていない場合でも、アクティブなトレースコンテキストを Google Cloud サービスに自動的に伝播します .with_tracing()。

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

テレメトリーをエクスポートする

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

トレース

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