راهنمای لاگ‌ها

این سند فیلدها، برچسب‌ها و تگ‌های لاگ در پشتهٔ مانیتورینگ روتر را توضیح می‌دهد: هر برچسب/فیلد چیست، چه مقادیری می‌تواند داشته باشد و چطور برای فیلتر و داشبورد از آن استفاده کنید.

نمای کلی و منبع داده

منبع: لاگ‌های سیستم و سرویس روی روتر (مثلاً journal، soolog، لاگ اپلیکیشن)، پردازش و ارسال به سرور مانیتورینگ.
Pipeline: لاگ‌ها روی روتر تگ‌گذاری می‌شوند (مثلاً با نام روتر و سایت). در مدل یکپارچه از طریق Vector به سرور مانیتورینگ می‌روند؛ در مدل فقط لاگ با TCP/UDP به سرور Syslog (دو مدل مانعه‌الجمع).
هدف: جمع‌آوری متمرکز لاگ با برچسب‌های یکسان تا بتوان بر اساس روتر، سایت، سطح، کامپوننت و زمان فیلتر کرد.

تگ‌های اعمال‌شده روی همهٔ لاگ‌ها (سمت روتر)

این تگ‌ها هنگام پردازش، قبل از ارسال به لاگ‌ها اضافه می‌شوند (ر.ک. معرفی و معماری مانیتورینگ).

Label / tag	What it is	Example values	Notes
`monitor_name`	Router identifier (e.g. hostname)	`router-1`, `gns3-tmp`	Identifies which device sent the log.
`monitor_site`	Site or group label	`Default`, `Site-A`	Use for grouping/filtering by location.
`monitor_identifier`	Log source / component	`systemd`, `zebra`	Identifies which service or subsystem produced the log.

در Grafana از متغیرهایی مثل $site و $node برای monitor_site و monitor_name استفاده کنید تا یک داشبورد برای همهٔ روترها و سایت‌ها کار کند.

کوئری لاگ با LogQL در Grafana

لاگ‌هایی که به سرور مانیتورینگ (مثلاً از طریق Loki) می‌رسند را می‌توان در Grafana با LogQL کوئری کرد. از LogQL به دو شکل اصلی استفاده می‌شود: در پنل Logs (برای نمایش خطوط خام یا قالب‌بندی‌شده) یا در پنل Graph (یا time-series) (برای نمایش تعداد یا مقادیر پارس‌شده در زمان).

مبانی LogQL

Label selector — {label="value",...} جریان‌های لاگ را با برچسب انتخاب می‌کند. در این پشته حداقل این‌ها را قرار دهید:
- monitor_site="$site" و monitor_name="$node" (از متغیرهای داشبورد استفاده کنید تا همان کوئری برای هر سایت/نود کار کند).
- monitor_identifier="<source>" برای فیلتر بر اساس منبع لاگ (مثلاً systemd, zebra).
Pipeline stages — بعد از selector می‌توانید اضافه کنید:
- |~ "regex" — فقط خطوطی که بدنه با regex مطابقت دارد نگه داشته می‌شوند.
- | regexp "pattern" — خط لاگ پارس و گروه‌های نام‌دار (مثلاً (?P<name>...)) استخراج می‌شوند.
- | line_format "template" — خروجی با گروه‌های گرفته‌شده قالب‌بندی می‌شود (مثلاً {{.track}}, {{.state}}).
- | unwrap / | count_over_time — برای تبدیل لاگ به عدد در نمودار (پایین را ببینید).

پنل Log (نمایش متن لاگ)

از label selector ساده استفاده کنید تا همهٔ خطوط منطبق به‌صورت متن نمایش داده شوند:

{monitor_site="$site",monitor_name="$node",monitor_identifier="systemd"}

کاربرد: همهٔ خطوط لاگ از سایت و نود انتخاب‌شده که منبع آن‌ها systemd است (مثلاً لاگ‌های systemd/journal) برمی‌گرداند.
در Grafana: یک پنل Logs بسازید، دیتاسورس را Loki قرار دهید و این کوئری را بچسبانید. بازهٔ زمانی را انتخاب کنید؛ نتیجه به‌صورت لیست خطوط لاگ نمایش داده می‌شود.

برای محدودتر کردن می‌توانید روی بدنهٔ لاگ فیلتر اضافه کنید، مثلاً:

{monitor_site="$site",monitor_name="$node",monitor_identifier="zebra"} |~ "error|failed"

این فقط لاگ‌های zebra را نشان می‌دهد که شامل “error” یا “failed” هستند.

پنل Graph (نمایش سری زمانی یا رویدادهای پارس‌شده)

برای نمایش نمودار (مثلاً وضعیت up/down در زمان یا تعداد رویدادها) از همان label selector استفاده می‌کنید و سپس:

شمارش خطوط لاگ در زمان — مثلاً count_over_time(...) برای گرفتن سری زمانی تعداد خطوط منطبق.
پارس و قالب‌بندی خطوط — از | regexp و | line_format استفاده کنید تا هر خط به یک رویداد کوتاه و خوانا تبدیل شود (مثلاً “Track 5 ==> up”); در پنل Logs لیست تمیز به دست می‌آید؛ در برخی مصورسازی‌ها می‌توان روی فیلدهای پارس‌شده تجمیع یا گروه‌بندی کرد.

نمونه: Track up/down در Zebra (پارس و قالب‌بندی برای نمایش)

{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}}"

کاربرد:
- Selector: لاگ‌های Zebra برای سایت و نود انتخاب‌شده.
- |~ "..." — فقط خطوطی شبیه “Track N came up” یا “Track N went down” نگه داشته می‌شوند (بدون حساسیت به حروف، N = ۱–۵ رقم).
- | regexp "..." — شناسهٔ track و وضعیت (up یا down) در گروه‌های نام‌دار track و state ذخیره می‌شوند.
- | line_format "..." — برای هر رویداد یک خط کوتاه خروجی می‌دهد: Track <id> ==> up یا Track <id> ==> down.
در Grafana: این را در پنل Logs برای نمایش لیست تمیز تغییر وضعیت track استفاده کنید. برای نمودار (مثلاً تعداد رویدادهای “up” در برابر “down” در هر بازهٔ زمانی) مرحله‌ای مثل | unwrap روی مقدار عددی یا count_over_time(... [1m]) با نوع کوئری «Range» اضافه کنید؛ گام دقیق به نسخهٔ Loki شما بستگی دارد.

نمونه: تعداد رویدادهای track در زمان (برای نمودار)

برای گرفتن سری زمانی تعداد چنین خطوطی در هر دقیقه (برای پنل نمودار):

count_over_time(
  {monitor_identifier="zebra",monitor_site="$site",monitor_name="$node"}
    |~ "(?i)Track\\s\\d{1,5}\\s(came up|went down)" [1m]
)

از این در پنلی با Query type: Range (یا معادل آن در Grafana/Loki) استفاده کنید. نتیجه یک سری زمانی است که می‌توان نمودار کشید.

مرجع سریع

Goal	Where in Grafana	LogQL idea
Show raw log lines	Logs panel	`{monitor_site="$site",monitor_name="$node",monitor_identifier="systemd"}`
Show filtered lines	Logs panel	Same selector + `\|~ "regex"` or `\| json \| line_format "..."`
Show parsed events	Logs panel	Selector + `\|~ "..."` + `\| regexp "..."` + `\| line_format "..."`
Show a graph	Graph / Time series	Same selector + `count_over_time(... [1m])` or metric extraction

از $site و $node استفاده کنید تا یک داشبورد برای همهٔ سایت‌ها و نودها کار کند.

فیلدها / برچسب‌های متداول لاگ

فیلدهای معمول در رکوردهای لاگ (نام دقیق به منبع لاگ و pipeline بستگی دارد).

Field / label	What it is	Example values	Notes
`level`	Log severity	`info`, `warn`, `error`, `debug`	Filter by severity in dashboards/alerts.
`message`	Log message body	(free text)	Main content of the log line.
`timestamp`	Time of the event	ISO8601 or Unix timestamp	For time-based queries and graphs.
`hostname`	Host that produced the log	`gns3-tmp`, `router-1`	May duplicate or complement monitor_name.
`component`	Subsystem or service	`kernel`, `vpp`, `zebra`, `soolog`	Filter by service.
`unit`	systemd unit name (if from journal)	`soolog.service`, `syslog.socket`	From journal / systemd.
`pid`	Process ID	`1234`	When available from the log source.
`file` / `path`	Source file or path (if applicable)	`/var/log/app.log`	Depends on pipeline configuration.

Soolog و systemd (فرایند / یونیت)

لاگ‌های soolog و systemd بخشی از همان pipeline هستند. شناسه‌های مرتبط:

Label / field	What it is	Example values	Notes
`groupname`	Process group (process-exporter)	`soolog`	Soolog appears as groupname in process metrics.
`name`	systemd unit name	`soolog.service`, `syslog.socket`	From node_systemd_unit_state, socket/timer metrics.
`state`	Unit or process state	`active`, `inactive`, `failed`, `activating`	From systemd; use for service health.
`type`	systemd unit type	`simple`, `socket`	From systemd.

این‌ها به هم‌بستن لاگ (مثلاً از soolog یا journal) با متریک‌ها (مثلاً process_metrics_guide، node_exporter_metrics_guide) کمک می‌کنند.

مراجع

01-introduction (معرفی و معماری مانیتورینگ) — معماری کلی، دو مدل مانعه‌الجمع (یکپارچه یا فقط لاگ با TCP/UDP)، و تگ‌ها (monitor_name، monitor_site).
process_metrics_guide.md — Soolog و سایر گروه‌های فرایند (groupname، متریک‌ها).
node_exporter_metrics_guide.md — وضعیت یونیت systemd و متریک‌های socket (name، state، type).

این راهنما برچسب‌ها و مقادیر لاگ را برای پشتهٔ مانیتورینگ روتر مستند می‌کند.