遥测事件、指标与 traces

日志记录具体事件，指标汇总随时间变化的数量与耗时，traces 关联一次操作中的步骤。先按问题选择数据，再决定是否开启详细属性，配置入口见遥测设置。

关联一次会话和请求

官方列出的共同属性包括 session.id、installation.id、active_approval_mode，以及认证时的 user.email。请求和工具事件常带 prompt_id；代理事件带 agent_id/agent_name。使用这些字段关联事件，避免仅按接近的时间戳判断因果。

主要日志事件

事件	可回答的问题与关键属性
gemini_cli.config	启动使用了哪些配置：model、sandbox_enabled、approval_mode、MCP/扩展清单、认证方式
gemini_cli.user_prompt	何时提交提示：prompt_id、prompt_length；logPrompts false 时排除 prompt 字符串
gemini_cli.tool_call	调用哪个工具、是否成功：function_name、function_args、duration_ms、success、decision、tool_type
gemini_cli.tool_output_truncated	工具结果是否被截断：原长度、截断长度、threshold、lines
gemini_cli.file_operation	文件创建、读取或更新：operation、tool_name、语言和 MIME 类型
gemini_cli.api_request	请求模型和角色：model、prompt_id、role，可有 request_text
gemini_cli.api_response	返回状态、耗时和 token：status_code、duration_ms、各类 token、finish_reasons
gemini_cli.api_error	请求失败：error.message、model_name、duration、status_code、error_type
gemini_cli.model_routing	路由决定和失败：decision_model、decision_source、routing_latency_ms、failed
gemini_cli.chat_compression	压缩前后 token 数量
gemini_cli.agent.start、gemini_cli.agent.finish	代理开始与结束，完成事件含 duration_ms、turn_count、terminate_reason
gemini_cli.hook_call	Hook 名称、类型、耗时与执行成功状态

工具 decision 包括 accept、reject、auto_accept、modify；tool_type 区分 native 与 mcp。自动批准不等于工具执行成功，应同时检查 success 和 error。

其他诊断事件

• 审批与计划：approval_mode_switch 记录 from_mode/to_mode；approval_mode_duration 记录 mode/duration_ms；plan_execution 记录执行计划时的 approval_mode。
• 模型与命令：gemini_cli.slash_command、gemini_cli.slash_command.model、gemini_cli.flash_fallback。
• 流式错误：gemini_cli.chat.invalid_chunk、gemini_cli.chat.content_retry、gemini_cli.chat.content_retry_failure，区分收到坏块、尝试重试和所有重试失败。
• 工具回退与恢复：gemini_cli.ripgrep_fallback、gemini_cli.web_fetch_fallback_attempt、gemini_cli.agent.recovery_attempt。
• 扩展生命周期：gemini_cli.extension_install、extension_uninstall、extension_enable、extension_disable；后三个名称同样带 gemini_cli. 前缀。
• 编辑与回退：gemini_cli.edit_strategy、gemini_cli.edit_correction、gemini_cli.rewind。
• 环境与性能：gemini_cli.ide_connection、gemini_cli.keychain.availability、gemini_cli.startup_stats，以及终端 kitty_sequence_overflow。
• 其他内容处理：gemini_cli.malformed_json_response、gemini_cli.tool_output_masking、gemini_cli.conseca.verdict、gemini_cli.conversation_finished。

字段名并非处处一致。例如工具耗时为 duration_ms，API error 事件列 duration，conversation_finished 使用 approvalMode/turnCount。采集查询应按事件定义书写，不批量假设同一命名形式。

数量、耗时与 token 指标

指标	含义或维度
gemini_cli.session.count	每次 CLI 启动加一
gemini_cli.onboarding.start、gemini_cli.onboarding.success	认证入门开始/成功
gemini_cli.tool.call.count	工具调用数量，可按名称、成功、批准决定和工具类型区分
gemini_cli.tool.call.latency	工具耗时，毫秒
gemini_cli.api.request.count	API 请求数，按模型与状态等区分
gemini_cli.api.request.latency	API 耗时，毫秒
gemini_cli.token.usage	按 model 与 type 区分 input、output、thought、cache、tool
gemini_cli.file.operation.count、gemini_cli.lines.changed	文件操作、增删行
gemini_cli.model_routing.latency、gemini_cli.model_routing.failure.count	路由延迟与失败
gemini_cli.agent.run.count、gemini_cli.agent.duration、gemini_cli.agent.turns	代理执行次数、持续时间、轮数
gemini_cli.plan.execution.count	计划执行数量

另有压缩、无效 chunk、重试与重试失败计数；gemini_cli.slash_command.model.call_count 统计模型选择次数。不要把“选过几次模型”当成“向模型发了几次 API 请求”。

性能指标

gemini_cli.startup.duration 按 phase 区分启动耗时；gemini_cli.memory.usage 区分 heap_used、heap_total、external 和 rss；gemini_cli.cpu.usage 记录 CPU 使用百分比。

gemini_cli.tool.queue.depth 表示工具队列深度，gemini_cli.tool.execution.breakdown 按 validation、preparation、execution、result_processing 区分工具阶段。终端闪烁另有 gemini_cli.ui.flicker.count。

OpenTelemetry GenAI 标准指标还包括 gen_ai.client.token.usage 与 gen_ai.client.operation.duration；后者使用秒，与上述 CLI API/tool latency 的毫秒不同。

详细 traces

telemetry.traces 默认 false。启用后可捕获包含完整提示、工具输出等较大属性的详细信息；不要只为查看调用数量就默认打开。

标准 span 属性可包含 gen_ai.operation.name、gen_ai.request.model、gen_ai.response.model、gen_ai.tool.name、gen_ai.tool.call_id、gen_ai.conversation.id，以及输入输出消息、工具定义、token 和系统指令。gen_ai.client.inference.operation.details 事件也列出输入输出、采样参数和服务地址等详细字段。

导出成功只是数据到达后端；分析时仍需核对字段、单位和当前 CLI 版本，不能将某个事件缺失直接认定为对应功能从未运行。