Google Cloud 遥测与客户端标识

为日志、指标和 traces 配置项目、身份和 IAM，选择直接导出或 Collector。

This page has not been translated into English yet. The original Chinese version is shown below.

Gemini CLI 可将遥测直接导出到 Cloud Logging、Cloud Monitoring 和 Cloud Trace。先准备项目、认证和写入权限，再启用目标；模型调用能成功并不自动证明遥测写入权限齐全。

选择遥测项目

使用独立遥测项目时设置：

export OTLP_GOOGLE_CLOUD_PROJECT="your-telemetry-project-id"

与推理使用同一项目时，官方指南也支持 GOOGLE_CLOUD_PROJECT。示例选择独立项目，后面的 API 启用命令引用同一个变量；替换为组织的真实项目 ID。

身份与写入权限

可以使用 Application Default Credentials：用户通过 gcloud auth application-default login 登录，服务账号可以通过 GOOGLE_APPLICATION_CREDENTIALS 指向凭据文件。

直接导出还支持 telemetry.useCliAuth: true，复用 CLI 登录所用的 OAuth 凭据。这仅适用于进程内导出器：useCliAuth 与 useCollector 同时为 true 时，官方说明遥测会被禁用。

写入身份需要下列 IAM 角色：Cloud Trace Agent、Monitoring Metric Writer、Logs Writer。管理员还需为目标项目启用相应 API：

gcloud services enable \
  cloudtrace.googleapis.com \
  monitoring.googleapis.com \
  logging.googleapis.com \
  --project="$OTLP_GOOGLE_CLOUD_PROJECT"

这是项目管理操作，需要执行身份具备相应权限；终端示例中的变量必须先设置。

直接导出配置

官方推荐直接导出。已准备 ADC 的配置可写为：

{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "logPrompts": false
  }
}

需要复用 CLI OAuth 时再加 useCliAuth true，并保持 useCollector false。重启后执行正常请求，在目标项目的 Logs Explorer、Metrics Explorer 和 Trace Explorer 查看数据；详细 trace 属性仍由 telemetry.traces 单独控制。

Google Cloud Monitoring 的 Dashboard Templates 提供名为 Gemini CLI Monitoring 的预配置仪表板，可作为查看日志和指标的入口。

区分客户端来源

CLI 会把集成环境放进 User-Agent 前缀与 surface 标签。官方列举：

环境	前缀	surface
普通终端	GeminiCLI	terminal
Gemini Code Assist Agent Mode	GeminiCLI-a2a-server	vscode
Zed ACP	GeminiCLI-acp-zed	zed
Xcode ACP	GeminiCLI-acp-xcode	xcode
IntelliJ IDEA ACP	GeminiCLI-acp-intellijidea	jetbrains

内部脚本可设置 GEMINI_CLI_SURFACE，把自定义名称放在 User-Agent 括号元数据的末尾：

export GEMINI_CLI_SURFACE="internal-review-tool"

该标识用于流量归类，不是授权凭据，也不替代应用、用户或服务端权限控制。Windows PowerShell 使用 $env:GEMINI_CLI_SURFACE="internal-review-tool"。