Telemetría a Google Cloud

La funcionalidad gcp de adk-telemetry exporta trazas directamente a Google Cloud Observability (Cloud Trace) y escribe registros estructurados de JSON que Cloud Logging analiza de forma nativa: se incluyen la gravedad, el mensaje y la correlación de trazas.

Habilitar la funcionalidad

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

O mediante el crate paraguas (gcp-telemetry también forma parte de la meta-funcionalidad gemini-agent-platform):

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

Exportación directa a Google Cloud

init_with_gcp exporta spans a https://telemetry.googleapis.com mediante gRPC, autenticando cada solicitud con un token Bearer generado a partir de Application Default Credentials (ADC), además de un encabezado x-goog-user-project. Una tarea en segundo plano vuelve a generar el token cada cinco minutos, por lo que los agentes de larga duración continúan exportando aunque el token caduque.

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

Requisitos:

Nota: Esta ruta exporta únicamente trazas. Enruta las métricas a través del sidecar del colector que se muestra a continuación.

Detección de recursos de GCP

init_with_gcp deriva los atributos de recursos de OpenTelemetry a partir de las variables de entorno que la plataforma establece en los contenedores implementados:

GOOGLE_CLOUD_AGENT_ENGINE_ID es el ID numérico básico del motor que Vertex AI Agent Engine establece en los contenedores desplegados. gcp.agent_engine es el valor canónico de cloud.platform de las convenciones semánticas de OpenTelemetry (añadido en upstream en octubre de 2025).

La misma detección está disponible de forma independiente para componer tu propio flujo:

use adk_telemetry::gcp_resource_attributes;

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

Registro estructurado de JSON para Cloud Logging

init_json_logging escribe un objeto JSON por línea en stdout, por lo que Cloud Logging analiza los campos de gravedad y traza en lugar de mostrar cargas de texto opacas. init_with_gcp instala automáticamente el mismo formato.

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

Campos emitidos:

Los campos de correlación de trazas requieren una capa de OpenTelemetry en el mismo suscriptor y GOOGLE_CLOUD_PROJECT — init_with_gcp proporciona ambos, lo que hace que las entradas de registro aparezcan integradas en el panel de Cloud Trace.

Alternativa: OTLP a un sidecar de Collector

Cuando el acceso directo a API no está disponible —o cuando también necesitas métricas— ejecuta un Collector de OpenTelemetry como sidecar y apunta el exportador OTLP estándar hacia él:

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

Configuración del Collector para reenviar datos a Google Cloud (otel-collector-config.yaml, usando el exportador googlecloud de la distribución 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]

Ejecútalo localmente para desarrollo:

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

Cómo elegir una opción

Relacionado

• Telemetría - Configuración de telemetría principal y asistentes de intervalos
• Implementación - Configuración de telemetría para producción