FA YAML Reference

مرجع YAML

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

همه‌ی کلیدهای pulsecheck.yml با نوع، مقدار پیش‌فرض و قاعده‌شان. توضیح و نمونه‌ی کاربرد را در تنظیمات ببینید. کلید ناشناخته در هر جای فایل خطا است و pulsecheck validate اسم کلید و جای آن را می‌گوید.

قاعده‌های فایل

قاعده	توضیح
مسیر	-c FILE؛ در غیر این صورت ./pulsecheck.yml و بعد ~/.config/pulsecheck/pulsecheck.yml
قالب	YAML. JSON هم قبول می‌شود (Worker کلودفلر JSON می‌گیرد)
${NAME}	در هر مقدار متنی (داخل لیست و mapping هم، اما نه در کلیدها) با متغیر محیطی NAME پر می‌شود. متغیر تنظیم‌نشده خطا است و خط خالی KEY= در .env هم «تنظیم‌نشده» حساب می‌شود. مقدار پیش‌فرض (${X:-y}) پشتیبانی نمی‌شود
.env	اول .env کنار فایل تنظیم خوانده می‌شود (KEY=value؛ توضیح با #؛ کوتیشن و export مجاز است). متغیرهای واقعیِ محیط بر آن غلبه دارند
نوع‌ها	int هم 5 را می‌پذیرد و هم "5" را، اما true را نه. str متن یا عدد می‌پذیرد. لیست باید لیست باشد و mapping باید mapping
mapping درون‌خطی	داخل { ... } مقدارهایی که ${VAR} دارند را در کوتیشن بگذارید: {url: "https://x/${T}"}

سطح اول

کلید	نوع	پیش‌فرض	توضیح
sites	لیست site	الزامی	بررسی‌ها. name باید یکتا باشد
defaults	mapping	{}	هر کلید سایت؛ زیر همه‌ی سایت‌ها ادغام می‌شود. مقدار خود سایت جایگزین آن می‌شود و ادغام عمیق نیست: headers یک سایت، headers پیش‌فرض را کامل کنار می‌زند
notify	notify	بدون آدرس	مقصدهای سراسری هشدار
messages	mapping	متن داخلی	متن هشدارها (messages)
maintenance	لیست maintenance	[]	بازه‌هایی که هشدار در آن‌ها ارسال نمی‌شود
otel	otel	خاموش	خروجی OpenTelemetry
state_file	str	pulsecheck.db	فایل SQLite (فقط CLI). ~ باز می‌شود و مسیر نسبی نسبت به پوشه‌ی فایل تنظیم حساب می‌شود، تا cron هم همان فایل را پیدا کند. روی Vercel و Cloudflare نادیده گرفته می‌شود
shoutrrr_bin	str	auto	auto: اگر docker info کار کند image داکر، وگرنه فایل اجرایی shoutrrr. docker: همیشه image. هر مقدار دیگر: مسیر یک فایل اجرایی. روی Cloudflare نادیده گرفته می‌شود
shoutrrr_image	str	nickfedor/shoutrrr:0.21.2	image در حالت auto و docker

notify

کلید	نوع	پیش‌فرض	توضیح
urls	لیست str	[]	آدرس‌های shoutrrr (اعلان‌ها)
events	لیست str	هر چهار	کدام هشدارها ارسال شود: down، up، degraded، ssl_warn. یادآوری «هنوز down است» جزو down حساب می‌شود

notify سطح سایت، notify سراسری را کامل کنار می‌گذارد، از جمله events آن را.

sites

کلیدهای مشترک همه‌ی نوع‌ها:

کلید	نوع	پیش‌فرض	توضیح
name	str	الزامی	یکتا؛ در هشدار، status و گزارش استفاده می‌شود
type	http | tcp | ping	http	چه چیزی بررسی شود
timeout	int (ثانیه)	10	برای هر بررسی (اتصال، درخواست یا انتظار برای ping)
down_after	int	2	تعداد شکست پشت‌سرهم پیش از آنکه سایت down شود و اولین هشدار برود
interval	int (دقیقه)	5	کمترین فاصله‌ی بین دو بررسی این سایت. اگر آخرین بررسی کمتر از interval دقیقه منهای ۱ دقیقه پیش بوده باشد، اجرا سایت را رد می‌کند (آن یک دقیقه برای تأخیر زمان‌بند است)
max_response_ms	int | null	خاموش	بررسی موفقی که کندتر از این باشد شکست حساب می‌شود
slow_ms	int | null	خاموش	بررسی موفقی که دست‌کم این‌قدر کند باشد degraded است (با تغییر وضعیت، هشدار degraded می‌رود)
remind_every	int (دقیقه)	0 (خاموش)	تا وقتی سایت down است، هشدار (کلید پیام reminder) را هر N دقیقه تکرار کن. کمترین فاصله‌ی هشدارهای گواهی هم هست (پیش‌فرض روزی یک‌بار)
ip_version	4 | 6 | null	پیش‌فرض سیستم	اتصال را فقط روی IPv4 یا IPv6 برقرار می‌کند؛ برای http، tcp، ping و بررسی گواهی. اگر سرور آدرسی از آن خانواده نداشته باشد، سایت down گزارش می‌شود (مثلاً Address family for hostname not supported) و بی‌صدا به خانواده‌ی دیگر برنمی‌گردد. آدرس IPv6 مستقیم بدون این کلید هم کار می‌کند: url: http://[2001:db8::1]/ و host: 2001:db8::1. روی Cloudflare رد می‌شود
tags	لیست str	[]	برچسب برای --tag، و برای {tags} در پیام‌ها و متریک‌ها
notify	notify | null	سراسری	مقصدهای هشدار مخصوص همین سایت
messages	mapping	{}	متن هشدارهای مخصوص همین سایت (بر messages سراسری غلبه دارد)

type: http

کلید	نوع	پیش‌فرض	توضیح
url	str	الزامی	آدرس http:// یا https://
method	str	GET	متد HTTP
headers	mapping (str به str)	{}	هدرهای درخواست
body	str | null	ندارد	بدنه‌ی درخواست (روی Cloudflare برای GET و HEAD نادیده گرفته می‌شود)
expected_status	لیست int	[]	کدهایی که یعنی up. خالی یعنی هر 2xx. اول ریدایرکت‌ها دنبال می‌شوند، پس کد نهایی سنجیده می‌شود
max_redirects	int	5	تعداد ریدایرکتی که دنبال می‌شود (CLI و Vercel؛ روی Cloudflare نادیده گرفته می‌شود)
ssl_warn_days	int | null	خاموش	فقط https. اگر گواهی در کمتر از این تعداد روز منقضی شود هشدار می‌دهد (حداکثر روزی یک‌بار، یا طبق remind_every). گواهی منقضی‌شده بررسی را با TLS certificate has expired شکست می‌دهد. روی Cloudflare در دسترس نیست

type: tcp

کلید	نوع	پیش‌فرض	توضیح
host	str	الزامی	نام سرور یا IP
port	int	الزامی	شماره‌ی پورت. اگر اتصال باز شود یعنی up. روی Cloudflare در دسترس نیست

type: ping

کلید	نوع	پیش‌فرض	توضیح
host	str	الزامی	نام سرور یا IP. دستور ping -c 1 -W <timeout> <host> (iputils لینوکس) اجرا می‌شود. روی Vercel و Cloudflare در دسترس نیست

messages

فقط این کلیدها مجازند و هر کلید دیگری خطا است. کلیدی که ننویسید، متن داخلی خودش را نگه می‌دارد.

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

جانگهدارهای مجاز (غیر از این‌ها خطا است): {site} {event} {error} {ms} {minutes} {status} {tags} {days}. برای نوشتن خود آکولاد از {{ و }} استفاده کنید. اولویت: messages سایت، بعد messages سراسری، بعد متن داخلی.

maintenance

کلید	نوع	پیش‌فرض	توضیح
start	str	الزامی	"HH:MM" (هر روز) یا "DAY HH:MM" با MON TUE WED THU FRI SAT SUN. به وقت UTC
duration	int (دقیقه)	الزامی	می‌تواند از نیمه‌شب رد شود
name	str	maintenance	فقط برچسب
sites	لیست str	[] (همه)	اسم سایت‌هایی که بازه برای آن‌هاست

بررسی‌ها ادامه پیدا می‌کنند و ذخیره می‌شوند، اما هشدارهایی که داخل بازه ساخته شوند (و رکوردهای لاگ OpenTelemetry) دور ریخته می‌شوند و بعداً ارسال نمی‌شوند. متریک‌ها همچنان فرستاده می‌شوند.

otel

کلید	نوع	پیش‌فرض	توضیح
endpoint	str	الزامی	آدرس پایه، مثلاً https://collector:4318. /v1/metrics و /v1/logs به آن اضافه می‌شود
headers	mapping (str به str)	{}	هدرهای اضافه، مثلاً Authorization
service_name	str	pulsecheck	ویژگی resource به اسم service.name
resource	mapping (str به str)	{}	ویژگی‌های بیشتر برای resource
metrics	bool	true	pulsecheck.up، .response_time، .http.status_code و .ssl.days_remaining
logs	bool	true	برای هر هشدار یک رکورد

مقدارها چطور با هم ترکیب می‌شوند

1. نتیجه‌ی یک بررسی ok است اگر ارتباط برقرار شده، کد پاسخ مورد انتظار بوده و کندتر از max_response_ms نبوده باشد.
2. اگر ok باشد و کندتر از slow_ms، وضعیت degraded است؛ اگر ok باشد و کند نباشد up. اگر ok نباشد یک شکست ثبت می‌شود و پس از down_after شکست پشت‌سرهم سایت down می‌شود.
3. هشدار فقط وقتی می‌رود که وضعیت عوض شده باشد (یا زمان یادآوری یا هشدار گواهی رسیده باشد)، بازه‌ی maintenance نباشد و رویدادش در events آمده باشد.

نمونه‌ی کامل

state_file: pulsecheck.db
shoutrrr_bin: auto
shoutrrr_image: nickfedor/shoutrrr:0.21.2

notify:
  urls: ["telegram://${TG_TOKEN}@telegram?chats=${TG_CHAT}", "ntfy://ntfy.sh/${NTFY_TOPIC}"]
  events: [down, up, degraded, ssl_warn]

messages:
  down: "🔴 {site} is DOWN: {error}"
  up: "🟢 {site} recovered after {minutes} min"

otel:
  endpoint: https://otel-collector.example.com:4318
  headers: {Authorization: "Bearer ${OTEL_TOKEN}"}
  resource: {env: prod}

maintenance:
  - {name: weekly, start: "SUN 02:00", duration: 60, sites: [api]}

defaults: {timeout: 10, down_after: 2, interval: 5, slow_ms: 3000, remind_every: 60}

sites:
  - name: web
    url: https://example.com
    expected_status: [200, 301]
    max_response_ms: 10000
    ssl_warn_days: 14
    tags: [prod, web]
  - name: api
    url: https://api.example.com/health
    method: POST
    headers: {Authorization: "Bearer ${API_TOKEN}"}
    body: '{"ping": true}'
    max_redirects: 3
    notify: {urls: ["discord://${DISCORD_TOKEN}@${DISCORD_ID}"], events: [down, up]}
    messages: {down: "💳 api DOWN, page on-call: {error}"}
  - {name: db, type: tcp, host: db.internal, port: 5432, interval: 1}
  - {name: gateway, type: ping, host: 10.0.0.1}

هر پلتفرم چه چیزی را پشتیبانی می‌کند

کلید یا قابلیت	CLI، CI، cron	Vercel	Cloudflare
type: http	بله	بله	بله (max_redirects نادیده گرفته می‌شود)
type: tcp	بله	بله	رد می‌شود
type: ping	بله	رد می‌شود	رد می‌شود
ssl_warn_days	بله	بله	نادیده گرفته می‌شود
ip_version	بله	بله، اگر پلتفرم آن اتصال را داشته باشد (تست نشده)	سایت رد می‌شود
state_file، shoutrrr_bin، shoutrrr_image	بله	نادیده گرفته می‌شود	نادیده گرفته می‌شود
notify.urls	هر آدرس shoutrrr	۱۲ سرویس داخلی، و بقیه با shoutrrr دانلودشده	۱۲ سرویس داخلی
بقیه‌ی کلیدها	بله	بله	بله

ورودی‌های دیگر

اسم	کاربرد
XDG_CONFIG_HOME، XDG_STATE_HOME	محل ساخته‌شدن تنظیمات، وضعیت و لاگ توسط init
VISUAL، EDITOR	ویرایشگر pulsecheck env
CRON_SECRET	Vercel: توکن bearer برای /api/cron و /api/status
STATUS_TOKEN	Cloudflare: توکن bearer برای /status و /run
KV_REST_API_URL و KV_REST_API_TOKEN (یا UPSTASH_REDIS_REST_URL و UPSTASH_REDIS_REST_TOKEN)	ذخیره‌ساز وضعیت در Vercel
PULSECHECK_SOURCE	install.sh: چیزی که uv tool install نصب می‌کند

کدهای خروج

دستور	۰	۱
run	تمام شد	با --fail-on-down: دست‌کم یک سایت down است
validate	معتبر است	shoutrrr یکی از آدرس‌های هشدار را رد کرد (خطای تنظیمات هم با یک پیام متوقف می‌شود)
test-notify	همه‌ی کانال‌ها کار کردند	دست‌کم یکی شکست خورد یا چیزی تنظیم نشده
update	انجام شد یا نسخه‌ی فعلی به‌روز است	دستور ارتقا شکست خورد