Skip to content

FA Configuration

Jump to bottom
Arian Omrani edited this page Oct 11, 2026 · 8 revisions

تنظیمات

زبان: English · فارسی

نوع و مقدار پیش‌فرض هر کلید در مرجع YAML آمده است؛ این صفحه توضیح می‌دهد کلیدها چطور با هم کار می‌کنند. فایل پیش‌فرض pulsecheck.yml است و با -c عوض می‌شود. هر ${NAME} داخل یک مقدار با متغیر محیطی NAME پر می‌شود و اگر آن متغیر تنظیم نشده باشد خطا می‌گیرید. پس رمز و توکن را مستقیم در فایل ننویسید.

داخل mappingهای درون‌خطی { ... } مقدارهایی که ${VAR} دارند باید در کوتیشن باشند: {name: api, url: "https://x.example.com/${TOKEN}"}.

state_file: pulsecheck.db
shoutrrr_bin: auto
notify:
  urls: ["telegram://${TG_TOKEN}@telegram?chats=${TG_CHAT}"]
  events: [down, up, degraded]
defaults: {timeout: 10, down_after: 2, interval: 5, slow_ms: 3000}
maintenance:
  - {name: weekly, start: "SUN 02:00", duration: 60, sites: [api]}
sites:
  - {name: web, url: https://example.com}

سطح اول

کلید پیش‌فرض توضیح
state_file pulsecheck.db فایل SQLite برای وضعیت فعلی و تاریخچه‌ی بررسی‌ها (۴۰۰ روز نگه داشته می‌شود)
shoutrrr_bin auto auto (اگر Docker کار کند image داکر، وگرنه فایل اجرایی shoutrrr)، docker، یا مسیر یک فایل اجرایی
shoutrrr_image nickfedor/shoutrrr:0.21.2 image داکر در حالت auto و docker
notify ندارد مقصدهای سراسری هشدار (پایین‌تر توضیح داده شده)
defaults {} هر کلید سایت؛ به همه‌ی سایت‌ها اضافه می‌شود و مقدار خود سایت بر آن غلبه دارد
messages متن داخلی متن هشدارها بر اساس کلید (بخش «پیام‌ها» در همین صفحه)
otel ندارد ارسال نتایج به OpenTelemetry (بخش «OpenTelemetry» در همین صفحه)
maintenance [] بازه‌هایی که در آن‌ها هشدار ارسال نمی‌شود
sites الزامی فهرست بررسی‌ها؛ name باید یکتا باشد

کلیدهای هر سایت

کلید پیش‌فرض مناسب برای توضیح
name الزامی همه نام یکتا، در هشدار و گزارش استفاده می‌شود
type http همه http، tcp یا ping
url – http آدرس کامل (الزامی)
host – tcp، ping نام سرور یا IP (الزامی)
port – tcp شماره‌ی پورت (الزامی)
method GET http متد HTTP
headers {} http هدرهای درخواست
body – http بدنه‌ی درخواست (متن)
expected_status هر 2xx http فهرستی مثل [200, 301]
max_redirects 5 http حداکثر ریدایرکتی که دنبال می‌شود
max_response_ms خاموش همه پاسخ کندتر از این مقدار شکست حساب می‌شود
slow_ms خاموش همه پاسخ موفقِ کندتر از این مقدار degraded است
timeout 10 همه به ثانیه
down_after 2 همه تعداد شکست پشت‌سرهم پیش از down شدن
interval 5 همه فاصله‌ی بررسی‌ها به دقیقه (پایین‌تر توضیح داده شده)
tags [] همه برچسب آزاد، مثل [prod, db]؛ برای --tag و به‌صورت {tags} در پیام‌ها
ssl_warn_days خاموش http وقتی گواهی https در کمتر از این تعداد روز منقضی می‌شود هشدار بده؛ گواهی منقضی‌شده شکست حساب می‌شود. روی Cloudflare در دسترس نیست
remind_every 0 (خاموش) همه فاصله‌ی دقیقه‌ای هشدارهای تکراری «هنوز down است»؛ فاصله‌ی هشدارهای تکراری گواهی را هم تعیین می‌کند
notify سراسری همه notify سراسری را فقط برای همین سایت عوض می‌کند
messages سراسری همه متن پیام‌ها را فقط برای همین سایت عوض می‌کند

وضعیت و هشدار

  • بررسی موفق یعنی up؛ اگر دست‌کم slow_ms طول کشیده باشد degraded.
  • بررسی ناموفق تا وقتی down_after بار پشت‌سرهم تکرار نشود سایت را down نمی‌کند، پس قطع‌های کوتاه هشدار نمی‌سازند.
  • هشدار فقط وقتی وضعیت عوض شود می‌رود: down، degraded یا up (بازگشت؛ پیام می‌گوید مشکل چند دقیقه طول کشیده).
  • events تعیین می‌کند کدام‌یک از down، up، degraded و ssl_warn ارسال شود. یادآوری «هنوز down است» جزو down حساب می‌شود. notify سطح سایت، notify سراسری را کامل کنار می‌گذارد، از جمله events آن را.
  • اگر ارسال هشدار شکست بخورد (برنامه پیدا نشود، آدرس غلط باشد) خطا در stderr چاپ می‌شود، ولی اجرا ادامه پیدا می‌کند.

یادآوری و گواهی

  • با remind_every: 60 تا وقتی سایت down است، هر ۶۰ دقیقه پیام reminder می‌آید. با 0 (پیش‌فرض) فقط اولین هشدار down ارسال می‌شود.
  • ssl_warn_days: 14 در هر بررسی گواهی https را می‌خواند. اگر کمتر از ۱۴ روز مانده باشد هشدار ssl_warn می‌آید، حداکثر روزی یک‌بار (یا هر remind_every دقیقه، اگر تنظیم کرده باشید). گواهی منقضی‌شده بررسی را با پیام TLS certificate has expired شکست می‌دهد و مثل یک down عادی رفتار می‌شود.
  • کلید ناشناخته در هر جای فایل خطا است، پس validate غلط‌های املایی را پیدا می‌کند.

IPv4 و IPv6

به‌طور پیش‌فرض سیستم‌عامل خانواده‌ی آدرس را انتخاب می‌کند. اگر می‌خواهید عمداً یک خانواده را بسنجید، روی سایت ip_version بگذارید:

sites:
  - {name: web-v4, url: "https://example.com", ip_version: 4}
  - {name: web-v6, url: "https://example.com", ip_version: 6}   # اگر سرور رکورد AAAA نداشته باشد یا IPv6 در دسترس نباشد، down می‌شود
  - {name: dns-v6, type: tcp, host: "2001:4860:4860::8888", port: 53}   # آدرس IPv6 مستقیم به ip_version نیاز ندارد
  - {name: gateway-v6, type: ping, host: gw.example.com, ip_version: 6}  # دستور `ping -6` اجرا می‌شود

این کلید برای http، tcp، ping و بررسی گواهی (ssl_warn_days) کار می‌کند. اگر برای یک سرور دو ورودی بگذارید، یکی برای هر خانواده، می‌فهمید مشکل از کدام طرف است. اگر ماشینی که pulsecheck روی آن اجرا می‌شود مسیر IPv6 نداشته باشد، سایتِ ip_version: 6 down گزارش می‌شود و خطا دلیلش را می‌گوید (Network is unreachable، Address family for hostname not supported یا Name or service not known). Cloudflare Workers نمی‌تواند خانواده را انتخاب کند، برای همین این سایت‌ها آنجا رد می‌شوند.

برچسب و وضعیت

به سایت‌ها tags: [prod] بدهید و دستورها را با --tag prod محدود کنید (run، status، report). pulsecheck status وضعیت فعلی همه‌ی سایت‌ها را چاپ می‌کند: با --json برای اسکریپت، با --md برای جدول مارک‌دان (مثلاً برای نوشتن در $GITHUB_STEP_SUMMARY). داشبوردی وجود ندارد و جای آن همین دستور است. روی Vercel همین اطلاعات در GET /api/status و روی Cloudflare در GET /status است و هر دو توکن می‌خواهند (سرورلس).

فاصله‌ی بررسی (interval)

اینکه pulsecheck هر چند دقیقه اجرا شود را زمان‌بند (cron یا CI) تعیین می‌کند. interval فقط سایت‌هایی را که تازه بررسی شده‌اند رد می‌کند. مثلاً اجرا را هر ۵ دقیقه بگذارید و برای یک بررسی سنگین interval: 60 بدهید تا ساعتی یک‌بار انجام شود. یک دقیقه هم برای تأخیر زمان‌بند کم می‌شود، بنابراین interval: 5 با زمان‌بندی ۵ دقیقه‌ای در هر اجرا بررسی می‌شود.

بازه‌ی نگهداری (maintenance)

زمان‌ها به UTC هستند. start یا به شکل "HH:MM" است (هر روز) یا "DAY HH:MM" با MON TUE WED THU FRI SAT SUN. duration به دقیقه است و می‌تواند از نیمه‌شب رد شود. اگر sites خالی باشد بازه برای همه‌ی سایت‌هاست. بررسی‌ها انجام و ذخیره می‌شوند، ولی هشدارهای داخل بازه دور ریخته می‌شوند و بعداً فرستاده نمی‌شوند.

پیام‌ها

هر متن هشدار یک کلید دارد. کد فقط از همین کلیدها استفاده می‌کند و هرکدام را می‌توانید زیر messages: عوض کنید، چه سراسری و چه فقط برای یک سایت. کلیدی که ننویسید همان متن داخلی را نگه می‌دارد.

کلید زمان ارسال متن داخلی
down سایت down شد 🔴 {site} is DOWN: {error}
degraded سایت بالاست ولی کند است 🟡 {site} is slow ({ms}ms)
up سایت برگشت 🟢 {site} is UP ({ms}ms) after {minutes}m
reminder بعد از remind_every هنوز down است 🔴 {site} is still DOWN after {minutes}m: {error}
ssl_warn گواهی نزدیک انقضاست 🔒 {site}: TLS certificate expires in {days} days
test pulsecheck test-notify pulsecheck test notification

جانگهدارها: {site} نام سایت، {event} (down، degraded یا up)، {error} دلیل شکست (در حالت موفق خالی)، {ms} زمان پاسخ، {minutes} دقیقه‌های گذشته از آخرین تغییر وضعیت، {status} کد وضعیت HTTP (برای tcp و ping خالی)، {tags} برچسب‌های سایت با کاما، {days} روزهای مانده تا انقضای گواهی (فقط در ssl_warn). برای نوشتن خود آکولاد از {{ و }} استفاده کنید. کلید یا جانگهدار ناشناخته را validate رد می‌کند. اولویت: messages سایت، بعد messages سراسری، بعد متن داخلی.

messages:
  down: "ALERT {site} unreachable ({error})"
  up: "{site} recovered after {minutes} min"
sites:
  - name: payments
    url: https://pay.example.com
    messages: {down: "💳 payments DOWN, page on-call"}

OpenTelemetry

با otel: نتیجه‌ی هر اجرا به یک OpenTelemetry collector می‌رود، یا به هر سرویسی که OTLP/HTTP JSON بپذیرد؛ یعنی عملاً مثل یک وب‌هوک. به بسته‌ی OpenTelemetry نیازی نیست و روی همه‌ی پلتفرم‌ها کار می‌کند.

otel:
  endpoint: https://otel-collector.example.com:4318   # /v1/metrics و /v1/logs خودکار اضافه می‌شود
  headers: {Authorization: "Bearer ${OTEL_TOKEN}"}
  resource: {env: prod}        # ویژگی‌های اضافه‌ی resource؛ service.name به‌طور پیش‌فرض "pulsecheck" است
  # service_name: pulsecheck
  # metrics: true              # برای هر بررسی: pulsecheck.up (۱ یا ۰)، .response_time (ms)، .http.status_code، .ssl.days_remaining
  # logs: true                 # برای هر هشدار یک رکورد لاگ (ERROR برای down، WARN برای کندی و گواهی، INFO برای بازگشت)

ویژگی‌های هر متریک: site، type، state (up، down یا degraded) و tags. اگر ارسال شکست بخورد، خطا در stderr چاپ می‌شود و اجرا خراب نمی‌شود. pulsecheck test-notify یک رکورد لاگ آزمایشی به endpoint می‌فرستد.

گزارش

pulsecheck report برای یک روز، هفته، ماه و سال اخیر این‌ها را نشان می‌دهد: درصد آپتایم، میانگین و p95 زمان پاسخ بررسی‌های موفق، و تعداد بررسی‌ها. --json همین داده را برای اسکریپت چاپ می‌کند. روی Vercel و Cloudflare فقط جمع روزانه ذخیره می‌شود، بنابراین گزارش آن‌ها p95 ندارد و ۹۰ روز اخیر را پوشش می‌دهد.

Clone this wiki locally