تنبيهات

تتيح لك تنبيهات Trackio تحديد الأحداث المهمة أثناء التشغيل. عند إطلاق تنبيه، يتم:

1. يُطبع في الطرفية مع تسمية شدة ملوّنة
2. مُخزَّن في قاعدة البيانات بحيث يمكن الاستعلام عنه لاحقًا عبر سطر الأوامر، أو واجهة برمجة تطبيقات بايثون، أو نقطة نهاية HTTP
3. يظهر في لوحة التحكم عبر لوحة تنبيهات عائمة وصفحة التقارير
4. إرسال إلى خطاف ويب (اختياري) — مع تنسيق أصلي لـ 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,
    )

المعاملات

مستويات التنبيه

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:

1. لوحة التنبيهات — لوحة عائمة في الزاوية اليمنى السفلية من كل صفحة لوحة تحكم. تعرض جميع التنبيهات (عبر جميع المشاريع) التي وصلت منذ تشغيل لوحة التحكم، مع وضع أحدث تنبيه في الأسفل. يمكنك التصفية حسب مستوى الخطورة وتوسيع/طي اللوحة. تومض اللوحة عند وصول تنبيهات جديدة.

2. صفحة التقارير — تتضمن صفحة التقارير جدول تنبيهات كاملًا أسفل قسم التقارير. يمكنك تصفية التنبيهات حسب التشغيل (عبر قائمة المنسدلة في الشريط الجانبي) وحسب مستوى الخطورة (عبر مجموعة مربعات الاختيار في الشريط الجانبي).

لإطلاق لوحة التحكم:

trackio show --project "my-project"

استعلام التنبيهات

سطر الأوامر

# 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

راجع صفحة أوامر سطر الأوامر للاطلاع على القائمة الكاملة لخيارات التصفية.

واجهة برمجة تطبيقات 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")

واجهة برمجة التطبيقات عبر HTTP

إذا كان لوحة تحكم 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 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 لجميع المشاريع دون الحاجة إلى تغيير الكود.

إرسال تنبيهات ذات خطورة أعلى فقط إلى نقاط الويب

إذا كنت ترغب في استخدام webhooks للتنبيهات المهمة فقط، فاضبط webhook_min_level في trackio.init():

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 وتُخزَّن وتُعرض في الواجهة، لكنها لا تُرسل إلى خطاف الويب
• تُرسل تنبيهات 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 وتنسيق الحمولة (payload) وفقًا لذلك.

تستقبل Generic webhooks جسم طلب POST بصيغة 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 و Discord رسائل منسّقة غنية (انظر الأقسام أدناه).

تُرسل Webhooks في خيط خلفية (background thread) لذا لا يحجب trackio.alert() حلقة التدريب الخاصة بك أبداً.

Slack

إنشاء خط ويب لـ Slack

1. انتقل إلى https://api.slack.com/apps وانقر على Create New App ← From scratch.
2. امنح التطبيق اسمًا (مثلًا “Trackio Alerts”) واختر مساحة العمل الخاصة بك.
3. في الشريط الجانبي الأيسر، انقر على Incoming Webhooks ثم فعّلها On.
4. انقر على إضافة Webhook جديد إلى مساحة العمل، وحدد القناة التي تريد استلام التنبيهات فيها، ثم انقر على السماح.
5. انسخ رابط webhook. يبدو على النحو التالي:
   تم النسخ

   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

1. افتح إعدادات الخادم → التكاملات → Webhooks.
2. انقر على Webhook جديد.
3. امنحها اسمًا (مثلًا “Trackio Alerts”)، وحدد القناة، ثم انقر على Copy Webhook URL.
4. يبدو الرابط على النحو التالي:
   تم النسخ

   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 رسائل Embed على Discord تتضمن:

• شريط جانبي ملوّن (أزرق لـ INFO، أصفر لـ WARN، أحمر لـ ERROR)
• عنوان يحتوي على رمز تعبيري ومستوى خطورة
• وصف يحتوي على text الخاص بك
• تذييل يتضمن اسم المشروع واسم التشغيل ورقم الخطوة