Telemetriesignale in Rust-Clientbibliotheken aktivieren

Google Cloud bietet leistungsstarke Monitoring-, Protokollierungs- und Diagnosefunktionen für Rust-Anwendungen.

Die Rust-Clientbibliotheken sind so instrumentiert, dass sie Tracing-, Messwert- und Protokolldaten ausgeben. Die Instrumentierung ist optional. Sie müssen sie explizit aktivieren. In diesem Dokument werden die verfügbaren Signale und die Aktivierung beschrieben.

Verfügbare Signale

Die Rust-Clientbibliotheken sind so instrumentiert, dass sie die folgenden Signale generieren:

  1. INFO-Spans für jede logische Clientanfrage. In der Regel erhält ein einzelner Methodenaufruf in der Clientstruktur einen solchen Span, z. B. wenn access_secret_version auf einem SecretManagerService-Client aufgerufen wird.
  2. Ein Histogramm-Messwert, der die verstrichene Zeit für jede logische Clientanfrage misst. Der primäre Messwert ist gcp.client.request.duration.
  3. WARN-Logs für jede logische Clientanfrage, die fehlschlägt.
  4. INFO-Spans für jeden RPC-Versuch auf niedriger Ebene. In der Regel erhält eine einzelne Methode in der Clientstruktur einen solchen Span. Es können jedoch mehr sein, wenn die Bibliothek den RPC wiederholen muss.
  5. DEBUG-Logs für jeden fehlgeschlagenen Versuch auf niedriger Ebene.

Diese Spans und Logs folgen den semantischen OpenTelemetry Konventionen mit zusätzlichen Google Cloud Attributen. Sowohl die Spans als auch die Logs sollten für das Produktionsmonitoring geeignet sein.

Die Signale enthalten standardmäßige OpenTelemetry-Attribute (z. B. http.response.status_code und rpc.system.name) und Google Cloud-spezifische benutzerdefinierte Attribute, darunter die folgenden und ähnliche Attribute:

  • gcp.client.service: Der Dienstname, z. B. pubsub oder storage.
  • gcp.client.repo: Das Repository der Clientbibliothek, z. B. googleapis/google-cloud-rust.
  • gcp.client.version: Die Version der Clientbibliothek.
  • gcp.client.artifact: Der spezifische Modulpfad, z. B. google-cloud-secretmanager.
  • gcp.resource.destination.id: Die ID der Ressource, auf die sich die Aktion bezieht.
  • gcp.errors.domain: Die Fehlerdomain für umsetzbare Fehlerlogs.
  • gcp.errors.metadata.<key>: Zusätzliche Metadatenschlüssel für Fehler für fehlgeschlagene Anfragen (vereinfacht).

Eine vollständige Liste der Standardattribute finden Sie in den semantischen OpenTelemetry-Konventionen für HTTP und gRPC.

Die Bibliotheken haben auch DEBUG-Spans für jede Anfrage. Dazu gehören der vollständige Anfragetext, der vollständige Antworttext für erfolgreiche Anfragen und die vollständige Fehlermeldung mit Details für fehlgeschlagene Anfragen.

Prüfen Sie den Inhalt dieser Anfragen und Antworten, bevor Sie sie in Produktionsumgebungen aktivieren, da die Anfragen oder Antworten sensible Daten enthalten können.

Diese DEBUG-Spans verwenden die Clientbibliotheks-Crate gefolgt von ::tracing als Ziel (z. B. google_cloud_secretmanager_v1::tracing) und den Methodennamen als Spannamen (z. B. access_secret_version). Sie können den Namen, das Ziel oder beides verwenden, um Ihre Filter einzurichten.

Telemetrie aktivieren

Zum Schutz sensibler Daten sind Telemetriesignale standardmäßig deaktiviert.

In Rust müssen Sie den Client so konfigurieren, dass er Traces, Messwerte und Logs ausgibt. Außerdem müssen Sie Abonnenten und Exporter konfigurieren, um diese Signale an einen externen Dienst zu senden.

Um den Client zu konfigurieren, können Sie die folgende Umgebungsvariable festlegen:

export GOOGLE_CLOUD_RUST_LOGGING=true

Alternativ können Sie das Tracing programmatisch explizit aktivieren, wenn Sie Ihren Client mit der Methode .with_tracing() im Client Builder erstellen:

use google_cloud_secretmanager_v1::client::SecretManagerService;

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

Weitergabe von Trace-Kontext

Die Rust-Clientbibliotheken geben aktive Trace-Kontexte automatisch an Google Cloud Dienste weiter, auch wenn die Trace-Generierung nicht explizit mit .with_tracing()aktiviert ist.

Verwenden Sie die tracing-opentelemetry oder opentelemetry Crates, um einen Tracing Kontext für die Clientbibliotheken bereitzustellen.

Telemetrie exportieren

Nachdem die Telemetrie in den Clientbibliotheken aktiviert wurde, muss Ihre Anwendung so konfiguriert sein, dass diese Daten erfasst und an Ihren Observability-Dienst exportiert werden. Die Rust-Clientbibliotheken verwenden nativ das Tracing-Ökosystem.

Tracing

Wenn Sie die von den Google Cloud Clientbibliotheken generiertentracing Spans nach OpenTelemetry exportieren möchten, müssen Sie in Ihrer Anwendung einen Subscriber konfigurieren, der Daten an einen OpenTelemetry-Exporter (z. B. OTLP) weiterleitet.

Verwenden Sie die Crates tracing-opentelemetry und opentelemetry-otlp, um den Exporter zu konfigurieren:

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(())
}

Messwerte

Wenn Sie Messwerte exportieren möchten, müssen Sie in Ihrer Anwendung einen globalen OpenTelemetry-MeterProvider installieren, bevor Sie den Client initialisieren. Die Clientbibliotheken verwenden ihn automatisch, um Messwertdaten aufzuzeichnen und zu exportieren.

Weitere Informationen zum Erfassen und Exportieren von OpenTelemetry-Daten nach Cloud Monitoring oder Cloud Trace finden Sie unter Instrumentierungsansatz auswählen.

Logging

Die Rust-Clientbibliotheken verwenden die Crate tracing, um umsetzbare Fehlerlogs auf den Ebenen WARN und DEBUG auszugeben. Die exportierten Logs enthalten Trace-IDs und Span-IDs, um eine nahtlose Korrelation mit Ihren Traces zu gewährleisten, sofern Sie einen geeigneten Formatierer verwenden.

Wenn Sie diese strukturierten Logs an Cloud Logging weiterleiten möchten, konfigurieren Sie einen Tracing-Abonnenten, um Ereignisse als JSON zu formatieren und an die Standardausgabe (stdout) auszugeben. Wenn Sie in einer Umgebung wie Google Kubernetes Engine oder Cloud Run bereitstellen, werden diese Logs automatisch von den integrierten Agents erfasst.

Im folgenden Beispiel wird ein Abonnent konfiguriert, um nur Logs der Ebene WARN zu erfassen und weiterzuleiten.

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(())
}

Eine detaillierte Anleitung zum Konfigurieren der OpenTelemetry-Trace-Korrelation daten (z. B. logging.googleapis.com/trace) im JSON-Formatierer finden Sie unter Übersicht über instrumentierungsbasierte Collector- Beispiele.