알림

Trackio 알림을 사용하면 런 중에 중요한 이벤트를 표시할 수 있습니다. 알림이 트리거되면 다음과 같이 처리됩니다:

터미널에 출력되며, 색상으로 구분된 심각도 라벨이 함께 표시됩니다
CLI, Python API 또는 HTTP 엔드포인트를 통해 나중에 쿼리할 수 있도록 데이터베이스에 저장됩니다
대시보드에 표시되며, 플로팅 알림 패널과 Reports 페이지를 통해 제공됩니다
Webhook으로 전송 (선택 사항) — Slack 및 Discord에 대한 네이티브 포맷 지원

알림 트리거

alert()은 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,
    )

매개변수

매개변수	유형	기본값	설명
`title`	`str`	(필수)	알림의 짧은 제목.
`text`	`str \\| None`	`None`	상세 정보가 포함된 선택적 긴 설명입니다.
`level`	`AlertLevel`	`AlertLevel.WARN`	중요도: `INFO`, `WARN` 또는 `ERROR`.
`webhook_url`	`str \\| None`	`None`	이 경고에만 대해 전역 웹훅 URL을 재정의합니다.

경보 수준

from trackio import AlertLevel

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

터미널 출력

모든 알림은 색상 코드가 적용된 라벨과 함께 터미널에 즉시 출력됩니다:

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

INFO는 파란색으로 출력됩니다
WARN은 노란색으로 출력됩니다
ERROR은 빨간색으로 출력됩니다

즉, 별도 설정 없이 바로 사용할 수 있습니다. 학습 로그를 볼 수 있다면 알림도 볼 수 있습니다.

대시보드

Alerts는 Trackio 대시보드에서 두 가지 위치에 표시됩니다:

알림 패널 — 모든 대시보드 페이지의 오른쪽 하단 모서리에 표시되는 플로팅 패널입니다. 대시보드가 시작된 이후에 도착한 모든 알림(모든 프로젝트에 걸쳐)을 표시하며, 최신 알림이 맨 아래에 위치합니다. 심각도 수준별로 필터링하고 패널을 확장/축소할 수 있습니다. 새 알림이 도착하면 패널이 깜빡입니다.
Reports 페이지 — Reports 페이지에는 reports 섹션 아래에 전체 alerts 테이블이 포함됩니다. 사이드바 드롭다운을 통해 run별로, 사이드바 체크박스 그룹을 통해 severity level별로 alerts를 필터링할 수 있습니다.

대시보드를 시작하려면:

trackio show --project "my-project"

알림 쿼리

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

알림 주위의 지표 검사

알림이 트리거되면 해당 시점의 모든 지표가 어떻게 보였는지 확인하고 싶을 때가 많습니다. trackio get snapshot를 사용하여 알림의 스텝 또는 타임스탬프 주변/해당 시점의 모든 지표를 가져오세요:

# 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

필터링 옵션의 전체 목록은 CLI Commands 페이지를 참조하세요.

Python API

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")

HTTP API

Trackio 대시보드가 실행 중(로컬 또는 Space)이라면 /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

Webhooks를 사용하면 Slack, Discord 또는 HTTP 엔드포인트와 같은 외부 서비스로 알림을 전송할 수 있습니다.

전역 Webhook 설정

런(run)의 모든 알림에 적용되는 웹훅 URL을 설정할 수 있습니다:

옵션 1: trackio.init()에서

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

옵션 2: 환경 변수

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")

env 변수는 코드를 변경하지 않고 모든 프로젝트에 동일한 웹훅을 사용하려는 경우 유용합니다.

Webhook으로 더 높은 심각도의 알림만 전송

중요한 알림에 대해서만 웹훅을 사용하려면 trackio.init()에서 webhook_min_level를 설정하세요:

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

webhook_min_level=AlertLevel.WARN인 경우:

INFO 경고는 여전히 출력/저장/UI에 표시되지만, 웹훅으로 전송되지 않습니다
WARN 및 ERROR 알림은 웹훅으로 전송됩니다

환경 변수를 사용하여 전역으로 설정할 수도 있습니다:

export TRACKIO_WEBHOOK_MIN_LEVEL="warn"

알림별 오버라이드

webhook_url을 trackio.alert()에 직접 전달하여 단일 알림에 대해 전역 설정을 재정의하거나, 특정 알림을 다른 채널로 보낼 수 있습니다:

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 페이로드

Trackio는 URL에서 서비스를 자동으로 감지하고 이에 따라 페이로드를 포맷합니다.

Generic webhooks는 JSON POST 본체를 수신합니다:

{
    "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와 Discord에는 풍부한 형식의 메시지가 전송됩니다(아래 섹션 참조).

Webhooks는 백그라운드 스레드에서 전송되므로 trackio.alert()이 학습 루프를 차단하지 않습니다.

Slack

Slack Webhook 만들기

https://api.slack.com/apps로 이동하여 Create New App → From scratch를 클릭하세요.
Trackio Alerts와 같은 이름을 지정하고 워크스페이스를 선택하세요.
왼쪽 사이드바에서 Incoming Webhooks를 클릭하고 On으로 전환합니다.
워크스페이스에 새 Webhook 추가를 클릭하고 알림을 받을 채널을 선택한 후 허용을 클릭합니다.
Webhook URL을 복사하세요. 다음과 같은 형태입니다:
```
https://hooks.slack.com/services/TXXXXX/BXXXXX/XXXXXXXXXX
```

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

모습

Trackio는 다음을 포함하는 Slack Block Kit 메시지를 전송합니다:

이모지와 심각도 수준을 포함한 굵은 헤더(예: “⚠️ [WARN] Loss spike“)
text를 포함하는 선택적 설명 섹션
프로젝트 이름, 실행 이름, 단계 번호를 표시하는 컨텍스트 푸터

Discord

Discord Webhook 만들기

서버 설정 → 통합 → 웹훅을(를) 엽니다.
새 Webhook을 클릭합니다.
이름을 지정하고(예: “Trackio Alerts”), 채널을 선택한 후 Copy Webhook URL을 클릭합니다.

URL은 다음과 같은 형태입니다:

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

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

모습

Trackio는 Discord Embed 메시지를 다음 내용과 함께 전송합니다:

색상 코딩된 사이드바(INFO는 파란색, WARN은 노란색, ERROR는 빨간색)
이모지와 심각도 레벨이 포함된 제목
text가 포함된 설명
프로젝트 이름, 실행 이름, 단계 번호가 포함된 푸터

Update on GitHub