Télémétrie vers Google Cloud

La fonctionnalité gcp de adk-telemetry exporte directement les traces vers Google Cloud Observability (Cloud Trace) et écrit des journaux JSON structurés que Cloud Logging analyse nativement — gravité, message et corrélation des traces inclus.

Activer la fonctionnalité

[dependencies]
adk-telemetry = { version = "2.1.0", features = ["gcp"] }

Ou via le crate umbrella (gcp-telemetry fait également partie de la méta-fonctionnalité gemini-agent-platform) :

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "gcp-telemetry"] }

Export direct vers Google Cloud

init_with_gcp exporte les spans vers https://telemetry.googleapis.com via gRPC, en authentifiant chaque requête avec un jeton Bearer généré à partir des Application Default Credentials (ADC), ainsi qu’un en-tête x-goog-user-project. Une tâche en arrière-plan génère un nouveau jeton toutes les cinq minutes ; les agents de longue durée continuent ainsi à exporter les données même après l’expiration du jeton.

use adk_telemetry::init_with_gcp;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Requires GOOGLE_CLOUD_PROJECT and Application Default Credentials.
    init_with_gcp("my-agent").await?;

    // Your agent code here

    adk_telemetry::shutdown_telemetry();
    Ok(())
}

Prérequis :

Remarque : Ce chemin exporte uniquement les traces. Acheminez les métriques via le sidecar du collecteur ci-dessous.

Détection des ressources GCP

init_with_gcp dérive les attributs de ressource OpenTelemetry à partir des variables d’environnement définies par la plateforme dans les conteneurs déployés :

GOOGLE_CLOUD_AGENT_ENGINE_ID est l’identifiant numérique brut du moteur que Vertex AI Agent Engine définit dans les conteneurs déployés. gcp.agent_engine est la valeur canonique cloud.platform issue des conventions sémantiques OpenTelemetry (ajoutée en amont en octobre 2025).

La même détection est disponible de manière autonome pour composer votre propre pipeline :

use adk_telemetry::gcp_resource_attributes;

let attributes = gcp_resource_attributes("my-agent");

Journalisation JSON structurée pour Cloud Logging

init_json_logging écrit un objet JSON par ligne sur la sortie standard, afin que Cloud Logging analyse les champs de gravité et de trace au lieu d’afficher des charges utiles textuelles opaques. init_with_gcp installe automatiquement le même format.

use adk_telemetry::init_json_logging;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_json_logging()?;

    tracing::info!(user.id = "u1", "request handled");
    Ok(())
}

Champs émis :

Les champs de corrélation des traces nécessitent une couche OpenTelemetry dans le même subscriber et GOOGLE_CLOUD_PROJECT — init_with_gcp fournit les deux, ce qui fait apparaître les entrées de journal directement dans le panneau Cloud Trace.

Solution de repli : OTLP vers un sidecar Collector

Lorsque l’accès direct à API n’est pas disponible — ou lorsque vous avez également besoin de métriques — exécutez un Collector OpenTelemetry en tant que sidecar et pointez l’exportateur OTLP standard vers celui-ci :

use adk_telemetry::init_with_otlp;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_with_otlp("my-agent", "http://localhost:4317")?;

    // Your agent code here

    adk_telemetry::shutdown_telemetry();
    Ok(())
}

Configuration du Collector pour transférer les données vers Google Cloud (otel-collector-config.yaml, à l’aide de l’exportateur googlecloud de la distribution contrib) :

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:
    send_batch_size: 200
    timeout: 5s
  resourcedetection:
    detectors: [env, gcp]

exporters:
  googlecloud:
    project: my-project

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, batch]
      exporters: [googlecloud]
    metrics:
      receivers: [otlp]
      processors: [resourcedetection, batch]
      exporters: [googlecloud]

Exécutez-le localement pour le développement :

docker run --rm -p 4317:4317 \
  -v ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml \
  -v ~/.config/gcloud:/root/.config/gcloud \
  otel/opentelemetry-collector-contrib:latest

Choisir une approche

Documentation associée

• Télémétrie - Configuration de base de la télémétrie et assistants de spans
• Déploiement - Configuration de la télémétrie en production