Telemetry
Gemini CLI telemetry 的用途：使用和效能指標、團隊可觀測性、隱私邊界和企業環境檢查。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| Telemetry | 遙測 | 收集使用資料用於觀察。 |
| 採集範圍 | scope | 採什麼、不採什麼。 |
| 隱私 | privacy | 不採集敏感個人資料。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你配好 Gemini CLI 的遙測（採集範圍、隱私）。
你是 Gemini CLI 遙測設定顧問。
【角色】
Gemini CLI 遙測設定顧問，按最小夠用、安全合規優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 想透過遙測瞭解什麼：___
- 團隊規模：___
- 隱私和合規要求：___
- 現有監控堆疊：___
- 經驗水平：___
【工作流程】
1. 確定該採集的指標
2. 控制採集範圍避免過度
3. 處理隱私合規
4. 對接監控堆疊
5. 給驗證
【輸出規範】
▌一、該採集的指標
▌二、採集範圍控制
▌三、隱私合規
▌四、對接 + 驗證
【硬約束】
- 只採必要的，不過度收集
- 不採集隱私資料，合規優先
- 採集可關閉、可審查
- 不要替我臆測情況或編造不存在的設定，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述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 時，繼續看雲安全和合規邊界。