Variáveis de Ambiente

O Trackio usa variáveis de ambiente para configurar vários aspectos de seu comportamento, especialmente para o deploy em Hugging Face Spaces e a persistência de dados. Este guia aborda as principais variáveis de ambiente e seu uso.

Variáveis de Ambiente Principais

TRACKIO_DIR

Especifica um diretório personalizado para armazenar os dados do Trackio. Por padrão, o Trackio armazena os dados em ~/.cache/huggingface/trackio/.

export TRACKIO_DIR="/path/to/trackio/data"

Nota: Esta variável de ambiente se aplica enquanto o Trackio não estiver sendo executado em um Space com armazenamento persistente habilitado. Se o Trackio estiver sendo executado em um Space com armazenamento persistente habilitado (o que é detectado pela variável de ambiente PERSISTANT_STORAGE_ENABLED), os dados do Trackio serão armazenados em /data/trackio.

TRACKIO_SERVER_URL

URL base de um servidor Trackio auto-hospedado (http:// ou https://). Você pode incluir write_token na string de consulta (como no full_url de trackio.show()) ou manter a URL sem parâmetros e definir TRACKIO_WRITE_TOKEN em vez disso. Quando definido, trackio.init() envia as métricas para esse servidor. Equivalente a passar server_url= para trackio.init().

Prioridade: Se TRACKIO_SPACE_ID também estiver definido (ou space_id for passado no código), o Hugging Face Space é usado e TRACKIO_SERVER_URL é ignorado. A mesma regra se aplica quando ambos space_id e server_url são passados: space_id tem prioridade.

Veja Hospedar o Servidor.

export TRACKIO_SERVER_URL="http://127.0.0.1:7860"
export TRACKIO_WRITE_TOKEN="YOUR_TOKEN"

TRACKIO_WRITE_TOKEN

O write token do dashboard para um servidor Trackio auto-hospedado (mesmo valor que o parâmetro de consulta write_token na URL de acesso de escrita). Quando definido no servidor Trackio, esse valor é usado como o write token do servidor em vez de gerar um token aleatório na inicialização. Quando definido no cliente Trackio, use isso quando TRACKIO_SERVER_URL ou server_url for uma URL base sem parâmetros de consulta. O cliente envia esse token em cada solicitação (por exemplo, como o cabeçalho X-Trackio-Write-Token) para que a ingestão de métricas e os uploads sejam autenticados quando não estiverem sendo executados nos Hugging Face Spaces.

TRACKIO_FRONTEND_DIR

Caminho para um diretório de frontend estático personalizado para o Trackio. O diretório deve conter index.html.

Quando definido, o Trackio usa esse frontend para trackio.show() e para fluxos de implantação como trackio.sync() e trackio.freeze(), a menos que um argumento explícito de frontend_dir / --frontend seja passado.

export TRACKIO_FRONTEND_DIR="/path/to/my-trackio-frontend"

Se o diretório configurado for inválido, o Trackio o ignora e recorre à lógica de seleção de frontend embutida. O comportamento automático de cópia do modelo inicial só se aplica quando um argumento explícito frontend_dir / --frontend aponta para um diretório ausente ou vazio.

TRACKIO_LOGO_LIGHT_URL e TRACKIO_LOGO_DARK_URL

Personalize os logotipos exibidos no dashboard do Trackio para os temas claro e escuro. Você pode fornecer URLs para logotipos personalizados. Observe que ambas as variáveis de ambiente devem ser fornecidas; caso contrário, o padrão do Trackio será usado para qualquer variável que não for fornecida.

export TRACKIO_LOGO_LIGHT_URL="https://example.com/logo-light.png"
export TRACKIO_LOGO_DARK_URL="https://example.com/logo-dark.png"

Observação: Para Spaces remotos do Trackio, essas variáveis de ambiente são aplicadas apenas quando o Space é criado pela primeira vez via trackio.init(space_id=...). Para alterar os logotipos em um Space existente, atualize as variáveis do Space diretamente nas configurações do Space no Hugging Face.

TRACKIO_PLOT_ORDER

Controla a ordem dos gráficos e dos grupos de métricas no dashboard do Trackio. O valor deve ser uma lista de padrões de métricas separados por vírgulas que especificam a ordem desejada. Os grupos são preservados - se train/loss for especificado primeiro, todas as outras métricas train/* aparecerão juntas no grupo train, com train/loss aparecendo primeiro dentro desse grupo.

Se um padrão não corresponder a nenhuma métrica, ele é simplesmente ignorado sem causar erros.

export TRACKIO_PLOT_ORDER="train/loss,val/loss"


**Pattern Matching:**
- **Exact matches**: `train/loss` matches exactly `train/loss`
- **Group wildcards**: `train/*` matches all metrics starting with `train/`
- **Partial wildcards**: `*gpu*` matches any metric containing "gpu"

**Behavior:**
- Metrics are grouped first (e.g., all `train/*` metrics stay together)
- Within each group, metrics are ordered according to the specified patterns
- Groups appear in the order of their first matching pattern
- Unspecified metrics appear in alphabetical order after specified ones

> **Note:** For remote Trackio Spaces, this environment variable is only applied when the Space is first created via `trackio.init(space_id=...)`. To change the plot order on an existing Space, update the `TRACKIO_PLOT_ORDER` Space variable directly in the Hugging Face Space settings.

### `TRACKIO_THEME`

Sets the theme for the Trackio dashboard. Can be a built-in Gradio theme name or a theme from the Hugging Face Hub.

```bash
# Built-in themes
export TRACKIO_THEME="soft"
export TRACKIO_THEME="citrus"
export TRACKIO_THEME="monochrome"

# Themes from the Hub
export TRACKIO_THEME="gstaff/xkcd"
export TRACKIO_THEME="ParityError/Anime"

Observação: Para Spaces remotos do Trackio, esta variável de ambiente é aplicada apenas quando o Space é criado pela primeira vez via trackio.init(space_id=...). Para alterar o tema em um Space existente, atualize a variável TRACKIO_THEME do Space diretamente nas configurações do Space no Hugging Face.

TRACKIO_COLOR_PALETTE

Personaliza a paleta de cores usada para as linhas de gráfico no dashboard do Trackio. O valor deve ser uma lista de códigos de cor em hexadecimal separados por vírgulas. Essas cores serão alternadas ao plotar múltiplas execuções.

export TRACKIO_COLOR_PALETTE="#FF0000,#00FF00,#0000FF,#FFFF00,#FF00FF,#00FFFF"

Paleta padrão: #A8769B, #E89957, #3B82F6, #10B981, #EF4444, #8B5CF6, #14B8A6, #F59E0B, #EC4899, #06B6D4

TRACKIO_TABLE_TRUNCATE_LENGTH

Controla o comprimento máximo dos valores de string exibidos nas células da tabela antes de serem truncados. Quando o valor de uma célula excede esse comprimento, ele será truncado com um elemento expansível que permite visualizar o texto completo. O valor padrão é 250 caracteres.

export TRACKIO_TABLE_TRUNCATE_LENGTH="500"

TRACKIO_STORAGE_MODE

Controla como o Trackio persiste dados localmente. Valores permitidos: auto (padrão), sqlite, jsonl.

sqlite: os processos de treinamento gravam diretamente no banco de dados SQLite do projeto (comportamento histórico).
jsonl: os processos de treinamento gravam fragmentos JSONL somente de adição em TRACKIO_DIR/inbox/, um arquivo por processo; o servidor do dashboard (trackio show) os importa para o SQLite. Isso evita completamente escritores simultâneos no SQLite, o que torna o Trackio seguro em sistemas de arquivos de rede (NFS, Lustre, FSx, GPFS, WekaFS, CephFS, …) onde as semânticas de bloqueio e mmap do SQLite são pouco confiáveis.
auto: seleciona jsonl automaticamente quando TRACKIO_DIR é detectado em um sistema de arquivos de rede (somente Linux), caso contrário, sqlite.

export TRACKIO_STORAGE_MODE="jsonl"

TRACKIO_INBOX_POLL_INTERVAL

Com que frequência (em segundos) o servidor do dashboard e os Trackio Spaces verificam novos fragmentos JSONL para importar, tanto do diretório local de inbox quanto do inbox do Hugging Face Bucket. O valor padrão é 15; valores abaixo de 5 são limitados a 5.

export TRACKIO_INBOX_POLL_INTERVAL="30"

TRACKIO_SQLITE_* (avançado)

Substitua os PRAGMAs que o Trackio define em suas conexões SQLite. Eles são principalmente úteis em sistemas de arquivos incomuns; valores inválidos são ignorados.

TRACKIO_SQLITE_JOURNAL_MODE: um de wal, delete, truncate, persist, memory, off. O padrão é wal localmente e delete nos Spaces.
TRACKIO_SQLITE_MMAP_SIZE: tamanho da E/S mapeada em memória, em bytes. O valor padrão é 0 (desativado) em todos os casos, pois as leituras mapeadas em memória são o gatilho direto para falhas SIGBUS em sistemas de arquivos de rede e trazem poucos benefícios para a carga de trabalho do Trackio.
TRACKIO_SQLITE_SYNCHRONOUS: um dos valores off, normal, full, extra. O padrão é normal.
TRACKIO_SQLITE_LOCKING_MODE: um de normal, exclusive. O padrão é exclusive nos Spaces e normal em outros ambientes.
TRACKIO_SQLITE_TEMP_STORE: um de default, file, memory. O padrão é memory.

Configuração de cluster recomendada: se o seu diretório home ou de cache estiver em um sistema de arquivos compartilhado (/fsx, Lustre, NFS, GPFS, WekaFS, …), aponte TRACKIO_DIR para um disco local do nó (por exemplo, /tmp ou $SLURM_TMPDIR) ou dependa de TRACKIO_STORAGE_MODE=auto, que detecta sistemas de arquivos de rede e alterna para o registro de fragmentos JSONL. Se você precisar gravar SQLite diretamente em um sistema de arquivos compartilhado, defina:

export TRACKIO_SQLITE_JOURNAL_MODE="delete"
export TRACKIO_SQLITE_MMAP_SIZE="0"

TRACKIO_WEBHOOK_URL

Define uma URL global de webhook para alertas. Quando definida, cada chamada para trackio.alert() enviará o payload do alerta via POST para esta URL. Suporta nativamente URLs de webhook do Slack e do Discord (os payloads são formatados automaticamente). Pode ser sobrescrita por alerta ou por execução por meio do parâmetro webhook_url.

export TRACKIO_WEBHOOK_URL="https://hooks.slack.com/services/T.../B.../xxx"

Consulte o Guia de alertas para mais detalhes.

TRACKIO_WEBHOOK_MIN_LEVEL

Define o nível mínimo de alerta que deve ser enviado para webhooks. Alertas abaixo desse nível ainda são exibidos no terminal, armazenados no banco de dados e mostrados no painel, mas não são enviados para os destinos de webhook.

Valores permitidos: info, warn, error.

export TRACKIO_WEBHOOK_MIN_LEVEL="warn"

Com warn, apenas alertas WARN e ERROR são enviados para as URLs de webhook.

TRACKIO_CAPTURE_CONSOLE

Quando definido como 1 ou true, o Trackio captura tudo que é escrito no stdout e stderr durante uma execução e exibe isso na página da execução no dashboard. Equivale a passar capture_console=True para trackio.init(); um argumento explícito de capture_console tem precedência.

export TRACKIO_CAPTURE_CONSOLE=1

Veja Capturando a saída do console e o comando de inicialização para mais detalhes.

TRACKIO_HANDLE_SIGTERM

Quando definido como 1 ou true, o trackio.init() instala um manipulador de SIGTERM que converte o sinal em uma saída normal, de modo que a execução é finalizada e suas últimas métricas e a saída do console são salvas quando o processo é interrompido por um limite de tempo do Slurm, docker stop ou uma evicção do Kubernetes. O código de saída permanece 143. O manipulador é instalado apenas a partir da thread principal e somente quando nenhum outro manipulador de SIGTERM estiver definido. Ele está desativado por padrão porque altera como o processo inteiro responde a SIGTERM: por exemplo, o processo aguarda as threads não daemon antes de sair, e frameworks que encadeiam manipuladores existentes (como o requeue automático do Slurm no PyTorch Lightning) sairão em vez de ignorar o sinal.

export TRACKIO_HANDLE_SIGTERM=1

TRACKIO_BUCKET_ID

O ID do Bucket do Hugging Face (por exemplo, username/bucketname) usado para persistir dados do Trackio ao executar em um Hugging Face Space. Normalmente, isso é definido automaticamente no Space quando ele é criado via trackio.init(space_id=...) ou trackio.sync(...); um bucket é gerado automaticamente a partir do ID do Space, a menos que um bucket_id explícito seja fornecido.

export TRACKIO_BUCKET_ID="username/my-trackio-bucket"

TRACKIO_DATASET_ID (obsoleto)

Descontinuado: A persistência de dados do Trackio em um Dataset do Hugging Face (dataset_id / TRACKIO_DATASET_ID) está descontinuada e será removida em uma versão futura do Trackio. Use um Bucket do Hugging Face em vez disso (bucket_id / TRACKIO_BUCKET_ID).

O ID do Dataset do Hugging Face (por exemplo, username/datasetname) para o qual um Space do Trackio sincroniza seus dados por meio de um agendador de commits em segundo plano. Quando definido em um Space, o Trackio emite um aviso de depreciação e, por enquanto, continua sincronizando com o Dataset.

export TRACKIO_DATASET_ID="username/my-trackio-dataset"

HF_TOKEN

Seu token de autenticação do Hugging Face. Necessário para criar Spaces e Buckets no Hugging Face. Defina-o localmente ao implantar no Spaces a partir da sua máquina. Deve ter permissões de write para o namespace no qual você está implantando o dashboard do Trackio.

export HF_TOKEN="hf_xxxxxxxxxxxxx"

Variáveis de Ambiente do Gradio

Como o Trackio é construído sobre o Gradio, você pode usar variáveis de ambiente usadas pelo Gradio para controlar o comportamento do Trackio. Aqui estão alguns exemplos:

GRADIO_SERVER_PORT

Especifica a porta na qual o dashboard do Tradio será iniciado. O padrão é 7860

export GRADIO_SERVER_PORT=8000

GRADIO_SERVER_NAME

Define o nome do host para o servidor do painel do Trackio. Para tornar o painel acessível a partir de qualquer endereço IP, defina este valor como "0.0.0.0"

export GRADIO_SERVER_NAME="0.0.0.0"

GRADIO_MCP_SERVER

Ativa a funcionalidade de servidor MCP (Model Context Protocol) no Trackio. Quando ativado, o dashboard do Trackio será configurado como um servidor MCP e certas funções serão expostas como ferramentas MCP que podem ser usadas por LLMs (por exemplo, para ler as métricas registradas).

export GRADIO_MCP_SERVER="True"

Veja esta lista mais abrangente de variáveis de ambiente usadas pelo Gradio.

Update on GitHub