# مانیتورینگ کران

> https://docs.errora.org/products/crons

مانیتور کران یک جاب زمان‌بندی‌شده را می‌پاید و وقتی **خطا بدهد**، **اصلاً اجرا نشود** (چک‌این
نرسیده) یا **بیش از حد طول بکشد** (تایم‌اوت) اعتراض می‌کند. چک‌این‌ها از هر SDK رسمی Sentry
می‌آیند یا از یک `curl` ساده در خط crontab.

## مفاهیم

| اصطلاح | معنی |
| --- | --- |
| **مانیتور** | جابی که انتظار خبرش را دارید، با یک **اسلاگ** شناخته می‌شود (`nightly-backup`) |
| **زمان‌بندی** | یک عبارت **crontab** پنج‌بخشی، یا یک **بازه** (`هر ۳۰ دقیقه`) |
| **چک‌این** | یک پیام از جاب: `in_progress`، `ok` یا `error` |
| **محیط** | هر محیط وضعیت خودش را نگه می‌دارد تا staging نتواند خرابی production را پنهان کند |
| **مهلت** | `checkin_margin` دقیقه ارفاق بعد از زمان مورد انتظار، پیش از آنکه *نرسیده* حساب شود |
| **بیشینهٔ اجرا** | `max_runtime` دقیقه پس از چک‌این `in_progress`، پیش از آنکه *تایم‌اوت* حساب شود |

## راه‌اندازی — گزینهٔ ۱: ساخت مانیتور از دل جاب

SDKهای Sentry می‌توانند مانیتور را با اولین چک‌این بسازند یا به‌روزرسانی کنند، پس زمان‌بندی
کنار خود کد می‌ماند:

```python
from sentry_sdk.crons import monitor

@monitor(monitor_slug="nightly-invoices")
def nightly_invoices():
    ...
```

```javascript
const checkInId = Sentry.captureCheckIn(
  { monitorSlug: "nightly-invoices", status: "in_progress" },
  {
    schedule: { type: "crontab", value: "0 3 * * *" },
    checkinMargin: 5,
    maxRuntime: 30,
    timezone: "Asia/Tehran",
  },
);

try {
  await run();
  Sentry.captureCheckIn({ checkInId, monitorSlug: "nightly-invoices", status: "ok" });
} catch (e) {
  Sentry.captureCheckIn({ checkInId, monitorSlug: "nightly-invoices", status: "error" });
  throw e;
}
```

لاراول:

```php
$schedule->command('invoices:generate')->dailyAt('03:00')->sentryMonitor('nightly-invoices');
```

## راه‌اندازی — گزینهٔ ۲: HTTP ساده (بدون SDK)

هر جابی که بتواند `curl` اجرا کند می‌تواند چک‌این بفرستد. کلید عمومی DSN در مسیر، آن را احراز
می‌کند:

```bash
# ساده: یک فراخوانی وقتی جاب تمام شد
curl -X POST "$ERRORA/api/$PROJECT_ID/cron/nightly-backup/$PUBLIC_KEY/?status=ok"

# بهتر: اجرا را در دو سر ببندید تا مدت و تایم‌اوت هم رصد شود
CHECK_IN=$(curl -s -X POST "$ERRORA/api/$PROJECT_ID/cron/nightly-backup/$PUBLIC_KEY/?status=in_progress" \
           | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')

if /usr/local/bin/backup.sh; then
  curl -X PUT "$ERRORA/api/$PROJECT_ID/cron/nightly-backup/$PUBLIC_KEY/$CHECK_IN/?status=ok"
else
  curl -X PUT "$ERRORA/api/$PROJECT_ID/cron/nightly-backup/$PUBLIC_KEY/$CHECK_IN/?status=error"
fi
```

در یک خط crontab، معمولاً همان شکل تک‌مرحله‌ای کافی است:

```crontab
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -X POST "https://errora.example.com/api/$PROJECT_ID/cron/nightly-backup/$KEY/?status=ok"
```

پارامترهای `environment=` و `duration=` (بر حسب میلی‌ثانیه) را هم می‌توانید بفرستید.

## راه‌اندازی — گزینهٔ ۳: ساخت مانیتور در پنل

**کران‌ها ← مانیتور جدید**. همان فیلدهایی که API می‌گیرد:

```json
{
  "slug": "nightly-invoices",
  "name": "فاکتورهای شبانه",
  "config": {
    "schedule_type": "crontab",
    "schedule": "0 3 * * *",
    "checkin_margin": 5,
    "max_runtime": 30,
    "timezone": "Asia/Tehran",
    "failure_issue_threshold": 1,
    "recovery_threshold": 1
  }
}
```

زمان‌بندی بازه‌ای با `"schedule_type": "interval"` و `"schedule": [30, "minute"]` نوشته
می‌شود. واحدها: `minute`، `hour`، `day`، `week`، `month`، `year`.

ماکروهای crontab هم کار می‌کنند: `@hourly`، `@daily`، `@midnight`، `@weekly`، `@monthly`،
`@yearly`. همه‌چیز **در منطقهٔ زمانی خود مانیتور** ارزیابی می‌شود؛ پس مانیتور `0 3 * * *` در
`Asia/Tehran` حتی با تغییر ساعت، سر ۰۳:۰۰ محلی می‌ماند.

## آستانه‌ها — با یک تک‌لغزش کسی را بیدار نکنید

- `failure_issue_threshold` — چند شکست پشت‌سرهم (خطا / نرسیده / تایم‌اوت) پیش از باز شدن خطا و
  فعال شدن هشدارها. پیش‌فرض `1`.
- `recovery_threshold` — چند موفقیت پشت‌سرهم تا دوباره سالم به‌حساب بیاید. پیش‌فرض `1`.

برای جاب‌هایی که گاهی می‌لرزند، آستانهٔ شکست را روی `2` یا `3` بگذارید.

## در پنل

صفحهٔ **کران‌ها** مانیتورها را با زمان‌بندی، چک‌این بعدی مورد انتظار، وضعیت فعلی به تفکیک محیط
و تاریخچهٔ چک‌این نشان می‌دهد. با باز کردن یکی، چک‌این‌های اخیر (وضعیت، مدت، نسخه، شناسهٔ
ترِیس) و آمارش را می‌بینید.

وضعیت‌ها: `ok`، `error`، `missed`، `timeout`، `in_progress` و `pending` تا پیش از رسیدن اولین
چک‌این.

## هشدارها

تغییر وضعیت کران رویدادهای `monitor.failed` و `monitor.recovered` را فعال می‌کند. در
**تنظیمات ← وب‌هوک‌ها** آن‌ها را به یک کانال و قاعدهٔ هشدار وصل کنید — نگاه کنید به
[هشدارها](/products/alerts).

## API

```text
GET    /api/v1/projects/{project_id}/monitors
POST   /api/v1/projects/{project_id}/monitors
GET    /api/v1/projects/{project_id}/monitors/overview
GET    /api/v1/projects/{project_id}/monitors/{slug}
PATCH  /api/v1/projects/{project_id}/monitors/{slug}
DELETE /api/v1/projects/{project_id}/monitors/{slug}
GET    /api/v1/projects/{project_id}/monitors/{slug}/checkins
GET    /api/v1/projects/{project_id}/monitors/{slug}/stats
```

مانیتورها علاوه بر شناسه، با **اسلاگ** هم آدرس‌پذیرند، چون کد جاب اسلاگ را می‌شناسد.

## عیب‌یابی

| نشانه | علت / راه‌حل |
| --- | --- |
| مانیتور در وضعیت `pending` مانده | هیچ چک‌اینی نرسیده — اسلاگ، شناسهٔ پروژه و کلید داخل آدرس را بررسی کنید |
| `missed` بی‌مورد | جاب دیر اجرا می‌شود؛ `checkin_margin` را بالا ببرید یا منطقهٔ زمانی زمان‌بندی را درست کنید |
| `timeout` بی‌مورد | `max_runtime` از زمان واقعی اجرای جاب کمتر است |
| جاب اجرا می‌شود ولی مانیتور خطا می‌دهد | لفافهٔ اسکریپت به‌خاطر خروج ناموفق *بخش دیگری* از خط لوله `error` می‌فرستد — خط شل را بررسی کنید |
| مانیتورهای تکراری | دو املای متفاوت از اسلاگ؛ اسلاگ‌ها یکدست می‌شوند ولی `nightly_backup` و `nightly-backup` دو مانیتور جدا هستند |