Abilitare gli indicatori di telemetria nelle librerie client Rust

Google Cloud offre funzionalità avanzate di monitoraggio, logging e diagnostica per le applicazioni Rust.

Le librerie client di Rust sono strumentate per emettere dati di tracciamento, metriche e logging. La strumentazione è facoltativa; devi attivarla in modo esplicito. Questo documento descrive gli indicatori disponibili e come attivarli.

Indicatori disponibili

Le librerie client di Rust sono strumentate per generare i seguenti indicatori:

  1. Span INFO per ogni richiesta client logica. In genere, una singola chiamata al metodo nella struct del client riceve uno span di questo tipo (ad esempio, la chiamata di access_secret_version su un client SecretManagerService).
  2. Una metrica dell'istogramma che misura il tempo trascorso per ogni richiesta client logica. La metrica principale è gcp.client.request.duration.
  3. Log WARN per ogni richiesta client logica non riuscita.
  4. Span INFO per ogni tentativo RPC di basso livello. In genere, un singolo metodo nella struct del client riceve uno span di questo tipo, ma potrebbero essercene di più se la libreria deve riprovare l'RPC.
  5. Log DEBUG per ogni tentativo di basso livello non riuscito.

Questi span e log seguono le convenzioni semantiche di OpenTelemetry con attributi aggiuntivi Google Cloud . Sia gli span che i log devono essere adatti al monitoraggio della produzione.

Gli indicatori includono attributi OpenTelemetry standard (ad esempio, http.response.status_code e rpc.system.name) e Google Cloud-specifici attributi personalizzati, che possono includere questi e attributi simili:

  • gcp.client.service: il nome del servizio (ad esempio, pubsub o storage).
  • gcp.client.repo: il repository della libreria client (ad esempio, googleapis/google-cloud-rust).
  • gcp.client.version: la versione della libreria client.
  • gcp.client.artifact: il percorso del modulo specifico (ad esempio, google-cloud-secretmanager).
  • gcp.resource.destination.id: l'ID della risorsa su cui viene eseguita l'azione.
  • gcp.errors.domain: il dominio di errore per i log di errore su cui è possibile intervenire.
  • gcp.errors.metadata.<key>: chiavi di metadati di errore aggiuntive per le richieste non riuscite (appiattite).

Per un elenco completo degli attributi standard, consulta le convenzioni semantiche HTTP e gRPC di OpenTelemetry.

Le librerie hanno anche span DEBUG per ogni richiesta. Questi includono il corpo della richiesta completo, il corpo della risposta completo per le richieste riuscite e il messaggio di errore completo, con i dettagli, per le richieste non riuscite.

Prima di abilitare questi elementi negli ambienti di produzione, esamina i contenuti di queste richieste e risposte, poiché potrebbero includere dati sensibili.

Questi span DEBUG utilizzano la crate della libreria client seguita da ::tracing come target (ad esempio, google_cloud_secretmanager_v1::tracing) e il nome del metodo come nome dello span (ad esempio, access_secret_version). Puoi utilizzare il nome, il target o entrambi per configurare i filtri.

Abilitazione della telemetria

Per proteggere i dati sensibili, gli indicatori di telemetria sono disattivati per impostazione predefinita.

In Rust, devi configurare il client per emettere tracce, metriche e log e devi configurare sottoscrittori ed esportatori per inviare questi indicatori a un servizio esterno.

Per configurare il client, puoi impostare la seguente variabile di ambiente:

export GOOGLE_CLOUD_RUST_LOGGING=true

In alternativa, puoi abilitare esplicitamente il tracciamento a livello di programmazione durante la creazione del client utilizzando il metodo .with_tracing() nel builder del client:

use google_cloud_secretmanager_v1::client::SecretManagerService;

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

Propagazione del contesto di Trace

Le librerie client di Rust propagano automaticamente i contesti di traccia attivi ai Google Cloud servizi, anche se la generazione di tracce non è abilitata in modo esplicito utilizzando .with_tracing().

Utilizza le crate tracing-opentelemetry o opentelemetry per fornire un contesto di tracciamento per le librerie client.

Esportazione della telemetria

Una volta abilitata la telemetria nelle librerie client, l'applicazione deve essere configurata per raccogliere ed esportare questi dati nel servizio di osservabilità. Le librerie client di Rust utilizzano in modo nativo l' ecosistema di tracciamento.

Tracciamento

Per esportare gli tracing span generati dalle Google Cloud librerie client in OpenTelemetry, devi configurare un Subscriber nella tua applicazione che invia i dati a un esportatore OpenTelemetry (ad esempio, OTLP).

Utilizza le crate tracing-opentelemetry e opentelemetry-otlp per configurare l'esportatore:

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

Metriche

Per esportare le metriche, devi installare un MeterProvider OpenTelemetry globale nella tua applicazione prima di inizializzare il client. Le librerie client lo utilizzeranno automaticamente per registrare ed esportare i dati delle metriche.

Per maggiori dettagli sulla raccolta e l'esportazione dei dati OpenTelemetry in Cloud Monitoring o Cloud Trace, consulta Scegliere un approccio di strumentazione.

Logging

Le librerie client di Rust utilizzano la crate tracing per emettere log di errore su cui è possibile intervenire ai livelli WARN e DEBUG. I log esportati includeranno ID traccia e ID span per garantire una correlazione perfetta con le tracce, a condizione che tu utilizzi un formattatore appropriato.

Per indirizzare questi log strutturati a Cloud Logging, configura un sottoscrittore di tracciamento per formattare gli eventi come JSON e inviarli all'output standard (stdout). Se esegui il deployment in un ambiente come Google Kubernetes Engine o Cloud Run, gli agenti integrati eseguono automaticamente lo scraping di questi log.

L'esempio seguente configura un sottoscrittore per acquisire e indirizzare solo i log di livello 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(())
}

Per istruzioni dettagliate sulla configurazione dei dati di correlazione delle tracce OpenTelemetry (ad esempio logging.googleapis.com/trace) nel formattatore JSON, consulta Panoramica degli esempi di strumentazione basata su collector.