> ## 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
```

### 针对当前 shell 会话

在 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` 行添加到 shell 的启动文件(例如 `~/.zshrc` 或
`~/.bashrc`)中,方法与[安装](https://docs.xbox.com/zh-CN/tools/xbox-cli/installation.md)将 CLI 添加到 `PATH` 的方法相同。

## 遥测数据的去向

发布版本会将遥测数据发送到 Microsoft 拥有的 Azure Monitor Application Insights 资源,你无法更改该资源。CLI 会忽略 `APPLICATIONINSIGHTS_CONNECTION_STRING`,因此为自己的应用程序设置该变量的主机不会重定向 CLI 的遥测数据。


## Related topics

- [遥测](https://docs.xbox.com/zh-CN/services/playfab/data-analytics/ingest-data/telemetry-overview.md)
- [遥测密钥](https://docs.xbox.com/zh-CN/services/playfab/data-analytics/ingest-data/telemetry-keys-overview.md)
- [删除遥测密钥](https://docs.xbox.com/zh-CN/services/playfab/data-analytics/ingest-data/ht-telemetry-keys-delete.md)
- [列出遥测密钥](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/events/play-stream-events/list-telemetry-keys.md)
- [获取遥测密钥](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/events/play-stream-events/get-telemetry-key.md)
