Activer les signaux de télémétrie dans les bibliothèques clientes Rust

Google Cloud propose une suite très performante d'outils de surveillance, de journalisation et de diagnostic pour les applications Rust.

Les bibliothèques clientes Rust sont instrumentées pour émettre des données de traçage, de métriques et de journalisation. L'instrumentation est facultative. Vous devez l'activer explicitement. Ce document décrit les signaux disponibles et explique comment les activer.

Signaux disponibles

Les bibliothèques clientes Rust sont instrumentées pour générer les signaux suivants :

  1. INFO étendues pour chaque requête client logique. En général, un seul appel de méthode dans la structure du client obtient une telle portée (par exemple, en appelant access_secret_version sur un client SecretManagerService).
  2. Métrique d'histogramme mesurant le temps écoulé pour chaque requête client logique. La métrique principale est gcp.client.request.duration.
  3. Journaux WARN pour chaque requête client logique ayant échoué.
  4. INFO étendues pour chaque tentative de RPC de bas niveau. En règle générale, une seule méthode dans la structure du client obtient une telle portée, mais il peut y en avoir davantage si la bibliothèque doit réessayer le RPC.
  5. Les journaux DEBUG sont enregistrés pour chaque tentative de bas niveau ayant échoué.

Ces spans et journaux suivent les conventions sémantiques OpenTelemetry avec des attributsGoogle Cloud supplémentaires. Les spans et les journaux doivent être adaptés à la surveillance de la production.

Les signaux incluent des attributs OpenTelemetry standards (par exemple, http.response.status_code et rpc.system.name) et des attributs personnalisés spécifiques à Google Cloud, qui peuvent inclure les attributs suivants et d'autres similaires :

  • gcp.client.service : nom du service (par exemple, pubsub ou storage).
  • gcp.client.repo : dépôt de la bibliothèque cliente (par exemple, googleapis/google-cloud-rust).
  • gcp.client.version : version de la bibliothèque cliente.
  • gcp.client.artifact : chemin d'accès spécifique au module (par exemple, google-cloud-secretmanager).
  • gcp.resource.destination.id : ID de la ressource sur laquelle l'action est effectuée.
  • gcp.errors.domain : domaine d'erreur pour les journaux d'erreurs exploitables.
  • gcp.errors.metadata.<key> : clés de métadonnées d'erreur supplémentaires pour les requêtes ayant échoué (aplaties).

Pour obtenir la liste complète des attributs standards, consultez les conventions sémantiques OpenTelemetry HTTP et gRPC.

Les bibliothèques comportent également des étendues DEBUG pour chaque requête. Cela inclut le corps complet de la requête, le corps complet de la réponse pour les requêtes réussies et le message d'erreur complet, avec des détails, pour les requêtes ayant échoué.

Examinez le contenu de ces requêtes et réponses avant de les activer dans les environnements de production, car elles peuvent inclure des données sensibles.

Ces étendues DEBUG utilisent le crate de la bibliothèque cliente suivi de ::tracing comme cible (par exemple, google_cloud_secretmanager_v1::tracing) et le nom de la méthode comme nom de l'étendue (par exemple, access_secret_version). Vous pouvez utiliser le nom, la cible ou les deux pour configurer vos filtres.

Activer la télémétrie

Pour protéger les données sensibles, les signaux de télémétrie sont désactivés par défaut.

En Rust, vous devez configurer le client pour qu'il émette des traces, des métriques et des journaux et configurer des abonnés et des exportateurs pour envoyer ces signaux à un service externe.

Pour configurer le client, vous pouvez définir la variable d'environnement suivante :

export GOOGLE_CLOUD_RUST_LOGGING=true

Vous pouvez également activer explicitement le traçage de manière programmatique lors de la création de votre client en utilisant la méthode .with_tracing() sur le générateur de client :

use google_cloud_secretmanager_v1::client::SecretManagerService;

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

Propagation du contexte de trace

Les bibliothèques clientes Rust propagent automatiquement les contextes de trace actifs aux servicesGoogle Cloud , même si la génération de trace n'est pas explicitement activée à l'aide de .with_tracing().

Utilisez les caisses tracing-opentelemetry ou opentelemetry pour fournir un contexte de traçage aux bibliothèques clientes.

Exporter la télémétrie

Une fois la télémétrie activée dans les bibliothèques clientes, votre application doit être configurée pour collecter et exporter ces données vers votre service d'observabilité. Les bibliothèques clientes Rust utilisent nativement l'écosystème tracing.

Traçage

Pour exporter les spans tracing générés par les bibliothèques clientes Google Cloud vers OpenTelemetry, vous devez configurer un Subscriber dans votre application qui transmet les données à un exportateur OpenTelemetry (OTLP, par exemple).

Utilisez les caisses tracing-opentelemetry et opentelemetry-otlp pour configurer l'exportateur :

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

Métriques

Pour exporter des métriques, vous devez installer un MeterProvider OpenTelemetry global dans votre application avant d'initialiser le client. Les bibliothèques clientes l'utiliseront automatiquement pour enregistrer et exporter les données de métriques.

Pour en savoir plus sur la collecte et l'exportation de données OpenTelemetry vers Cloud Monitoring ou Cloud Trace, consultez Choisir une approche d'instrumentation.

Journalisation

Les bibliothèques clientes Rust utilisent le crate tracing pour émettre des journaux d'erreurs exploitables aux niveaux WARN et DEBUG. Les journaux exportés incluront des ID de trace et des ID de segment pour assurer une corrélation fluide avec vos traces, à condition que vous utilisiez un formateur approprié.

Pour acheminer ces journaux structurés vers Cloud Logging, configurez un abonné de traçage afin de mettre en forme les événements au format JSON et de les envoyer vers la sortie standard (stdout). Si vous effectuez un déploiement dans un environnement tel que Google Kubernetes Engine ou Cloud Run, les agents intégrés récupèrent automatiquement ces journaux.

L'exemple suivant configure un abonné pour qu'il capture et achemine uniquement les journaux de niveau 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(())
}

Pour obtenir des instructions détaillées sur la configuration des données de corrélation de trace OpenTelemetry (comme logging.googleapis.com/trace) dans le formateur JSON, consultez Présentation des exemples d'instrumentation basée sur le collecteur.