# Telemetria

A partir da versão 1.7.0, o pacote Python `hf_xet` e o crate Rust `hf-xet` enviam um relatório curto para o Hub após cada upload e download. Usamos esses relatórios para ver com que frequência as transferências falham e qual é a velocidade delas entre as versões do `hf_xet`, sistemas operacionais e redes, para que possamos encontrar e corrigir problemas.

Git Xet 0.2.1 e versões anteriores não enviam telemetria.

## O que é coletado

Cada relatório descreve uma transferência. O envio de vários arquivos em um único commit é uma transferência, assim como o download de vários arquivos de uma vez.

| Dados | Detalhes |
|---|---|
| Tipo e resultado da transferência | Upload ou download, e se ele teve sucesso, falhou ou foi cancelado. Para falhas, uma categoria geral de erro, como `network`, `timeout` ou `server_error`. |
| Tempo | Quanto tempo a transferência levou. Para uploads, também o tempo gasto em fatiar e enviar os dados e o tempo gasto em finalizar o commit. |
| Tamanho | Número de arquivos, tamanho total dos arquivos e número de bytes enviados pela rede. |
| Deduplicação | Para uploads, a quantidade de dados que já estava armazenada no Hub e foi ignorada, a quantidade de dados novos e o quão bem os novos dados foram compactados. |
| Caminho de upload | A partir da versão 1.8.0 do `hf_xet`, para uploads, quantos blocos foram enviados [diretamente para o S3](./using-xet-storage#uploading-behind-a-proxy-or-firewall) e quantos através do serviço de armazenamento Xet, com seu tamanho e tempo de upload. Além disso, quantos uploads diretos caíram de volta para o serviço de armazenamento Xet, e quantos desses ocorreram porque o S3 não pôde ser alcançado. |
| Velocidade | Throughput médio e o maior número de solicitações paralelas usado. |
| Cliente | versão do `hf_xet`, sistema operacional, arquitetura da CPU, número de CPUs e a string do user agent. Este é o mesmo user agent que o `huggingface_hub` envia com cada solicitação ao Hub, contendo o nome e a versão da biblioteca chamadora (como `transformers`) e as versões de `huggingface_hub`, Python e PyTorch. |
| IDs | Um ID aleatório para a transferência, um ID aleatório para a sessão `hf_xet` e o nome do host do servidor de armazenamento Xet que processou a transferência. |

Os relatórios não incluem nomes de arquivos, caminhos de arquivos, conteúdos de arquivos, hashes de arquivos, nomes de repositórios ou seu nome de usuário.

Os relatórios são enviados ao servidor de armazenamento Xet com o mesmo token de acesso da transferência. Quando o servidor armazena um relatório, ele adiciona seu endereço IP, a conta do Hub à qual o token pertence (ou "anônimo" se você não estiver conectado), o repositório para o qual o token foi emitido e se o token permite acesso de leitura ou gravação.

## Quando os relatórios são enviados

`hf_xet` envia um relatório quando um upload ou download termina, independentemente de ter tido sucesso ou não. Uma transferência que dura mais de 5 minutos também envia um relatório de progresso a cada 5 minutos até que termine.

Os relatórios têm cerca de 1 KB. Eles são enviados junto com a transferência e não a deixam mais lenta. Se um relatório não puder ser enviado, ele é descartado e não há nova tentativa. Quando uma transferência é concluída, o `hf_xet` aguarda até 2 segundos para que o último relatório seja enviado, para que ele não seja perdido caso seu programa encerre imediatamente.

## Optar por não participar

A telemetria está ativada por padrão. Para desativá-la, defina `HF_HUB_DISABLE_TELEMETRY=1`:

```bash
export HF_HUB_DISABLE_TELEMETRY=1
```

Esta é a mesma variável que desativa a telemetria no `huggingface_hub` e nas outras bibliotecas Python da Hugging Face. Consulte [`HF_HUB_DISABLE_TELEMETRY`](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubdisabletelemetry) na documentação do `huggingface_hub`.

`hf_xet` também desativa a telemetria quando `DO_NOT_TRACK`, `DISABLE_TELEMETRY`, `HF_HUB_OFFLINE` ou `TRANSFORMERS_OFFLINE` é definido como `1`, `true`, `yes` ou `on`.

Para desativar a telemetria apenas para `hf_xet`, defina `HF_XET_TELEMETRY_ENABLED=0`.

| Variável de Ambiente | Padrão | Descrição |
|---|---|---|
| `HF_HUB_DISABLE_TELEMETRY` | unset | Defina como `1` para desativar a telemetria no `hf_xet` e nas outras bibliotecas Python do Hugging Face. |
| `HF_XET_TELEMETRY_ENABLED` | `true` | Defina como `0` para desativar apenas a telemetria do `hf_xet`. Definir como `1` não substitui as variáveis de opt-out acima. |
| `HF_XET_TELEMETRY_HEARTBEAT_AFTER` | `300s` | O tempo de duração de uma transferência antes de começar a enviar relatórios de progresso. `0` desativa os relatórios de progresso. |
| `HF_XET_TELEMETRY_HEARTBEAT_INTERVAL` | `300s` | Tempo entre os relatórios de progresso. |
| `HF_XET_TELEMETRY_FINAL_FLUSH_TIMEOUT` | `2s` | Tempo que o `hf_xet` aguarda pelo último relatório após a conclusão de uma transferência. `0` significa que ele não aguarda. |