将遥测数据发送到 Google Cloud

gcp 功能可将 adk-telemetry 的追踪数据直接导出到 Google Cloud Observability（Cloud Trace），并写入结构化的 JSON 日志，Cloud Logging 可原生解析这些日志——其中包括严重性、消息和追踪关联信息。

启用此功能

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

或者通过伞形 crate 启用（gcp-telemetry 也是 gemini-agent-platform 元功能的一部分）：

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

直接导出到 Google Cloud

init_with_gcp 通过 gRPC 将跨度导出到 https://telemetry.googleapis.com，使用从 Application Default Credentials (ADC) 生成的 Bearer 令牌以及 x-goog-user-project 标头对每个请求进行身份验证。后台任务每五分钟重新生成一次令牌，因此长时间运行的 agent 即使令牌过期，也能持续导出数据。

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

要求：

注意： 此路径仅导出追踪信息。请通过下方的收集器 sidecar 路由指标。

GCP 资源检测

init_with_gcp 根据平台在已部署容器中设置的环境变量，推导 OpenTelemetry 资源属性：

GOOGLE_CLOUD_AGENT_ENGINE_ID 是 Vertex AI Agent Engine 在已部署容器中设置的纯数字引擎 ID。gcp.agent_engine 是来自 OpenTelemetry 语义约定的规范 cloud.platform 值（上游于 2025 年 10 月添加）。

相同的检测功能也可以独立使用，以便组合您自己的流水线：

use adk_telemetry::gcp_resource_attributes;

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

用于 Cloud Logging 的结构化 JSON 日志记录

init_json_logging 每行向 stdout 写入一个 JSON 对象，因此 Cloud Logging 会解析严重性和跟踪字段，而不是显示不透明的文本有效负载。init_with_gcp 会自动安装相同的格式。

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

输出字段：

Trace 关联字段要求同一订阅者中包含 OpenTelemetry 层和 GOOGLE_CLOUD_PROJECT — init_with_gcp 同时提供这两者，因此日志条目会以内联方式显示在 Cloud Trace 面板中。

备用方案：通过 Sidecar 使用 OTLP

当无法直接访问 API 时，或者还需要指标数据时，可以将 OpenTelemetry Collector 作为 sidecar 运行，并将标准 OTLP exporter 指向它：

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

将数据转发到 Google Cloud 的 Collector 配置（otel-collector-config.yaml，使用 contrib 分发版中的 googlecloud exporter）：

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]

在本地运行以进行开发：

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

选择方案

相关

• 遥测 - 核心遥测设置和跨度辅助工具
• 部署 - 生产环境遥测设置