Telemetria para o Google Cloud

O recurso gcp de adk-telemetry exporta traces diretamente para o Google Cloud Observability (Cloud Trace) e grava logs estruturados de JSON que o Cloud Logging analisa nativamente — incluindo severidade, mensagem e correlação de trace.

Ativar o recurso

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

Ou por meio do crate abrangente (gcp-telemetry também faz parte do metarrecurso gemini-agent-platform):

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

Exportação direta para o Google Cloud

init_with_gcp exporta spans para https://telemetry.googleapis.com por gRPC, autenticando cada solicitação com um token Bearer gerado a partir das Application Default Credentials (ADC), além de um cabeçalho x-goog-user-project. Uma tarefa em segundo plano gera o token novamente a cada cinco minutos, para que agentes de longa duração continuem exportando após a expiração do token.

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:

Observação: Este caminho exporta apenas rastreamentos. Encaminhe as métricas pelo sidecar coletor abaixo.

Detecção de recursos do GCP

init_with_gcp deriva atributos de recurso OpenTelemetry das variáveis de ambiente que a plataforma define nos contêineres implantados:

GOOGLE_CLOUD_AGENT_ENGINE_ID é o ID numérico bruto do mecanismo que o Vertex AI Agent Engine define nos contêineres implantados. gcp.agent_engine é o valor canônico de cloud.platform das convenções semânticas de OpenTelemetry (adicionado upstream em outubro de 2025).

A mesma detecção está disponível de forma independente para compor seu próprio pipeline:

use adk_telemetry::gcp_resource_attributes;

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

Registro estruturado de JSON para o Cloud Logging

init_json_logging grava um objeto JSON por linha na saída padrão, para que o Cloud Logging analise os campos de severidade e de rastreamento em vez de exibir cargas de texto opacas. init_with_gcp instala o mesmo formato automaticamente.

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:

Os campos de correlação de trace exigem uma camada OpenTelemetry no mesmo subscriber e GOOGLE_CLOUD_PROJECT — init_with_gcp fornece ambos, fazendo com que as entradas de log apareçam em linha no painel do Cloud Trace.

Fallback: OTLP para um sidecar do Collector

Quando o acesso direto a API não está disponível — ou quando você também precisa de métricas — execute um Collector OpenTelemetry como sidecar e aponte o exportador OTLP padrão para ele:

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

Configuração do Collector encaminhando para o Google Cloud (otel-collector-config.yaml, usando o exportador googlecloud da distribuição 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]

Execute-o localmente para desenvolvimento:

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

Escolhendo um caminho

Relacionados

• Telemetria - Configuração da telemetria principal e auxiliares de span
• Implantação - Configuração da telemetria de produção