# Cảnh báo

Cảnh báo Trackio cho phép bạn đánh dấu các sự kiện quan trọng trong một lần chạy. Khi một cảnh báo được kích hoạt, nó sẽ:

1. **Được in ra terminal** kèm nhãn mức độ nghiêm trọng có mã màu
2. **Được lưu trong cơ sở dữ liệu** để có thể truy vấn sau đó qua CLI, API Python hoặc điểm cuối HTTP
3. **Hiển thị trên bảng điều khiển** thông qua một bảng thông báo nổi và trang Báo cáo
4. **Gửi đến webhook** (tùy chọn) — với định dạng gốc cho Slack và Discord

## Kích hoạt Cảnh báo

Sử dụng `alert()` ở bất kỳ đâu sau khi gọi [init()](/docs/trackio/v0.45.0/vi/api#trackio.init):

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

### Tham số

| Tham số | Loại | Mặc định | Mô tả |
|---|---|---|---|
| `title` | `str` | *(bắt buộc)* | Tiêu đề ngắn cho cảnh báo. |
| `text` | `str \| None` | `None` | Mô tả dài hơn tùy chọn với các chi tiết. |
| `level` | `AlertLevel` | `AlertLevel.WARN` | Mức độ nghiêm trọng: `INFO`, `WARN` hoặc `ERROR`. |
| `webhook_url` | `str \| None` | `None` | Ghi đè URL webhook toàn cục chỉ cho cảnh báo này. |

### Mức độ cảnh báo

```python
from trackio import AlertLevel

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

## Đầu ra của Terminal

Mọi cảnh báo đều được in ra terminal ngay lập tức, kèm theo nhãn có mã màu:

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

- **INFO** được in bằng màu xanh lam
- **WARN** được in màu vàng
- **ERROR** được in màu đỏ

Điều này có nghĩa là các cảnh báo hoạt động ngay lập tức mà không cần thiết lập — nếu bạn có thể xem nhật ký huấn luyện của mình, bạn cũng có thể xem các cảnh báo.

## Bảng điều khiển

Các cảnh báo xuất hiện ở hai vị trí trong bảng điều khiển Trackio:

1. **Bảng thông báo** — Một bảng nổi ở góc dưới bên phải của mọi trang bảng điều khiển. Nó hiển thị tất cả các thông báo (trên tất cả các dự án) đã đến kể từ khi bảng điều khiển được khởi chạy, với thông báo mới nhất ở cuối. Bạn có thể lọc theo mức độ nghiêm trọng và mở rộng/thu gọn bảng. Bảng sẽ nhấp nháy khi có thông báo mới đến.

2. **Trang Báo cáo** — Trang Báo cáo bao gồm bảng cảnh báo đầy đủ bên dưới phần báo cáo. Bạn có thể lọc cảnh báo theo lần chạy (thông qua menu thả xuống ở thanh bên) và theo mức độ nghiêm trọng (thông qua nhóm hộp kiểm ở thanh bên).

Để khởi chạy bảng điều khiển:

```bash
trackio show --project "my-project"
```

## Truy vấn Cảnh báo

### CLI

```bash
# 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
```

### Kiểm tra các chỉ số xung quanh một cảnh báo

Khi một cảnh báo được kích hoạt, bạn thường muốn xem toàn bộ các chỉ số trông như thế nào tại thời điểm đó. Sử dụng `trackio get snapshot` để lấy mọi chỉ số tại hoặc quanh bước hoặc mốc thời gian của cảnh báo:

```bash
# 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
```

Xem trang [Lệnh CLI](cli_commands) để biết danh sách đầy đủ các tùy chọn lọc.

### API Python

```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 API

Nếu bảng điều khiển Trackio đang chạy (trên máy cục bộ hoặc trên một Space), bạn có thể truy vấn cảnh báo qua endpoint `/get_alerts`:

```python
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 cho phép bạn đẩy cảnh báo đến các dịch vụ bên ngoài như Slack, Discord hoặc bất kỳ điểm cuối HTTP nào.

### Đặt Webhook Toàn cục

Bạn có thể đặt một URL webhook áp dụng cho mọi cảnh báo trong một lần chạy:

**Tùy chọn 1: Trong `trackio.init()`**

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

**Tùy chọn 2: Biến môi trường**

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

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

Biến môi trường tiện lợi khi bạn muốn dùng cùng một webhook cho tất cả các dự án mà không cần thay đổi mã.

### Gửi Chỉ Các Cảnh Báo Nghiêm Trọng Hơn Đến Webhooks

Nếu bạn chỉ muốn webhook cho các cảnh báo quan trọng, hãy đặt `webhook_min_level` trong `trackio.init()`:

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

Với `webhook_min_level=AlertLevel.WARN`:
- Các cảnh báo `INFO` vẫn được in/lưu/hiển thị trong giao diện người dùng, nhưng không được gửi đến webhook
- Các cảnh báo `WARN` và `ERROR` được gửi đến webhook

Bạn cũng có thể cấu hình điều này trên toàn cục bằng một biến môi trường:

```bash
export TRACKIO_WEBHOOK_MIN_LEVEL="warn"
```

### Ghi đè cho từng cảnh báo

Truyền `webhook_url` trực tiếp vào `trackio.alert()` để ghi đè cài đặt toàn cục cho một cảnh báo duy nhất, hoặc để gửi một cảnh báo cụ thể đến một kênh khác:

```python
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 Payload

Trackio tự động phát hiện dịch vụ từ URL và định dạng payload tương ứng.

**Webhook chung** nhận thân bài POST dạng JSON:

```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** và **Discord** nhận các tin nhắn định dạng phong phú (xem các mục bên dưới).

Webhooks được gửi trong một luồng nền nên `trackio.alert()` không bao giờ chặn vòng lặp huấn luyện của bạn.

---

## Slack

### Tạo Webhook Slack

1. Truy cập [https://api.slack.com/apps](https://api.slack.com/apps) và nhấp vào **Create New App** → **From scratch**.
2. Đặt tên cho ứng dụng (ví dụ: "Trackio Alerts") và chọn workspace của bạn.
3. Trong thanh bên trái, nhấp vào **Incoming Webhooks** và bật **On**.
4. Nhấp vào **Thêm Webhook mới vào Workspace**, chọn kênh bạn muốn nhận cảnh báo, sau đó nhấp vào **Cho phép**.
5. Sao chép URL webhook. Nó có dạng:
   ```
   https://hooks.slack.com/services/TXXXXX/BXXXXX/XXXXXXXXXX
   ```

### Sử dụng với Trackio

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

### Nó trông như thế nào

Trackio gửi các thông báo [Block Kit](https://api.slack.com/block-kit) của Slack với:
- Tiêu đề nổi bật với emoji và mức độ nghiêm trọng (ví dụ: "⚠️ **[WARN] Loss spike**")
- Một phần mô tả tùy chọn với `text` của bạn
- Chân trang ngữ cảnh hiển thị tên dự án, tên chạy và số bước

---

## Discord

### Tạo Webhook Discord

1. Mở **Cài đặt máy chủ** → **Tích hợp** → **Webhooks**.
2. Nhấp vào **Webhook mới**.
3. Đặt tên cho nó (ví dụ: "Trackio Alerts"), chọn kênh và nhấp vào **Copy Webhook URL**.
4. URL có dạng:
   ```
   https://discord.com/api/webhooks/123456789/ABCDEFghijklmnop
   ```

### Sử dụng với Trackio

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

### Nó trông như thế nào

Trackio gửi các tin nhắn [Embed](https://discord.com/developers/docs/resources/message#embed-object) Discord với:
- Thanh bên có mã màu (xanh dương cho INFO, vàng cho WARN, đỏ cho ERROR)
- Tiêu đề có emoji và mức độ nghiêm trọng
- Mô tả với `text` của bạn
- Phân trang chân trang với tên dự án, tên chạy và số bước