Telemetriesignale in Rust-Clientbibliotheken aktivieren

Google Cloud bietet leistungsstarkes Monitoring, Logging und leistungsstarke Diagnose für Rust-Anwendungen.

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

Verfügbare Signale

Die Rust-Clientbibliotheken sind so instrumentiert, dass die folgenden Signale generiert werden:

1. INFO-Spans für jede logische Clientanfrage. In der Regel wird ein solcher Bereich durch einen einzelnen Methodenaufruf in der Clientstruktur abgerufen, z. B. durch Aufrufen von access_secret_version für einen SecretManagerService-Client.
2. Ein Histogrammmesswert, 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 fehlgeschlagene logische Clientanfrage.
4. INFO-Spans für jeden Low-Level-RPC-Versuch. Normalerweise wird für jede Methode im Client-Struct ein solcher Bereich erstellt. Wenn die Bibliothek den RPC jedoch noch einmal versuchen muss, kann es auch mehr geben.
5. DEBUG-Logs für jeden fehlgeschlagenen Low-Level-Versuch.

Diese Spans und Logs folgen den OpenTelemetry Semantic Conventions mit zusätzlichenGoogle Cloud -Attributen. Sowohl die Spans als auch die Logs sollten für das Produktionsmonitoring geeignet sein.

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

• gcp.client.service: Der Dienstname, z. B. pubsub oder storage.
• gcp.client.repo: Das Clientbibliotheks-Repository (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 (reduziert).

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

Die Bibliotheken enthalten 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 Anfrage oder Antworten sensible Daten enthalten können.

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

Telemetrie aktivieren

Signale zur Beobachtbarkeit können auf jeder Ebene sensible Daten wie Ressourcennamen, vollständige URLs und Fehlermeldungen enthalten.

Bevor Sie Abonnenten oder Exporter für Traces und Logs konfigurieren, sollten Sie die Inhalte der Spans prüfen und die Dokumentation zum Tracing-Framework lesen, um Filter und Formatierer einzurichten, die je nach Anwendungsfall die Weitergabe vertraulicher Informationen verhindern.

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 und Abonnenten und Exporter so konfigurieren, dass diese Signale an einen externen Dienst gesendet werden.

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

export GOOGLE_CLOUD_RUST_LOGGING=true

Alternativ können Sie das Tracing programmatisch aktivieren, wenn Sie Ihren Client mit der Methode .with_tracing() für den 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 übertragen aktive Trace-Kontexte automatisch anGoogle Cloud -Dienste, auch wenn die Trace-Generierung nicht explizit mit .with_tracing() aktiviert ist.

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

Telemetrie exportieren

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

Tracing

Wenn Sie die von den Clientbibliotheken Google Cloud generierten tracing-Spans in 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 ein globales OpenTelemetry-MeterProvider installieren, bevor Sie den Client initialisieren. Die Clientbibliotheken verwenden sie 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 das tracing-Crate, um umsetzbare Fehlerlogs auf den Ebenen WARN und DEBUG auszugeben. Die exportierten Logs enthalten Trace-IDs und Span-IDs, damit sie sich nahtlos mit Ihren Traces korrelieren lassen, sofern Sie einen geeigneten Formatierer verwenden.

Wenn Sie diese strukturierten Logs an Cloud Logging weiterleiten möchten, konfigurieren Sie einen Tracing-Subscriber, um Ereignisse als JSON zu formatieren und in 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 so konfiguriert, dass nur Logs auf WARN-Ebene erfasst und weitergeleitet werden.

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-Korrelationsdaten (z. B. logging.googleapis.com/trace) im JSON-Formatierer finden Sie unter Übersicht über Collector-basierte Instrumentierungsbeispiele.