Alertas

Las alertas de Trackio te permiten marcar eventos importantes durante una ejecución. Cuando se activa una alerta, esta

1. Impreso en la terminal con una etiqueta de severidad codificada por color
2. Guardado en la base de datos para que pueda consultarse más adelante mediante la CLI, la API de Python o el punto de acceso HTTP
3. Mostrado en el panel de control mediante un panel de alertas flotante y la página Informes
4. Enviado a un webhook (opcional) — con formato nativo para Slack y Discord

Activar una alerta

Usa alert() en cualquier momento después de llamar a 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,
    )

Parámetros

Niveles de alerta

from trackio import AlertLevel

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

Salida de la terminal

Cada alerta se imprime en la terminal de inmediato, con una etiqueta codificada por color:

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

• INFO se imprime en azul
• WARN se imprime en amarillo
• ERROR se imprime en rojo

Esto significa que las alertas funcionan desde el principio, sin necesidad de configuración: si puedes ver tus registros de entrenamiento, puedes ver tus alertas.

Panel de control

Las alertas aparecen en dos lugares en el panel de Trackio:

1. Panel de alertas — Un panel flotante en la esquina inferior derecha de cada página de panel de control. Muestra todas las alertas (en todos los proyectos) que llegaron desde que se inició el panel de control, con la alerta más reciente en la parte inferior. Puedes filtrar por nivel de severidad y expandir o contraer el panel. El panel parpadea cuando llegan nuevas alertas.

2. Página de informes — La página de informes incluye una tabla completa de alertas debajo de la sección de informes. Puedes filtrar las alertas por ejecución (mediante el menú desplegable de la barra lateral) y por nivel de severidad (mediante el grupo de casillas de selección de la barra lateral).

Para iniciar el panel de control:

trackio show --project "my-project"

Consultar alertas

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

Inspeccionar las métricas alrededor de una alerta

Cuando se activa una alerta, a menudo se desea ver cómo eran todas las métricas en ese momento. Utilice trackio get snapshot para obtener cada métrica en o alrededor del paso o marca de tiempo de la alerta:

# 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

Consulte la página Comandos de CLI para obtener la lista completa de opciones de filtrado.

API de 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 el panel de Trackio está en ejecución (localmente o en un Space), puedes consultar las alertas mediante el punto de acceso /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

Los webhooks permiten enviar alertas a servicios externos como Slack, Discord o cualquier punto de finalización HTTP.

Configuración de un webhook global

Puede configurar una URL de webhook que se aplique a todas las alertas de una ejecución:

Opción 1: En trackio.init()

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

Opción 2: Variable de entorno

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 de entorno es conveniente cuando se desea el mismo webhook para todos los proyectos sin cambiar el código.

Enviando solo alertas de mayor severidad a los webhooks

Si solo quieres webhooks para alertas importantes, configura webhook_min_level en trackio.init():

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

Con webhook_min_level=AlertLevel.WARN:

• Las alertas de INFO aún se imprimen, almacenan y muestran en la interfaz, pero no se envían al webhook.
• Las alertas WARN y ERROR se envían al webhook

También puede configurarse de forma global mediante una variable de entorno:

export TRACKIO_WEBHOOK_MIN_LEVEL="warn"

Anulación por alerta

Pase webhook_url directamente a trackio.alert() para anular la configuración global de una sola alerta o para enviar una alerta específica a un canal diferente:

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

Cargas de Webhook

Trackio detecta automáticamente el servicio a partir de la URL y formatea el payload en consecuencia.

Los webhooks genéricos reciben un cuerpo POST en 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 y Discord reciben mensajes con formato enriquecido (consulte las secciones siguientes).

Los webhooks se envían en un hilo en segundo plano, por lo que trackio.alert() nunca bloquea tu bucle de entrenamiento.

Slack

Creación de un Webhook de Slack

1. Vaya a https://api.slack.com/apps y haga clic en Create New App → From scratch.
2. Dale un nombre a la aplicación (p. ej., “Trackio Alerts”) y selecciona tu espacio de trabajo.
3. En la barra lateral izquierda, haz clic en Incoming Webhooks y actívalo en On.
4. Haz clic en Add New Webhook to Workspace, selecciona el canal en el que deseas recibir las alertas y haz clic en Allow.
5. Copia la URL del webhook. Tiene este aspecto:
   Copiado

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

Uso con 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,
)

Cómo se ve

Trackio envía mensajes de Slack Block Kit con:

• Un encabezado en negrita con un emoji y un nivel de severidad (p. ej., “⚠️ [WARN] Loss spike“)
• Una sección de descripción opcional con tu text
• Un pie de contexto que muestra el nombre del proyecto, el nombre de la ejecución y el número de paso

Discord

Creación de un webhook de Discord

1. Abra Server Settings → Integrations → Webhooks.
2. Haz clic en Nuevo Webhook.
3. Asígnales un nombre (p. ej., “Trackio Alerts”), selecciona el canal y haz clic en Copy Webhook URL.
4. La URL tiene este aspecto:
   Copiado

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

Uso con 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,
)

Cómo se ve

Trackio envía mensajes de Discord Embed con:

• Una barra lateral con código de colores (azul para INFO, amarillo para WARN, rojo para ERROR)
• Un título con emoji y nivel de severidad
• Una descripción con tu text
• Un pie de página con el nombre del proyecto, el nombre de la ejecución y el número de paso