> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 遙測

> CLI 收集哪些匿名產品使用遙測，以及如何將其關閉。

XBOX CLI 會收集有限的匿名使用遙測，以協助 Microsoft 了解哪些命令被使用、它們的可靠程度，以及它們所需的時間。您可以[將其關閉](#opt-out)。遙測絕不會變更命令的輸出或結束代碼。

Microsoft 會依照 [Microsoft 隱私權聲明](https://go.microsoft.com/fwlink/?LinkID=824704)中的說明處理此資料。存放庫的[隱私權注意事項](https://github.com/xbox/cli/blob/v0.4.2/PRIVACY.md)涵蓋軟體的資料收集。

## 收集的內容

每次執行 `xbox` 最多會建立一個事件 `xbox.cli.command_invocation`，只包含下列欄位，不含其他任何內容：

| 欄位 | 內容 |
| - | - |
| `xbox.cli.schema_version` | 事件的結構描述版本，`3` |
| 時間 | 命令執行的時間，無條件捨去至整點 |
| `service.version` | CLI 版本 |
| `os.type`、`os.version` | 作業系統系列 (例如 `windows`)，以及僅限其主要版本 |
| `host.arch` | 處理器架構：`amd64`、`arm64` 或 `unknown` |
| `process.runtime.name`、`process.runtime.version` | .NET 執行階段及其版本 |
| `xbox.cli.command` | 命令在命令樹狀結構中的路徑，以連字號連接，例如 `playfab-economy-inventory-transaction-list`；單獨執行 `xbox` 時為 `root`；無法辨識任何命令時為 `unknown` |
| `xbox.cli.auth_mode` | CLI 的登入方式：`user`、服務主體模式 (例如 `githuboidc`) 或 `invalid`；絕不包含租用戶、應用程式或身分識別 |
| `xbox.cli.outcome` | `success`、`failure` 或 `cancelled` |
| `process.exit.code` | 結束代碼 |
| `error.type` | 命令失敗的原因，來自固定清單：`usage`、`context`、`auth`、`not_confirmed`、`transport`、`service_rejected`、`service_error`、`local_tool`、`io`、`cancelled` 或 `_OTHER`。成功時不會傳送。 |
| `http.response.status_code` | 最後一個服務回應的狀態 (如果有的話) |
| `xbox.cli.duration_ms` | 命令所花費的時間，以毫秒為單位 |
| `xbox.cli.options` | 所提供選項的名稱，不含破折號並經過排序，例如 `output,verbose`；絕不包含其值 |
| `xbox.cli.context_keys` | 命令具有哪些內容值 (無論是來自選項、環境變數或已儲存的內容)：`playfab-title-id`、`sandbox-id`、`seller-id` 或 `title-id`；絕不包含其值 |
| `xbox.cli.ci` | 設定了常見的 CI 變數 (例如 `CI` 或 `TF_BUILD`) 時為 `true`；只會讀取是否已設定 |

CLI 未定義的命令或選項名稱會以 `unknown` 傳送或予以省略，因此輸入在錯誤位置的值絕不會被傳送。

### 大概位置

CLI 絕不會傳送您的位置。不過，Application Insights 會從傳送事件的 IP 位址推導出大概位置 (國家/地區、區域或州，以及城市)，並將其儲存在每個事件上。IP 位址本身不會保留；它會儲存為 `0.0.0.0`。此位置僅用於了解各市場的採用情況。[選擇退出](#opt-out)會停止所有遙測，包括此位置。

## 不會收集的內容

CLI 不會收集引數或選項值、要求或回應本文、PlayFab 遊戲 ID、賣方 ID、沙箱 ID、使用者名稱、租用戶或帳戶 ID、存取權杖、檔案路徑、設定的祕密、錯誤訊息或電腦名稱。

## 事件的傳送時機

當命令成功時，CLI 會將事件儲存在磁碟上，並由之後的執行傳送，因此命令不需要等候網路。當命令失敗時，CLI 最多會等候 300 毫秒，以傳送其事件和任何已儲存的事件。在 CI 中，由於 CLI 可能不會再次執行，它會在結束之前傳送事件，而不是將其儲存。當端點速度緩慢時，這可能會增加最多約 5 秒，而如果事件未在該時間內傳送，就會被捨棄。

## 版本標頭

與遙測分開，CLI 使用存取權杖傳送的每個要求都會帶有 `User-Agent: XboxDevCLI/<version>` 標頭 (例如 `XboxDevCLI/0.1.0.9`)，讓這些服務可以分辨哪些 CLI 版本在呼叫它們。此標頭不包含其他任何內容，而選擇退出遙測並不會將其移除。

## 首次執行揭露

CLI 第一次在電腦上收集遙測時，會將此通知寫入 stderr 一次：

```text theme={null}
TELEMETRY
  XBOX CLI collects anonymous usage telemetry.
  Learn more or opt out: https://go.xbox/cli/telemetry
```

## 選擇退出

### 針對單一命令

傳遞 `--disable-telemetry`：

```powershell theme={null}
xbox --disable-telemetry auth status
```

### 針對目前的殼層工作階段

在 PowerShell 中設定 `XBOX_TELEMETRY_OPTOUT`：

```powershell theme={null}
$env:XBOX_TELEMETRY_OPTOUT = "1"
```

在 bash 或 zsh 上：

```bash theme={null}
export XBOX_TELEMETRY_OPTOUT=1
```

值 `1`、`true` 和 `yes` 會關閉遙測，無論其他設定為何。將 `XBOX_TELEMETRY__ENABLED` 設定為 `false` 也會將其關閉。

### 針對每個新的終端機

為您的帳戶設定變數。在 Windows 上，請執行下列命令，然後重新開啟您的終端機，如果您使用 IDE 的整合式終端機，也請重新開啟 IDE：

```powershell theme={null}
[Environment]::SetEnvironmentVariable("XBOX_TELEMETRY_OPTOUT", "1", "User")
```

在 Linux 和 macOS 上，將 `export` 行新增至殼層的啟動檔案 (例如 `~/.zshrc` 或 `~/.bashrc`)，方式與[安裝](https://docs.xbox.com/zh-TW/tools/xbox-cli/installation.md)將 CLI 新增至 `PATH` 相同。

## 遙測的傳送目的地

發行組建會將遙測傳送至 Microsoft 擁有的 Azure Monitor Application Insights 資源，您無法變更此資源。CLI 會忽略 `APPLICATIONINSIGHTS_CONNECTION_STRING`，因此為自己的應用程式設定此變數的主機，不會重新導向 CLI 的遙測。


## Related topics

- [遙測](https://docs.xbox.com/zh-TW/services/playfab/data-analytics/ingest-data/telemetry-overview.md)
- [遙測金鑰](https://docs.xbox.com/zh-TW/services/playfab/data-analytics/ingest-data/telemetry-keys-overview.md)
- [刪除遙測金鑰](https://docs.xbox.com/zh-TW/services/playfab/data-analytics/ingest-data/ht-telemetry-keys-delete.md)
- [列出遙測金鑰](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/events/play-stream-events/list-telemetry-keys.md)
- [取得遙測金鑰](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/events/play-stream-events/get-telemetry-key.md)
