Telemetry
Gemini CLI telemetry 的用途：使用和效能指標、團隊可觀測性、隱私邊界和企業環境檢查。
Telemetry 用於瞭解 Gemini CLI 的使用和效能。個人使用者要知道它記錄什麼；企業使用者要確認它是否符合內部合規要求。
logPrompts 是高風險開關。prompt 可能包含原始碼、路徑、客戶資訊、賬號線索或內部系統名，公開演示和客戶專案預設不要開啟。
Gemini CLI 的 telemetry 基於 OpenTelemetry，可以輸出 logs、metrics 和 traces。預設 telemetry 是關閉的；是否啟用、輸出到哪裡、是否記錄 prompt，都由 .gemini/settings.json 或環境變數控制。
需要確認
- 採集哪些指標。
- 是否包含專案路徑或命令資訊。
- 是否能關閉或統一配置。
- 團隊是否需要集中觀測。
- 是否符合隱私和合規要求。
常見配置項
重點看這些配置：
telemetry.enabled/GEMINI_TELEMETRY_ENABLED：是否啟用。telemetry.traces/GEMINI_TELEMETRY_TRACES_ENABLED：是否啟用詳細 trace。telemetry.target/GEMINI_TELEMETRY_TARGET：輸出到local還是gcp。telemetry.outfile/GEMINI_TELEMETRY_OUTFILE：本地輸出檔案。telemetry.logPrompts/GEMINI_TELEMETRY_LOG_PROMPTS：是否記錄 prompt。GEMINI_CLI_SURFACE：給指令碼或內部工具打標，方便區分來源。
官方 OpenTelemetry 頁面還列出 otlpEndpoint 和 otlpProtocol，預設端點類似 http://localhost:4317，協議可選 grpc 或 http。接本地 collector、Jaeger 或企業 OTEL collector 時，要把 endpoint、協議和網路可達性一起驗收。
本地與雲端
本地除錯可以輸出到 .gemini/telemetry.log，適合排查工具呼叫、延遲和失敗原因。企業場景可以匯出到 Google Cloud Trace、Cloud Monitoring 和 Cloud Logging，但需要專案、認證、IAM role 和 API 都配置正確。
如果使用 Google Cloud telemetry，至少要確認 Cloud Trace Agent、Monitoring Metric Writer、Logs Writer 等許可權，以及相關 Google Cloud API 是否啟用。
| 輸出目標 | 適合場景 | 風險 |
|---|---|---|
| local file | 本機除錯、協議排錯 | 本地路徑和 prompt 洩露 |
| GCP logging / monitoring | 企業可觀測和審計 | IAM、專案歸屬、保留策略 |
| disabled | 預設個人使用 | 診斷資訊不足 |
隱私建議
公開演示、錄屏、客戶專案和企業環境，都應先確認 telemetry 設定，避免把路徑、專案名或操作資訊暴露出去。
特別注意 logPrompts。如果 prompt 裡可能包含業務程式碼、客戶資訊、路徑、金鑰線索或內部系統名稱，預設不應該把它寫入可共享日誌。
釋出前檢查
教程、錄屏或企業自動化上線前，至少確認：
- telemetry 是否開啟。
- 輸出目標是 local 還是 gcp。
- 是否記錄 prompt。
- 日誌檔案是否進入
.gitignore/.geminiignore。 - GCP 專案和 IAM 是否屬於正確組織。
- 日誌保留和訪問許可權是否符合團隊要求。
這一步要在真實任務前完成。任務跑完後再發現 prompt 被寫入共享日誌，補救成本會高很多。
驗收方式
啟用 telemetry 後，先跑一條低風險 prompt，再檢查目標位置是否產生 logs、metrics 或 traces。不要等到生產自動化出問題時，才發現 telemetry 根本沒寫進去或寫到了錯誤專案。
同時要檢查是否出現 gemini_cli.tool_call、gemini_cli.api_request、gemini_cli.api_error、token usage、tool latency 這類關鍵事件或指標。只有日誌檔案存在，不代表可觀測性已經可用。
接下來去哪
Terms and privacy
繼續核對不同認證方式下的資料和條款邊界。
Enterprise controls
企業 telemetry 應和 controls、license、Cloud project 一起管理。
Cloud security
把日誌寫到 Cloud 時，繼續看雲安全和合規邊界。