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

# Telemetria

> Qual telemetria anônima de uso do produto a CLI coleta e como desativá-la.

A XBOX CLI coleta telemetria de uso limitada e anônima para ajudar a Microsoft a entender quais
comandos são usados, quão confiáveis eles são e quanto tempo levam. Você pode
[desativá-la](#opt-out). A telemetria nunca altera a saída nem o código de saída de um comando.

A Microsoft trata esses dados conforme descrito na
[Política de Privacidade da Microsoft](https://go.microsoft.com/fwlink/?LinkID=824704). O
[aviso de privacidade](https://github.com/xbox/cli/blob/v0.4.2/PRIVACY.md) do repositório abrange a coleta de dados pelo software.

## O que é coletado

Cada execução de `xbox` cria no máximo um evento, `xbox.cli.command_invocation`, com estes campos
e nada mais:

| Campo | Contém |
| - | - |
| `xbox.cli.schema_version` | A versão do esquema do evento, `3` |
| Hora | Quando o comando foi executado, arredondado para baixo até a hora |
| `service.version` | A versão da CLI |
| `os.type`, `os.version` | A família do sistema operacional, como `windows`, e somente a versão principal dele |
| `host.arch` | A arquitetura do processador: `amd64`, `arm64` ou `unknown` |
| `process.runtime.name`, `process.runtime.version` | O runtime do .NET e a versão dele |
| `xbox.cli.command` | O caminho do comando na árvore de comandos, unido por hifens, como `playfab-economy-inventory-transaction-list`; `root` para `xbox` sozinho; `unknown` quando nenhum comando foi reconhecido |
| `xbox.cli.auth_mode` | Como a CLI fez o login: `user`, um modo de entidade de serviço como `githuboidc`, ou `invalid`; nunca o locatário, o aplicativo nem a identidade |
| `xbox.cli.outcome` | `success`, `failure` ou `cancelled` |
| `process.exit.code` | O código de saída |
| `error.type` | Por que um comando falhou, de uma lista fixa: `usage`, `context`, `auth`, `not_confirmed`, `transport`, `service_rejected`, `service_error`, `local_tool`, `io`, `cancelled` ou `_OTHER`. Não é enviado em caso de sucesso. |
| `http.response.status_code` | O status da última resposta do serviço, quando houve uma |
| `xbox.cli.duration_ms` | Quanto tempo o comando levou, em milissegundos |
| `xbox.cli.options` | Os nomes das opções fornecidas, sem hifens, em ordem, como `output,verbose`; nunca os valores delas |
| `xbox.cli.context_keys` | Quais valores de contexto o comando tinha, seja de uma opção, de uma variável de ambiente ou do contexto salvo: `playfab-title-id`, `sandbox-id`, `seller-id` ou `title-id`; nunca os valores |
| `xbox.cli.ci` | `true` quando uma variável de CI conhecida, como `CI` ou `TF_BUILD`, está definida; somente se ela está definida é lido |

Um nome de comando ou de opção que a CLI não define é enviado como `unknown` ou omitido; portanto, um valor
digitado no lugar errado nunca é enviado.

### Localização aproximada

A CLI nunca envia a sua localização. No entanto, o Application Insights deriva uma localização
aproximada (país, região ou estado e cidade) do endereço IP que envia o evento e
a armazena em todos os eventos. O endereço IP em si não é mantido; ele é armazenado como `0.0.0.0`. A
localização é usada somente para entender a adoção nos diferentes mercados. [Recusar](#opt-out) interrompe toda a
telemetria, incluindo essa localização.

## O que não é coletado

A CLI não coleta valores de argumentos ou de opções, corpos de solicitações ou de respostas, IDs de título do
PlayFab, IDs de vendedor, IDs de sandbox, nomes de usuário, IDs de locatário ou de conta, tokens de acesso, caminhos de arquivo,
segredos configurados, mensagens de erro nem o nome do computador.

## Quando o evento é enviado

Quando um comando é bem-sucedido, a CLI salva o evento em disco, e uma execução posterior o envia, para que o
comando não precise aguardar a rede. Quando um comando falha, a CLI aguarda no máximo 300
milissegundos para enviar o evento dele e os eventos salvos. Em CI, onde a CLI pode não ser executada novamente, ela
envia o evento antes de sair em vez de salvá-lo. Isso pode adicionar até cerca de 5 segundos quando
o ponto de extremidade está lento, e o evento é descartado se não for enviado nesse tempo.

## Cabeçalho de versão

Separadamente da telemetria, todas as solicitações que a CLI envia com um token de acesso incluem um
cabeçalho `User-Agent: XboxDevCLI/<version>`, como `XboxDevCLI/0.1.0.9`, para que esses serviços possam
saber quais versões da CLI os chamam. Ele não contém mais nada, e recusar a telemetria não
o remove.

## Aviso na primeira execução

Na primeira vez em que a CLI coleta telemetria em um computador, ela grava este aviso em stderr, uma única vez:

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

## Recusar

### Para um único comando

Passe `--disable-telemetry`:

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

### Para a sessão atual do shell

Defina `XBOX_TELEMETRY_OPTOUT` no PowerShell:

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

No bash ou zsh:

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

Os valores `1`, `true` e `yes` desativam a telemetria, independentemente do que mais estiver configurado. Definir
`XBOX_TELEMETRY__ENABLED` como `false` também a desativa.

### Para todos os novos terminais

Defina a variável para a sua conta. No Windows, execute isto e, em seguida, reabra o terminal e o
IDE, se você usar o terminal integrado dele:

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

No Linux e no macOS, adicione a linha `export` ao arquivo de inicialização do shell, como `~/.zshrc` ou
`~/.bashrc`, da mesma forma que a [Instalação](https://docs.xbox.com/pt-BR/tools/xbox-cli/installation.md) adiciona a CLI ao `PATH`.

## Para onde a telemetria vai

Os builds de versão enviam a telemetria para um recurso do Azure Monitor Application Insights de propriedade da Microsoft,
que você não pode alterar. A CLI ignora `APPLICATIONINSIGHTS_CONNECTION_STRING`; portanto, um host que
a define para o próprio aplicativo não redireciona a telemetria da CLI.


## Related topics

- [Telemetria](https://docs.xbox.com/pt-BR/services/playfab/data-analytics/ingest-data/telemetry-overview.md)
- [Chaves de telemetria](https://docs.xbox.com/pt-BR/services/playfab/data-analytics/ingest-data/telemetry-keys-overview.md)
- [Excluir chaves de telemetria](https://docs.xbox.com/pt-BR/services/playfab/data-analytics/ingest-data/ht-telemetry-keys-delete.md)
- [Excluir chave de telemetria](https://docs.xbox.com/pt-BR/services/playfab/api-references/rest/events/play-stream-events/delete-telemetry-key.md)
- [Listar chaves de telemetria](https://docs.xbox.com/pt-BR/services/playfab/api-references/rest/events/play-stream-events/list-telemetry-keys.md)
