Variables d'environnement

Trackio utilise des variables d’environnement pour configurer divers aspects de son comportement, notamment pour le déploiement sur Hugging Face Spaces et la persistance des données. Ce guide présente les principales variables d’environnement et leur utilisation.

Variables d'environnement principales

TRACKIO_DIR

Spécifie un répertoire personnalisé pour le stockage des données Trackio. Par défaut, Trackio stocke les données dans ~/.cache/huggingface/trackio/.

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

Note : Cette variable d’environnement s’applique tant que Trackio ne fonctionne pas dans un Space avec le stockage persistant activé. Si Trackio fonctionne dans un Space avec le stockage persistant activé (ce qui est détecté par la variable d’environnement PERSISTANT_STORAGE_ENABLED), les données Trackio seront stockées dans /data/trackio.

TRACKIO_SERVER_URL

URL de base d’un serveur Trackio auto-hébergé (http:// ou https://). Vous pouvez inclure write_token dans la chaîne de requête (comme dans le full_url de trackio.show()), ou conserver l’URL brute et définir TRACKIO_WRITE_TOKEN à la place. Lorsqu’il est défini, trackio.init() envoie les métriques à ce serveur. Équivaut à passer server_url= à trackio.init().

Précédence : si TRACKIO_SPACE_ID est également défini (ou si space_id est passé dans le code), le Space Hugging Face est utilisé et TRACKIO_SERVER_URL est ignoré. Même règle lorsque space_id et server_url sont tous les deux passés : space_id l’emporte.

Voir Héberger le serveur vous-même.

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

TRACKIO_WRITE_TOKEN

Le jeton d’écriture du tableau de bord pour un serveur Trackio auto-hébergé (même valeur que le paramètre de requête write_token dans l’URL d’accès en écriture). Lorsqu’il est défini sur le serveur Trackio, cette valeur est utilisée comme jeton d’écriture du serveur au lieu de générer un jeton aléatoire au démarrage. Lorsqu’il est défini sur le client Trackio, utilisez-le lorsque TRACKIO_SERVER_URL ou server_url est une URL de base sans paramètres de requête. Le client envoie ce jeton à chaque requête (par exemple en tant qu’en-tête X-Trackio-Write-Token) afin que l’ingestion des métriques et les téléversements soient authentifiés lorsque l’exécution ne se fait pas sur Hugging Face Spaces.

TRACKIO_FRONTEND_DIR

Chemin vers un répertoire de frontend statique personnalisé pour Trackio. Le répertoire doit contenir index.html.

Lorsqu’il est défini, Trackio utilise cette interface pour trackio.show() et pour les flux de déploiement tels que trackio.sync() et trackio.freeze(), à moins qu’un argument explicite frontend_dir / --frontend ne soit transmis.

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

Si le répertoire configuré est invalide, Trackio l’ignore et revient à la logique de sélection du frontend intégrée. Le comportement de copie automatique du modèle de démarrage ne s’applique que lorsque l’argument explicite frontend_dir / --frontend pointe vers un répertoire manquant ou vide.

TRACKIO_LOGO_LIGHT_URL et TRACKIO_LOGO_DARK_URL

Personnalisez les logos affichés dans le tableau de bord Trackio pour les thèmes clair et sombre. Vous pouvez fournir des URL vers des logos personnalisés. Notez que les deux variables d’environnement doivent être fournies ; sinon, la valeur par défaut de Trackio sera utilisée pour toute variable non fournie.

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

Remarque : Pour les Spaces Trackio distants, ces variables d’environnement ne sont appliquées que lors de la première création du Space via trackio.init(space_id=...). Pour modifier les logos d’un Space existant, mettez à jour les variables du Space directement dans les paramètres du Space Hugging Face.

TRACKIO_PLOT_ORDER

Contrôle l'ordre des graphiques et des groupes de métriques dans le tableau de bord Trackio. La valeur doit être une liste de motifs de métriques séparés par des virgules qui spécifient l'ordre souhaité. Les groupes sont préservés - si train/loss est spécifié en premier, toutes les autres métriques train/* apparaîtront ensemble dans le groupe train, avec train/loss apparaissant en premier dans ce groupe.

Si un motif ne correspond à aucune métrique, il est simplement ignoré sans provoquer d’erreurs.

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"

Remarque : Pour les Spaces Trackio distants, cette variable d’environnement n’est appliquée que lors de la première création du Space via trackio.init(space_id=...). Pour modifier le thème d’un Space existant, mettez à jour la variable TRACKIO_THEME du Space directement dans les paramètres du Space Hugging Face.

TRACKIO_COLOR_PALETTE

Personnalise la palette de couleurs utilisée pour les lignes de tracé dans le tableau de bord Trackio. La valeur doit être une liste de codes couleur hexadécimaux séparés par des virgules. Ces couleurs seront utilisées de manière cyclique lors de la visualisation de plusieurs exécutions.

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

Palette par défaut : #A8769B, #E89957, #3B82F6, #10B981, #EF4444, #8B5CF6, #14B8A6, #F59E0B, #EC4899, #06B6D4

TRACKIO_TABLE_TRUNCATE_LENGTH

Contrôle la longueur maximale des valeurs de chaîne affichées dans les cellules du tableau avant qu'elles ne soient tronquées. Lorsqu'une valeur de cellule dépasse cette longueur, elle est tronquée avec un élément extensible permettant d'afficher le texte complet. La valeur par défaut est de 250 caractères.

export TRACKIO_TABLE_TRUNCATE_LENGTH="500"

TRACKIO_STORAGE_MODE

Controls how Trackio persists data locally. Allowed values: auto (default), sqlite, jsonl.

• sqlite : les processus d’entraînement écrivent directement dans la base de données SQLite du projet (comportement historique).
• jsonl : les processus d’entraînement écrivent des fragments JSONL en mode append-only dans TRACKIO_DIR/inbox/, un fichier par processus ; le serveur du tableau de bord (trackio show) les importe dans SQLite. Cela évite tout écriture concurrente à SQLite, ce qui rend Trackio sûr sur les systèmes de fichiers réseau (NFS, Lustre, FSx, GPFS, WekaFS, CephFS, …) où les sémantiques de verrouillage et de mmap de SQLite sont peu fiables.
• auto : sélectionne automatiquement jsonl lorsque TRACKIO_DIR est détecté sur un système de fichiers réseau (Linux uniquement), sinon sqlite.

export TRACKIO_STORAGE_MODE="jsonl"

TRACKIO_INBOX_POLL_INTERVAL

Fréquence (en secondes) à laquelle le serveur de tableau de bord et Trackio Spaces vérifient la présence de nouveaux fragments JSONL à importer, tant depuis le répertoire local de la boîte d’arrivée que depuis la boîte d’arrivée du Bucket Hugging Face. La valeur par défaut est 15 ; les valeurs inférieures à 5 sont ramenées à 5.

export TRACKIO_INBOX_POLL_INTERVAL="30"

TRACKIO_SQLITE_* (avancé)

Écraser les PRAGMAs que Trackio définit sur ses connexions SQLite. Ces paramètres sont principalement utiles sur des systèmes de fichiers atypiques ; les valeurs invalides sont ignorées.

• TRACKIO_SQLITE_JOURNAL_MODE : l’un des éléments suivants : wal, delete, truncate, persist, memory, off. La valeur par défaut est wal en local et delete sur Spaces.
• TRACKIO_SQLITE_MMAP_SIZE : taille de l’E/S mappée en mémoire, en octets. La valeur par défaut est 0 (désactivé) partout, car les lectures mappées en mémoire sont le déclencheur direct des plantages SIGBUS sur les systèmes de fichiers réseau et n’apportent que peu d’avantages pour la charge de travail de Trackio.
• TRACKIO_SQLITE_SYNCHRONOUS : l’un des éléments off, normal, full, extra. La valeur par défaut est normal.
• TRACKIO_SQLITE_LOCKING_MODE : l’un des modes normal, exclusive. La valeur par défaut est exclusive sur Spaces, normal ailleurs.
• TRACKIO_SQLITE_TEMP_STORE : l’un des default, file, memory. La valeur par défaut est memory.

Configuration de cluster recommandée : si votre répertoire personnel ou de cache se trouve sur un système de fichiers partagé (/fsx, Lustre, NFS, GPFS, WekaFS, …), pointez soit TRACKIO_DIR vers un disque local au nœud (par exemple /tmp ou $SLURM_TMPDIR), soit reposez-vous sur TRACKIO_STORAGE_MODE=auto qui détecte les systèmes de fichiers réseau et bascule sur la journalisation de fragments JSONL. Si vous devez écrire directement dans SQLite sur un système de fichiers partagé, définissez :

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

TRACKIO_WEBHOOK_URL

Définit une URL de webhook globale pour les alertes. Une fois définie, chaque appel à trackio.alert() enverra la charge utile de l’alerte à cette URL via une requête POST. Les URL de webhook Slack et Discord sont prises en charge nativement (les charges utiles sont formatées automatiquement). Peut être remplacée par alerte ou par exécution via le paramètre webhook_url.

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

Consultez le guide des alertes pour plus de détails.

TRACKIO_WEBHOOK_MIN_LEVEL

Définit le niveau d’alerte minimal qui doit être envoyé aux webhooks. Les alertes inférieures à ce niveau sont toujours affichées dans le terminal, stockées dans la base de données et visibles dans le tableau de bord, mais ne sont pas envoyées aux destinations webhook.

Valeurs autorisées : info, warn, error.

export TRACKIO_WEBHOOK_MIN_LEVEL="warn"

Avec warn, seules les alertes WARN et ERROR sont envoyées aux URL de webhook.

TRACKIO_CAPTURE_CONSOLE

Lorsqu’il est défini sur 1 ou true, Trackio capture tout ce qui est écrit dans stdout et stderr pendant une exécution et l’affiche sur la page de l’exécution dans le tableau de bord. Équivalent à passer capture_console=True à trackio.init() ; un argument capture_console explicite prend le pas.

export TRACKIO_CAPTURE_CONSOLE=1

Voir Capture de la sortie de la console et de la commande de lancement pour plus de détails.

TRACKIO_HANDLE_SIGTERM

Lorsque la valeur est définie sur 1 ou true, trackio.init() installe un gestionnaire SIGTERM qui convertit le signal en une sortie normale, de sorte que l’exécution est terminée et que ses dernières métriques et sa sortie console sont enregistrées lorsque le processus est arrêté par une limite de temps Slurm, docker stop ou une éviction Kubernetes. Le code de sortie reste 143. Le gestionnaire n’est installé que depuis le thread principal et uniquement si aucun autre gestionnaire SIGTERM n’est défini. Il est désactivé par défaut car il modifie la façon dont l’ensemble du processus réagit à SIGTERM : par exemple, le processus attend la fin des threads non-daemon avant de se terminer, et les frameworks qui enchaînent les gestionnaires existants (comme le Slurm auto-requeue de PyTorch Lightning) se termineront au lieu d’ignorer le signal.

export TRACKIO_HANDLE_SIGTERM=1

TRACKIO_BUCKET_ID

L’identifiant du Bucket Hugging Face (par exemple username/bucketname) utilisé pour persister les données Trackio lors de l’exécution sur un Hugging Face Space. Il est normalement défini automatiquement sur le Space lors de sa création via trackio.init(space_id=...) ou trackio.sync(...) ; un bucket est généré automatiquement à partir de l’identifiant du Space, sauf si un bucket_id explicite est fourni.

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

TRACKIO_DATASET_ID (obsolète)

Déprécié : La persistance des données Trackio dans un Dataset Hugging Face (dataset_id / TRACKIO_DATASET_ID) est dépréciée et sera supprimée dans une future version de Trackio. Utilisez à la place un Bucket Hugging Face (bucket_id / TRACKIO_BUCKET_ID).

L'identifiant du jeu de données Hugging Face (par exemple username/datasetname) vers lequel un Space Trackio synchronise ses données via un planificateur d'engagement en arrière-plan. Lorsqu'il est défini sur un Space, Trackio émet un avertissement de non-recommandation et continue de synchroniser vers le jeu de données pour le moment.

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

HF_TOKEN

Votre jeton d’authentification Hugging Face. Requis pour créer des Spaces et des Buckets sur Hugging Face. Définissez-le localement lors du déploiement vers Spaces depuis votre machine. Il doit disposer des autorisations write pour l’espace de noms dans lequel vous déployez le tableau de bord Trackio.

export HF_TOKEN="hf_xxxxxxxxxxxxx"

Variables d'environnement de Gradio

Puisque Trackio est construit sur la base de Gradio, vous pouvez utiliser les variables d’environnement utilisées par Gradio pour contrôler le comportement de Trackio. Voici quelques exemples :

GRADIO_SERVER_PORT

Spécifie le port sur lequel le tableau de bord Tradio sera lancé. La valeur par défaut est 7860

export GRADIO_SERVER_PORT=8000

GRADIO_SERVER_NAME

Définit le nom d'hôte du serveur du tableau de bord Trackio. Pour rendre le tableau de bord accessible depuis n'importe quelle adresse IP, définissez cette valeur sur "0.0.0.0"

export GRADIO_SERVER_NAME="0.0.0.0"

GRADIO_MCP_SERVER

Active la fonctionnalité de serveur MCP (Model Context Protocol) dans Trackio. Une fois activée, le tableau de bord Trackio est configuré en tant que serveur MCP et certaines fonctions sont exposées en tant qu’outils MCP, utilisables par des LLM (par exemple, pour lire les métriques journalisées).

export GRADIO_MCP_SERVER="True"

Voir cette liste plus complète des variables d’environnement utilisées par Gradio.