Heartbeat و وب‌هوک خطا
دو مانیتور که سیستم خودتان صدا می‌زند: «هنوز زنده‌ام» (Heartbeat) و «خطا رخ داد» (وب‌هوک خطا).
کدام را انتخاب کنم؟
| Heartbeat | وب‌هوک خطا | |
|---|---|---|
| منطق | سکوت = مشکل | صدا = مشکل |
| چه کسی صدا می‌زند؟ | سیستم شما، به‌طور منظم، وقتی همه‌چیز سالم است | سیستم شما، فقط وقتی خطایی رخ داد |
| مثال | بکاپ شبانه، cron، worker صف | catch در کد، خطای پرداخت، job شکست‌خورده |
| کی «قطع» می‌شود؟ | اگر تا ۲ برابر فاصله پینگی نیاید | به‌محض رسیدن یک گزارش |
| کی برطرف می‌شود؟ | با اولین پینگ | اگر به‌اندازه‌ی فاصله گزارش تازه‌ای نیاید |
آدرس هرکدام در صفحه‌ی خود مانیتور (کارت «تنظیمات و سیاست») نوشته شده؛ هر دو درخواست POST هستند، احراز هویت ندارند و خودِ شناسه‌ی مانیتور نقش کلید را بازی می‌کند. پس آن را جایی عمومی (مثلاً مخزن کد باز) نگذارید.
لازم نیست دستور را خودتان بنویسید: همان کارت، نمونه‌کد آماده‌ی همین مانیتور را با آدرس خودش دارد؛ برای Heartbeat: cron، bash، Python، Node.js و PowerShell، و برای وب‌هوک: curl، bash، Python، Node.js و PHP. تب زبان را انتخاب کنید و با دکمه‌ی کپی در اسکریپت‌تان بگذارید.
Heartbeat
مانیتور را از نوع «Heartbeat (پینگ دوره‌ای شما)» بسازید و «حداکثر فاصله‌ی مورد انتظار بین پینگ‌ها» را بدهید. بعد سیستم شما باید حداقل هر همین مقدار یک‌بار صدا بزند:
POST https://statly.ir/api-backend/heartbeat/<MONITOR_ID>/ping
- پاسخ موفق
204است و بدنه لازم نیست. شناسه‌ی نامعتبر404می‌دهد. - هر ۳۰ ثانیه بررسی می‌کنیم: اگر آخرین پینگ از دو برابر فاصله قدیمی‌تر بود، مانیتور «قطع» می‌شود. یعنی با فاصله‌ی ۵ دقیقه، بعد از حدود ۱۰ تا ۱۱ دقیقه سکوت قطعی باز می‌شود. مانیتور تازه‌ساخته هم اگر پینگ نخورد، بعد از دو برابر فاصله قطع می‌شود.
- با اولین پینگ بعد از قطعی، مانیتور «فعال» و قطعی بسته می‌شود.
- مانیتور «توقف موقت» شده بررسی نمی‌شود.
نمونه‌ی Heartbeat
# فقط اگر بکاپ موفق بود پینگ می‌زنیم 0 3 * * * /opt/backup.sh && curl -fsS -m 10 -X POST https://statly.ir/api-backend/heartbeat/<MONITOR_ID>/ping
وب‌هوک خطا
مانیتور را از نوع «وب‌هوک خطا (گزارش خودتان)» بسازید. «حداکثر سکوت قبل از resolve خودکار» را مشخص کنید. هر بار کد شما خطایی تشخیص داد، گزارش بدهد:
POST https://statly.ir/api-backend/error-reports/<MONITOR_ID>/report
- بدنه اختیاری است:
{"message": "...", "source": "..."}(message تا ۲۰۰۰ و source تا ۲۰۰ نویسه) و می‌تواند هر فیلد دیگری هم داشته باشد (مجموع تا ۴ کیلوبایت JSON). پاسخ موفق204است؛ بدنه‌ی نامعتبر یا بزرگ‌تر از ۴ کیلوبایت400. - اولین گزارش، مانیتور را «قطع» و یک قطعی باز می‌کند؛ هشدار طبق سیاست می‌رود.
- گزارش‌های بعدی تا وقتی قطعی باز است فقط به تاریخچه‌ی همان قطعی اضافه می‌شوند — هشدار تکراری نمی‌رود؛ آخرین بدنه برای پر کردن متغیرهای «قالب پیام» سیاست نگه داشته می‌شود (قالب‌های پیام).
- اگر به‌اندازه‌ی «حداکثر سکوت» هیچ گزارش تازه‌ای نیاید، قطعی خودکار برطرف می‌شود (و اگر سیاست بازیابی را خواسته باشد، پیام بازیابی می‌رود). مانیتور وب‌هوکی که اصلاً گزارشی نمی‌گیرد، هرگز «قطع» نمی‌شود: سکوت یعنی سالم.
نمونه‌ی وب‌هوک خطا
curl -X POST https://statly.ir/api-backend/error-reports/<MONITOR_ID>/report \
-H "Content-Type: application/json" \
-d '{"message":"payment gateway timeout","source":"checkout-service"}'نکته‌ها
- آدرس‌ها را از صفحه‌ی مانیتور کپی کنید؛ آدرس دقیق نصب شما همان‌جا نوشته شده (نمونه‌ها در این صفحه با
<MONITOR_ID>نشان داده شده‌اند). - وب‌هوک خطا مثل بقیه‌ی مانیتورها ۱ واحد از سقف پلن مصرف می‌کند؛ Heartbeat ۰ واحد.
- می‌خواهید به‌جای ثبت «قطعی»، مستقیم یک پیامک یا تماس بفرستید؟ آن کار «کلید فراخوانی» است: راهنمای پیامک و تماس سفارشی.
- هر دو نوع از سیاست هشدار و ذخیره‌ی تاریخچه‌ی قطعی مثل مانیتورهای عادی استفاده می‌کنند و در صفحه‌ی وضعیت هم قابل نمایش‌اند.