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 Rust sono strumentate per emettere dati di tracciamento, metriche e logging. L'instrumentazione è facoltativa, devi attivarla esplicitamente. Questo documento descrive gli indicatori disponibili e come attivarli.

Indicatori disponibili

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

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

Questi intervalli e log seguono le Convenzioni semantiche di OpenTelemetry con attributiGoogle Cloud aggiuntivi. 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 attributi personalizzati specifici di Google Cloud, 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 degli errori azionabili.
• gcp.errors.metadata.<key>: Chiavi dei 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 intervalli DEBUG per ogni richiesta. Questi includono l'intero corpo della richiesta, l'intero corpo della risposta per le richieste riuscite e l'intero messaggio di errore, con i dettagli, per le richieste non riuscite.

Valuta i contenuti di queste richieste e risposte prima di attivarle negli ambienti di produzione, poiché la richiesta o le risposte potrebbero includere dati sensibili.

Questi intervalli DEBUG utilizzano il crate della libreria client seguito da ::tracing come target (ad esempio google_cloud_secretmanager_v1::tracing) e il nome del metodo come nome dell'intervallo (ad esempio access_secret_version). Puoi utilizzare il nome, il target o entrambi per configurare i filtri.

Attivazione della telemetria

I segnali di osservabilità a qualsiasi livello possono contenere dati sensibili, come nomi di risorse, URL completi e messaggi di errore.

Prima di configurare i sottoscrittori o gli esportatori per le tracce e i log, esamina i contenuti degli span e consulta la documentazione del framework di tracing per configurare filtri e formattatori per impedire la divulgazione di informazioni sensibili, a seconda del caso d'uso previsto.

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 i sottoscrittori e gli esportatori per inviare questi segnali a un servizio esterno.

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

export GOOGLE_CLOUD_RUST_LOGGING=true

In alternativa, puoi attivare esplicitamente la tracciabilità a livello di programmazione durante la creazione del client utilizzando il metodo .with_tracing() nel generatore di client:

use google_cloud_secretmanager_v1::client::SecretManagerService;

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

Propagazione del contesto di Trace

Le librerie client Rust propagano automaticamente i contesti di traccia attivi ai serviziGoogle Cloud , anche se la generazione di tracce non è abilitata esplicitamente utilizzando .with_tracing().

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

Esportazione della telemetria

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

Tracciamento

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

Utilizza i 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 ulteriori 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 Rust utilizzano il crate tracing per generare log di errori azionabili ai livelli WARN e DEBUG. I log esportati includeranno ID traccia e ID span per garantire una correlazione perfetta con le tue tracce, a condizione che utilizzi un formattatore appropriato.

Per indirizzare questi log strutturati a Cloud Logging, configura un abbonato alla traccia 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 abbonato per acquisire e instradare 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 formatter JSON, consulta la panoramica degli esempi di strumentazione basata su collector.