Telemetry to Google Cloud

The gcp feature of adk-telemetry exports traces directly to Google Cloud Observability (Cloud Trace) and writes structured JSON logs that Cloud Logging parses natively — severity, message, and trace correlation included.

Enable the Feature

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

Or through the umbrella crate (gcp-telemetry is also part of the gemini-agent-platform meta-feature):

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

Direct Export to Google Cloud

init_with_gcp exports spans to https://telemetry.googleapis.com over gRPC, authenticating each request with a Bearer token minted from Application Default Credentials (ADC) plus an x-goog-user-project header. A background task re-mints the token every five minutes, so long-running agents keep exporting across token expiry.

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

Requirements:

Note: This path exports traces only. Route metrics through the collector sidecar below.

GCP Resource Detection

init_with_gcp derives OpenTelemetry resource attributes from the environment variables the platform sets in deployed containers:

GOOGLE_CLOUD_AGENT_ENGINE_ID is the bare numeric engine ID that Vertex AI Agent Engine sets in deployed containers. gcp.agent_engine is the canonical cloud.platform value from the OpenTelemetry semantic conventions (added upstream in October 2025).

The same detection is available standalone for composing your own pipeline:

use adk_telemetry::gcp_resource_attributes;

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

Structured JSON Logging for Cloud Logging

init_json_logging writes one JSON object per line to stdout, so Cloud Logging parses severity and trace fields instead of showing opaque text payloads. init_with_gcp installs the same format automatically.

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

Emitted fields:

Trace correlation fields require an OpenTelemetry layer in the same subscriber and GOOGLE_CLOUD_PROJECT — init_with_gcp provides both, which makes log entries appear inline in the Cloud Trace panel.

Fallback: OTLP to a Collector Sidecar

When direct API access is unavailable — or when you also need metrics — run an OpenTelemetry Collector as a sidecar and point the standard OTLP exporter at it:

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 configuration forwarding to Google Cloud (otel-collector-config.yaml, using the googlecloud exporter from the 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]

Run it locally for development:

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

Choosing a Path

Related

• Telemetry - Core telemetry setup and span helpers
• Deployment - Production telemetry setup