アラート

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`	このアラートにのみ適用されるグローバル Webhook 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 は赤色で表示されます

つまり、設定なしでアラートがすぐに動作します。トレーニングログが見える環境であれば、アラートも表示できます。

ダッシュボード

Trackioダッシュボードでは、アラートは2つの場所に表示されます。

アラートパネル — すべてのダッシュボードページの右下隅に表示される浮動パネルです。ダッシュボードの起動以降に届いたすべてのアラート（すべてのプロジェクトにわたる）を表示し、最新のアラートが最下部に配置されます。重大度レベルでフィルタリングでき、パネルの展開/折りたたみも可能です。新しいアラートが届くと、パネルが点滅します。
Reports ページ — Reports ページには、レポートセクションの下に完全なアラートテーブルが含まれています。ラン（サイドバーのドロップダウンメニューを介して）および重大度レベル（サイドバーのチェックボックスグループを介して）でアラートをフィルタリングできます。

ダッシュボードを起動するには:

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の設定

ラン内のすべてのアラートに適用されるWebhook 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 を使用したい場合に便利です。

Webhookへの高重大度アラートのみを送信する

重要なアラートのみ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に表示されますが、Webhookには送信されません。
WARNおよびERRORのアラートはwebhookに送信されます

環境変数を使用して、これをグローバルに設定することもできます:

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からサービスを自動検出し、それに合わせてペイロードを整形します。

汎用 Webhookは 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 には、リッチなフォーマット付きメッセージが送信されます（以下のセクションを参照）。

Webhook はバックグラウンドスレッドで送信されるため、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の作成

Server Settings → Integrations → Webhooks を開きます。
新しい 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