Alertes

Les alertes Trackio vous permettent de signaler des événements importants pendant une exécution. Lorsqu’une alerte se déclenche, elle est :

Affiché dans le terminal avec un libellé de gravité codé par couleur
Stocké dans la base de données afin de pouvoir être interrogé ultérieurement via le CLI, l'API Python ou le point de terminaison HTTP
Affiché dans le tableau de bord via un panneau d’alerte flottant et la page Rapports
Envoyer vers un webhook (facultatif) — avec un formatage natif pour Slack et Discord

Déclencher une alerte

Utilisez alert() n'importe où après avoir appelé init() :

import trackio

trackio.init(project="my-project")

# ... inside your training loop ...
if val_loss > 2.0:
    trackio.alert(
        title="Validation loss spike",
        text=f"val_loss={val_loss:.4f} exceeded threshold 2.0",
        level=trackio.AlertLevel.ERROR,
    )

Paramètres

Paramètre	Type	Par défaut	Description
`title`	`str`	(obligatoire)	Un titre court pour l'alerte.
`text`	`str \\| None`	`None`	Une description plus longue et facultative, avec des détails.
`level`	`AlertLevel`	`AlertLevel.WARN`	Gravité : `INFO`, `WARN` ou `ERROR`.
`webhook_url`	`str \\| None`	`None`	Écraser l'URL globale du webhook uniquement pour cette alerte.

Niveaux d'alerte

from trackio import AlertLevel

AlertLevel.INFO   # Informational — nothing is wrong
AlertLevel.WARN   # Warning — something may need attention
AlertLevel.ERROR  # Error — something is definitely wrong

Sortie du terminal

Chaque alerte est affichée immédiatement dans le terminal, avec un libellé codé par couleur :

[TRACKIO WARN] Validation loss spike: val_loss=2.3412 exceeded threshold 2.0 (step 42)

INFO est affiché en bleu
WARN est affiché en jaune
ERROR est affiché en rouge

Cela signifie que les alertes fonctionnent immédiatement, sans configuration — si vous pouvez voir vos journaux d’entraînement, vous pouvez voir vos alertes.

Tableau de bord

Les alertes apparaissent à deux endroits dans le tableau de bord Trackio :

Panneau d’alertes — Un panneau flottant situé dans le coin inférieur droit de chaque page de tableau de bord. Il affiche toutes les alertes (tous projets confondus) arrivées depuis le lancement du tableau de bord, la plus récente étant en bas. Vous pouvez filtrer par niveau de gravité et déplier/replier le panneau. Le panneau clignote à l’arrivée de nouvelles alertes.
Page des rapports — La page des rapports inclut un tableau complet des alertes sous la section des rapports. Vous pouvez filtrer les alertes par exécution (via le menu déroulant de la barre latérale) et par niveau de gravité (via le groupe de cases à cocher de la barre latérale).

Pour lancer le tableau de bord :

trackio show --project "my-project"

Interroger les alertes

CLI

# List all alerts for a project
trackio get alerts --project "my-project"

# Filter by run
trackio get alerts --project "my-project" --run "brave-sunset-0"

# Filter by level
trackio get alerts --project "my-project" --level error

# Only alerts after a specific timestamp (useful for polling)
trackio get alerts --project "my-project" --since "2025-06-01T00:00:00"

# JSON output for programmatic consumption
trackio get alerts --project "my-project" --json

Inspecter les métriques autour d'une alerte

Lorsqu’une alerte se déclenche, vous souhaitez souvent voir l’aspect de toutes les métriques à ce moment-là. Utilisez trackio get snapshot pour obtenir chaque métrie à l’étape ou au timestamp de l’alerte, ou à proximité :

# An alert fired at step 200 — get all metrics in a ±5 step window
trackio get snapshot --project "my-project" --run "brave-sunset-0" --around 200 --window 5 --json

# Or inspect a single metric around the alert's timestamp
trackio get metric --project "my-project" --run "brave-sunset-0" --metric "loss" --at-time "2025-06-01T12:05:30" --window 60 --json

Consultez la page Commandes CLI pour la liste complète des options de filtrage.

API Python

import trackio

api = trackio.Api()

# All alerts in a project
alerts = api.alerts("my-project")

# Filter by run and level
alerts = api.alerts("my-project", run="brave-sunset-0", level="error")

# Only new alerts since a timestamp
alerts = api.alerts("my-project", since="2025-06-01T12:00:00")

# From a Run object
runs = api.runs("my-project")
run_alerts = runs[0].alerts(level="warn")

API HTTP

Si le tableau de bord Trackio est en cours d’exécution (localement ou sur un Space), vous pouvez interroger les alertes via le point de terminaison /get_alerts :

import httpx2

alerts = httpx2.post(
    "http://127.0.0.1:7860/api/get_alerts",
    json={
        "project": "my-project",
        "run": None,
        "level": "error",
        "since": "2025-06-01T00:00:00",
    },
).json()["data"]

Webhooks

Les webhooks vous permettent d’envoyer des alertes vers des services externes tels que Slack, Discord ou tout point de terminaison HTTP.

Définir un webhook global

Vous pouvez définir une URL de webhook qui s’applique à chaque alerte d’une exécution :

Option 1 : dans trackio.init()

trackio.init(
    project="my-project",
    webhook_url="https://hooks.slack.com/services/T.../B.../xxx",
)

Option 2 : Variable d’environnement

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

# No webhook_url needed — picks up the env var automatically
trackio.init(project="my-project")

La variable d'environnement est pratique lorsque vous souhaitez utiliser le même webhook pour tous les projets sans modifier le code.

Envoi uniquement des alertes de gravité supérieure vers les Webhooks

Si vous ne souhaitez des webhooks que pour les alertes importantes, définissez webhook_min_level dans trackio.init() :

trackio.init(
    project="my-project",
    webhook_url="https://hooks.slack.com/services/T.../B.../xxx",
    webhook_min_level=trackio.AlertLevel.WARN,
)

Avec webhook_min_level=AlertLevel.WARN :

Les alertes INFO sont toujours affichées/enregistrées/affichées dans l'interface utilisateur, mais ne sont pas envoyées au webhook
Les alertes WARN et ERROR sont envoyées au webhook

Vous pouvez également configurer cela globalement avec une variable d'environnement :

export TRACKIO_WEBHOOK_MIN_LEVEL="warn"

Définition par alerte

Passez webhook_url directement à trackio.alert() pour remplacer le paramètre global pour une seule alerte, ou pour envoyer une alerte spécifique à un autre canal :

trackio.alert(
    title="Checkpoint saved",
    text="Saved model at step 5000",
    level=trackio.AlertLevel.INFO,
    webhook_url="https://discord.com/api/webhooks/123456/abcdef",
)

Webhook Payloads

Trackio détecte automatiquement le service à partir de l’URL et met en forme la charge utile en conséquence.

Webhooks génériques reçoivent un corps de requête POST au format JSON :

{
    "level": "warn",
    "title": "Validation loss spike",
    "text": "val_loss=2.34 exceeded threshold 2.0",
    "project": "my-project",
    "run": "brave-sunset-0",
    "step": 42,
    "timestamp": "2025-06-15T14:30:00+00:00"
}

Slack et Discord reçoivent des messages richement formatés (voir les sections ci-dessous).

Les webhooks sont envoyés dans un thread en arrière-plan, de sorte que trackio.alert() ne bloque jamais votre boucle d'entraînement.

Slack

Créer un Webhook Slack

Accédez à https://api.slack.com/apps et cliquez sur Create New App → From scratch.
Donnez un nom à l’application (par exemple, « Trackio Alerts ») et sélectionnez votre espace de travail.
Dans la barre latérale gauche, cliquez sur Incoming Webhooks et activez-le en le passant sur On.
Cliquez sur Ajouter un nouveau Webhook à l’espace de travail, sélectionnez le canal dans lequel vous souhaitez recevoir les alertes, puis cliquez sur Autoriser.

Copiez l'URL du webhook. Elle ressemble à ceci :

https://hooks.slack.com/services/TXXXXX/BXXXXX/XXXXXXXXXX

L'utiliser avec Trackio

trackio.init(
    project="my-project",
    webhook_url="https://hooks.slack.com/services/T.../B.../xxx",
)

trackio.alert(
    title="Training complete",
    text="Final val_accuracy: 0.94",
    level=trackio.AlertLevel.INFO,
)

À quoi ça ressemble

Trackio envoie des messages Slack Block Kit avec :

Un en-tête en gras avec un emoji et un niveau de gravité (par exemple, « ⚠️ [WARN] Loss spike »)
Une section de description facultative avec votre text
Un pied de page de contexte affichant le nom du projet, le nom de l'exécution et le numéro d'étape

Discord

Créer un Webhook Discord

Ouvrez Paramètres du serveur → Intégrations → Webhooks.
Cliquez sur Nouveau Webhook.
Donnez-lui un nom (par exemple, « Trackio Alerts »), sélectionnez le canal, puis cliquez sur Copy Webhook URL.

L'URL ressemble à ceci :

https://discord.com/api/webhooks/123456789/ABCDEFghijklmnop

L'utiliser avec Trackio

trackio.init(
    project="my-project",
    webhook_url="https://discord.com/api/webhooks/123456789/ABCDEFghijklmnop",
)

trackio.alert(
    title="GPU temperature critical",
    text="GPU 0 reached 95°C",
    level=trackio.AlertLevel.ERROR,
)

À quoi ça ressemble

Trackio envoie des messages Discord Embed avec :

Une barre latérale codée par couleur (bleu pour INFO, jaune pour WARN, rouge pour ERROR)
Un titre avec émoji et niveau de gravité
Une description avec votre text
Un pied de page avec le nom du projet, le nom de l'exécution et le numéro d'étape

Update on GitHub