راهنمای مختصر PromQL و LogQL

سند کوتاهی برای آشنایی با زبان‌های کوئری Prometheus (PromQL) و Loki (LogQL) در پشتهٔ مانیتورینگ. با خواندن این سند می‌توانید مفهوم کوئری، نوع داده‌ها و عملگرهای پرکاربرد را درک کنید و برای جزئیات کامل به مستندات رسمی مراجعه کنید.

فهرست

PromQL
LogQL
مستندات رسمی

PromQL

PromQL (Prometheus Query Language) زبان کوئری متریک‌های Prometheus است. با آن می‌توانید سری‌های زمانی را انتخاب، فیلتر و تجمیع کنید و در Grafana به‌صورت نمودار یا جدول نمایش دهید.

نوع کوئری

Instant query — در یک نقطهٔ زمانی ارزیابی می‌شود؛ نتیجهٔ آن یک مقدار (یا چند سری) برای همان لحظه است. در Grafana برای جدول یا مقدار فعلی استفاده می‌شود.
Range query — در بازهٔ زمانی و با گام‌های مشخص چند بار ارزیابی می‌شود؛ برای نمودار زمانی مناسب است.

نوع دادهٔ عبارت (Expression)

نتیجهٔ یک عبارت PromQL می‌تواند یکی از این‌ها باشد:

نوع	توضیح کوتاه
Instant vector	مجموعهٔ سری‌های زمانی، هر کدام با یک نمونه در یک زمان مشخص (مثلاً خروجی `rate(...)` یا انتخابگر با برچسب).
Range vector	مجموعهٔ سری‌های زمانی، هر کدام با چند نمونه در یک بازهٔ زمانی (مثلاً `metric[5m]`). مستقیماً در نمودار نمایش داده نمی‌شود؛ معمولاً داخل توابعی مثل `rate()` استفاده می‌شود.
Scalar	یک عدد (مثلاً نتیجهٔ `sum(...)` بدون برچسب).
String	رشته؛ در عمل کمتر به‌کار می‌آید.

برای نمودار در Grafana معمولاً به instant vector (مثلاً بعد از rate() یا sum()) نیاز دارید.

انتخابگر سری زمانی (Time series selector)

انتخابگر آنی (Instant vector selector): نام متریک و در صورت نیاز برچسب‌ها داخل {}.

# همهٔ سری‌های با این نام متریک
node_cpu_seconds_total

# فیلتر با برچسب (برابر دقیق)
node_cpu_seconds_total{job="node",mode="idle"}

# چند مقدار برای یک برچسب (regex)
node_cpu_seconds_total{mode=~"idle|user|system"}

# ناهمخوان با مقدار
node_cpu_seconds_total{job!="test"}

عملگرهای تطبیق برچسب:

عملگر	معنی
`=`	برابر با مقدار
`!=`	مخالف مقدار
`=~`	مطابق عبارت باقاعده (regex)
`!~`	نامطابق با regex

در این پشتهٔ مانیتورینگ معمولاً از برچسب‌هایی مثل monitor_name (روتر) و monitor_site (سایت) استفاده می‌کنید؛ مثلاً node_cpu_seconds_total{monitor_site="$site",monitor_name="$node"}.

انتخابگر بازه‌ای (Range vector selector): با اضافه کردن [مدت] به انتخابگر آنی، نمونه‌های آن متریک در بازهٔ گذشته را می‌گیرید. این خروجی نوع range vector است و معمولاً مستقیماً برای نمودار استفاده نمی‌شود؛ داخل توابعی مثل rate() یا increase() قرار می‌گیرد.

# نمونه‌های ۵ دقیقهٔ اخیر
node_cpu_seconds_total{job="node"}[5m]

واحدهای مدت: s (ثانیه)، m (دقیقه)، h (ساعت)، d (روز)، w (هفته). مثلاً [5m] یعنی ۵ دقیقه، [1h] یعنی ۱ ساعت.

توابع پرکاربرد

تابع	ورودی معمول	خروجی	کاربرد
`rate(metric[5m])`	range vector	instant vector	نرخ افزایش در ثانیه (برای counterها؛ مناسب نمودار).
`increase(metric[5m])`	range vector	instant vector	افزایش کل در آن بازه.
`sum(...)`, `avg(...)`	instant vector	scalar یا instant vector	جمع یا میانگین؛ با `by (label)` یا `without (label)` گروه‌بندی می‌کنید.
`by (label)`	همراه تجمیع	گروه‌بندی بر اساس برچسب	مثلاً `sum by (instance) (rate(...))` — یک سری به ازای هر `instance`.
`without (label)`	همراه تجمیع	حذف برچسب از گروه‌بندی	مثلاً `sum without (cpu) (rate(node_cpu_seconds_total[5m]))`.

نمونه برای نمودار استفادهٔ CPU (درصد): نرخ ثانیه‌ای CPU را با rate می‌گیریم، با by (mode) یا بدون آن جمع/میانگین می‌کنیم و در صورت نیاز در ۱۰۰ ضرب می‌کنیم. مثال ساده برای یک روتر:

rate(node_cpu_seconds_total{monitor_site="$site",monitor_name="$node"}[5m])

یا برای درصد idle به‌تفکیک حالت (با فرض چند CPU):

100 - (sum by (mode) (rate(node_cpu_seconds_total{monitor_site="$site",monitor_name="$node",mode="idle"}[5m])) * 100 / count without (cpu,mode) (node_cpu_seconds_total{monitor_site="$site",monitor_name="$node"}))

در عمل می‌توان از الگوهای آمادهٔ داشبورد یا مستندات متریک‌ها (مثل node_exporter_metrics_guide) استفاده کرد.

نکات مهم PromQL

Counter و Gauge: متریک‌های counter (مثل node_cpu_seconds_total) همیشه افزایشی‌اند؛ برای نمودار معمولاً rate() یا increase() استفاده می‌کنید. متریک‌های gauge (مثل حافظهٔ آزاد) را مستقیم یا با avg() نمایش می‌دهید.
Staleness: اگر هدف (target) دیگر نمونه نفرستد، سری زمانی بعد از مدتی «منقضی» می‌شود و در نتیجهٔ کوئری ظاهر نمی‌شود.
کوئری سنگین: انتخابگرهای خیلی گسترده (مثلاً فقط نام متریک بدون فیلتر) یا تجمیع روی هزاران سری می‌تواند سرور یا مرورگر را تحت فشار قرار دهد. بهتر است ابتدا در نمای جدولی نتیجه را محدود کنید، بعد به نمودار بروید. مستندات رسمی Prometheus این موضوع را در بخش Querying basics توضیح می‌دهد.

در Grafana معمولاً PromQL را در پنل‌های Time series (نمودار) یا Table با دیتاسورس Prometheus استفاده می‌کنید.

LogQL

LogQL زبان کوئری لاگ‌های Loki است. ساختار آن شبیه PromQL است: ابتدا جریان لاگ را با انتخابگر برچسب مشخص می‌کنید، سپس در صورت نیاز مراحل خط لوله (pipeline) مثل فیلتر، پارس یا تجمیع اضافه می‌کنید.

انتخابگر جریان لاگ (Log stream selector)

جریان لاگ با برچسب‌ها داخل {} انتخاب می‌شود. در این پشته معمولاً از monitor_site، monitor_name و monitor_identifier (منبع لاگ، مثلاً systemd یا zebra) استفاده می‌کنید.

{monitor_site="$site",monitor_name="$node"}
{monitor_site="$site",monitor_name="$node",monitor_identifier="systemd"}
{monitor_site="$site",monitor_name="$node",monitor_identifier=~"zebra|sshd"}

عملگرهای تطبیق برچسب همان PromQL هستند: =, !=, =~, !~.

خط لوله (Pipeline)

بعد از انتخابگر می‌توانید با | مرحلهٔ بعدی را اضافه کنید:

مرحله	نمونه	کاربرد
فیلتر با regex	`\|~ "error\|failed"`	فقط خطوطی که با عبارت باقاعده مطابقت دارند.
پارس با regex و گروه نام‌دار	`\| regexp "Track (?P<track>.) . (?P<state>up\|down)$"`	استخراج فیلد برای استفاده در `line_format` یا نمودار.
قالب خروجی	`\| line_format "Track {{.track}} ==> {{.state}}"`	نمایش خط با فیلدهای استخراج‌شده.

نمونهٔ کامل: لاگ‌های zebra را برای یک روتر بگیر، فقط خطوط مربوط به Track up/down را نگه دار، فیلدها را استخراج و قالب‌بندی کن:

{monitor_identifier="zebra",monitor_site="$site",monitor_name="$node"} |~ "(?i)Track\\s\\d{1,5}\\s(came up|went down)" | regexp "Track (?P<track>.*) .* (?P<state>up|down)$" | line_format "Track {{.track}} ==> {{.state}}"

تجمیع بازه‌ای (Range aggregation)

برای نمودار بر اساس لاگ (مثلاً تعداد خط در هر دقیقه) از range aggregation استفاده می‌کنید. ساختار: انتخابگر به‌همراه [مدت] و تابع تجمیع، مثلاً count_over_time(... [1m]).

count_over_time({monitor_site="$site",monitor_name="$node",monitor_identifier="systemd"}[1m])

این عبارت تعداد خطوط لاگ را در هر بازهٔ ۱ دقیقه برمی‌گرداند و در پنل Time series با دیتاسورس Loki به‌صورت نمودار قابل نمایش است.

نوع کوئری در Grafana

Instant: برای پنل Logs — لیست خطوط لاگ در یک نقطهٔ زمانی.
Range: برای پنل Time series وقتی از count_over_time(... [1m]) یا مشابه استفاده می‌کنید — نمودار تعداد رویداد در زمان.

در Grafana معمولاً LogQL را در پنل Logs (متن لاگ) یا Time series (نمودار از روی تجمیع لاگ) با دیتاسورس Loki استفاده می‌کنید.

مستندات رسمی

برای جزئیات کامل نحو، توابع، عملگرها و بهترین روش‌ها به مستندات رسمی مراجعه کنید:

PromQL (Prometheus):
- Querying basics — مبانی کوئری، نوع داده‌ها، انتخابگرها، مدت‌ها و نکات مهم.
- Operators — عملگرهای PromQL.
- Functions — توابع PromQL.
LogQL (Loki):
- LogQL reference — مرجع نحو و قابلیت‌های LogQL (انتخابگر، pipeline، توابع).
- Grafana Loki documentation — مستندات کلی Loki.

با این لینک‌ها می‌توانید به‌روزترین توضیحات و نمونه‌های بیشتر را در منبع اصلی مطالعه کنید.