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. Étendues INFO pour chaque requête client logique. En règle générale, un seul appel de méthode dans la structure du client obtient un tel segment (par exemple, l'appel de access_secret_version sur un client SecretManagerService).
2. Une 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 qui échoue.
4. Étendues INFO 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 étendue, mais il peut y en avoir plus si la bibliothèque doit réessayer le RPC.
5. Journaux DEBUG pour chaque tentative de bas niveau qui échoue.

Ces étendues et ces journaux suivent les conventions sémantiques OpenTelemetry avec des Google Cloud attributs supplémentaires. Les étendues 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 Google Cloud-spécifiques attributs personnalisés, 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 au module spécifique (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. Elles incluent le corps complet de la requête, le corps complet de la réponse pour les requêtes ayant réussi et le message d'erreur complet, avec des détails, pour les requêtes ayant échoué.

Tenez compte du contenu de ces requêtes et réponses avant de les activer dans les environnements de production, car la requête ou les réponses peuvent inclure des données sensibles.

Ces étendues DEBUG utilisent le conteneur 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 d'é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

Les signaux d'observabilité, quel que soit leur niveau, peuvent contenir des données sensibles telles que des noms de ressources, des URL complètes et des messages d'erreur.

Avant de configurer des abonnés ou des exportateurs pour les traces et les journaux, examinez le contenu des étendues et consultez la documentation du framework de traçage pour configurer des filtres et des formateurs afin d'éviter la fuite d'informations sensibles, en fonction de votre cas d'utilisation.

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

Dans 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 par programmation lors de la création de votre client à l'aide de la méthode .with_tracing() sur le compilateur 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 Google Cloud services, même si la génération de traces n'est pas explicitement activée à l'aide de .with_tracing().

Utilisez les conteneurs 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 de traçage.

Traçage

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

Utilisez les conteneurs 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 conteneur 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 d'étendue pour assurer une corrélation transparente 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 pour mettre en forme les événements au format JSON et les envoyer à 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 capturer et acheminer 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és sur un collecteur.