遥测配置与本地采集

设置 OpenTelemetry 日志、指标和 trace，区分启用、提示内容与详细属性。

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

Gemini CLI 内置 OpenTelemetry，可输出日志、指标和 traces。配置位于 settings.json 的 telemetry 对象，环境变量可以覆盖相应设置；遥测默认关闭。

配置与默认值

下表采用官方遥测专页列出的默认值。布尔环境变量用 true 或 1 开启。

telemetry 字段	环境变量	默认值
`enabled`	`GEMINI_TELEMETRY_ENABLED`	false
`traces`	`GEMINI_TELEMETRY_TRACES_ENABLED`	false
`target`	`GEMINI_TELEMETRY_TARGET`	local；也可选 gcp
`otlpEndpoint`	`GEMINI_TELEMETRY_OTLP_ENDPOINT`	http://localhost:4317
`otlpProtocol`	`GEMINI_TELEMETRY_OTLP_PROTOCOL`	grpc；也可选 http
`outfile`	`GEMINI_TELEMETRY_OUTFILE`	未设置
`logPrompts`	`GEMINI_TELEMETRY_LOG_PROMPTS`	true
`useCollector`	`GEMINI_TELEMETRY_USE_COLLECTOR`	false
`useCliAuth`	`GEMINI_TELEMETRY_USE_CLI_AUTH`	false，仅适用 GCP 直接导出

logPrompts 默认 true 不代表开箱即启用遥测；但开启 enabled 时，应同时明确是否需要保存提示内容。outfile 指定文件输出，会覆盖 otlpEndpoint 的输出去向。修改 telemetry 配置后重启 CLI。

本地文件示例

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "outfile": ".gemini/telemetry.log",
    "logPrompts": false,
    "traces": false
  }
}

重新启动 CLI 并进行一次正常交互，然后查看 .gemini/telemetry.log 中的日志和指标。示例主动关闭提示文本及详细 trace 属性，便于先验证事件是否正常产生。

需要将数据发送到已有 OpenTelemetry 后端时，核对 Collector 端点与 grpc/http 协议；文件仍配置在 outfile 时，不要期待数据按 otlpEndpoint 发送。

内容范围

共同属性包括 session.id、installation.id、active_approval_mode，认证时还可能包含 user.email。工具事件还列有 function_args 等字段。因此 logPrompts false 不能被当作所有遥测字段都已匿名化或已移除所有业务内容。

traces 控制含完整提示、工具输出等较大属性的详细采集，默认关闭。需要诊断时再明确启用，并按事件与指标参考确认输出内容。

常见问题

配置已修改却没有数据时，检查是否重启、enabled 是否被环境变量覆盖、outfile 是否仍生效，以及 Collector 地址与协议是否一致。Google Cloud 的认证与角色要求见云端遥测。