---
title: "Telemetry"
description: "Gemini CLI telemetry 的用途：使用和效能指標、團隊可觀測性、隱私邊界和企業環境檢查。"
verifiedAt: "2026-05-09"
---

Telemetry 用於瞭解 Gemini CLI 的使用和效能。個人使用者要知道它記錄什麼；企業使用者要確認它是否符合內部合規要求。

> [!WARNING]
> `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 裡可能包含業務程式碼、客戶資訊、路徑、金鑰線索或內部系統名稱，預設不應該把它寫入可共享日誌。

## 釋出前檢查

教程、錄屏或企業自動化上線前，至少確認：

1. telemetry 是否開啟。
2. 輸出目標是 local 還是 gcp。
3. 是否記錄 prompt。
4. 日誌檔案是否進入 `.gitignore` / `.geminiignore`。
5. GCP 專案和 IAM 是否屬於正確組織。
6. 日誌保留和訪問許可權是否符合團隊要求。

這一步要在真實任務前完成。任務跑完後再發現 prompt 被寫入共享日誌，補救成本會高很多。

## 驗收方式

啟用 telemetry 後，先跑一條低風險 prompt，再檢查目標位置是否產生 logs、metrics 或 traces。不要等到生產自動化出問題時，才發現 telemetry 根本沒寫進去或寫到了錯誤專案。

同時要檢查是否出現 `gemini_cli.tool_call`、`gemini_cli.api_request`、`gemini_cli.api_error`、token usage、tool latency 這類關鍵事件或指標。只有日誌檔案存在，不代表可觀測性已經可用。

## 接下來去哪

<Cards>
  <Card title="Terms and privacy" description="繼續核對不同認證方式下的資料和條款邊界。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/65-terms-privacy" />
  <Card title="Enterprise controls" description="企業 telemetry 應和 controls、license、Cloud project 一起管理。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/63-enterprise-controls" />
  <Card title="Cloud security" description="把日誌寫到 Cloud 時，繼續看雲安全和合規邊界。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/66-cloud-security-privacy" />
</Cards>

## 官方來源

- [Gemini CLI telemetry](https://github.com/google-gemini/gemini-cli/blob/main/docs/telemetry.md)
- [Gemini CLI enterprise](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/enterprise.md)
