Telemetrie zu Google Cloud

Die Funktion gcp von adk-telemetry exportiert Traces direkt nach Google Cloud Observability (Cloud Trace) und schreibt strukturierte JSON-Protokolle, die von Cloud Logging nativ analysiert werden – einschließlich Schweregrad, Nachricht und Trace-Korrelation.

Funktion aktivieren

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

Oder über das übergeordnete Crate (gcp-telemetry ist ebenfalls Teil des gemini-agent-platform-Meta-Features):

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

Direkter Export nach Google Cloud

init_with_gcp exportiert Spans über gRPC nach https://telemetry.googleapis.com und authentifiziert jede Anfrage mit einem Bearer-Token, das aus Application Default Credentials (ADC) sowie einem x-goog-user-project-Header erstellt wird. Eine Hintergrundaufgabe erstellt das Token alle fünf Minuten neu, sodass lang laufende Agents auch nach Ablauf des Tokens weiterhin exportieren.

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

Anforderungen:

Hinweis: Dieser Pfad exportiert ausschließlich Traces. Leiten Sie Metriken über den unten stehenden Collector-Sidecar weiter.

GCP-Ressourcenerkennung

init_with_gcp leitet OpenTelemetry-Ressourcenattribute aus den Umgebungsvariablen ab, die die Plattform in bereitgestellten Containern setzt:

GOOGLE_CLOUD_AGENT_ENGINE_ID ist die reine numerische Engine-ID, die Vertex AI Agent Engine in bereitgestellten Containern festlegt. gcp.agent_engine ist der kanonische Wert cloud.platform aus den semantischen Konventionen von OpenTelemetry (vorgelagert im Oktober 2025 hinzugefügt).

Dieselbe Erkennung ist auch eigenständig verfügbar, um Ihre eigene Pipeline zusammenzustellen:

use adk_telemetry::gcp_resource_attributes;

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

Strukturierte JSON-Protokollierung für Cloud Logging

init_json_logging schreibt ein JSON-Objekt pro Zeile in stdout, sodass Cloud Logging Schweregrad- und Trace-Felder analysiert, anstatt undurchsichtige Textnutzdaten anzuzeigen. init_with_gcp installiert dasselbe Format automatisch.

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

Ausgegebene Felder:

Trace-Korrelationsfelder erfordern eine OpenTelemetry-Ebene im selben Subscriber und GOOGLE_CLOUD_PROJECT – init_with_gcp stellt beides bereit, sodass Protokolleinträge inline im Cloud-Trace-Bereich angezeigt werden.

Fallback: OTLP zu einem Collector-Sidecar

Wenn der direkte Zugriff auf API nicht verfügbar ist – oder wenn Sie zusätzlich Metriken benötigen –, führen Sie einen OpenTelemetry Collector als Sidecar aus und richten Sie den standardmäßigen OTLP-Exporter darauf aus:

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

Collector-Konfiguration zur Weiterleitung an Google Cloud (otel-collector-config.yaml unter Verwendung des googlecloud-Exporters aus der Contrib-Distribution):

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]

Führen Sie ihn lokal für die Entwicklung aus:

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

Einen Pfad auswählen

Verwandte Themen

• Telemetrie – Einrichtung der Kerntelemetrie und Span-Hilfsfunktionen
• Bereitstellung – Einrichtung der Produktionstelemetrie