راهنمای ARQL: زبان کوئری آروان‌کلاد

ARQL یا Arvancloud Query Language، یک زبان کوئری اختصاصی بر پایه‌ی منطق بولی (Boolean) است. این زبان به شما امکان می‌دهد با ترکیب شرط‌های مختلف، از میان حجم انبوه داده‌ها، لاگ‌های مورد نظر خود را با دقت بالا جست‌وجو، فیلتر و تحلیل کنید.

ویژگی‌های کلیدی ARQL:

• منطق ساده: ساختار عبارات مشابه منطق ریاضی و برنامه‌نویسی است.
• عدم حساسیت به حروف (Case Insensitivity): به‌جز در موارد استفاده از Regex، این زبان نسبت به بزرگی و کوچکی حروف حساس نیست.
• انعطاف‌پذیری: پشتیبانی از فیلدهای تودرتو (Nested Fields) و عملگرهای متنوع.

ساختار و قواعد نگارشی

هر کوئری در ARQL از ترکیب یک یا چند «عبارت شرطی» ساخته می‌شود. ساختار استاندارد هر عبارت به‌شکل زیر است:

<field> <comparison_operator> <value>

که در آن:

• field: یک فیلد در لاگ (مانند resource.type)

• comparison_operator: یک عملگر مقایسه‌ای (مانند ==, !=, =~)

• value: مقدار مورد نظر (مانند "iaasServer")

است. برای نمونه:

resource.type == "iaasServer"

یا

resource.type == "iaasServer" AND ((severity == "ERROR") OR (severity == "error"))

یا

resource.type == "iaasServer" AND
severity != "ERROR" AND
payload.errorText !~ "^apache"

این کوئری تمام لاگ‌هایی را که مربوط به سرور ابری است و سطح severity آن‌ها برابر با "ERROR" نیست و پیام آن‌ها با کلمه "apache" شروع نمی‌شود را برمی‌گرداند.

عملگرهای مقایسه‌ای (Comparison Operators)

این عملگرها رابطه‌ی بین یک فیلد و یک مقدار را تعیین می‌کنند:

عملگر	توضیح
==	مساوی بودن دقیق
!=	نامساوی بودن
=~	تطبیق با الگوی Regex
!~	تطبیق نداشتن با الگوی Regex
> , >=	بزرگ‌تر / بزرگ‌تر یا مساوی
< , <=	کوچک‌تر / کوچک‌تر یا مساوی
IN	عضویت در یک مجموعه (Set)

برای نمونه:

• یافتن مقادیر خالی: jsonPayload.field = NULL_VALUE
• حذف مقادیر خالی: NOT jsonPayload.field = NULL_VALUE

عملگرهای منطقی (Boolean Operators)

برای ترکیب چند شرط با یک‌دیگر از عملگرهای زیر استفاده می‌شود:

عملگر	توضیح	اولویت اجرا
NOT یا -	نقیض شرط (شرط برقرار نباشد)	۱ (بالاترین)
OR	یا (برقراری حداقل یکی از شرط‌ها)	۲
AND	و (برقراری تمام شرط‌ها)	۳

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

نمونه:

resource.type == "iaasServer" AND (severity == "ERROR" OR severity == "CRITICAL")

شناساگر فیلدها (Field Identifiers)

برای دسترسی به داده‌ها، از مسیر (Path) دقیق فیلد استفاده می‌شود. این مسیرها معمولن با نقطه (dot-separated) از هم جدا می‌شوند.

برای نمونه:

فیلد	توضیح
resource.type	نوع منبع (مانند iaasServer یا cdnDomain)
resource.labels.zone	منطقه‌ی جغرافیایی که منبع در آن قرار دارد
resource.labels.project_id	شناسه‌ی پروژه‌ای که لاگ متعلق به آن است
insertId	شناسه‌ی یکتا و منحصربه‌فرد هر لاگ
jsonPayload.httpRequest.protocol	پروتکل استفاده‌شده در درخواست (مانند HTTP/1.1)
"payload.http."request/resource_id	فیلد حاوی کاراکتر خاص (مانند /)

اگر بخشی از مسیر فیلد حاوی کاراکترهای خاص (مانند / یا فاصله) باشد، حتمن باید آن بخش را داخل دبل‌کوتیشن (" ") قرار دهید تا به‌درستی شناسایی شود.

انواع مقادیر (Values)

مقدارهایی که در شرط‌های خود برای مقایسه از آن‌ها استفاده می‌کنید، می‌توانند شامل انواع زیر باشند:

نوع مقدار	مثال	کاربرد
رشته (String)	"iaasServer"	مقادیر متنی که حتمن باید داخل " " باشند.
عدد (Number)	404, 1.2	مقادیر عددی (صحیح یا اعشاری)
مقدار خاص	NULL_VALUE	برای بررسی وجود یا نبود یک فیلد (مقادیر تهی)
Regex	"$foo.*bar^"	الگوهای عبارات منظم برای جست‌وجوهای پیچیده

جست‌وجو با عبارات منظم (Regex)

ARQL از عملگرهای ~= (تطبیق) و ~! (نداشتن تطبیق) برای کار با الگوهای Regex پشتیبانی می‌کند.

مثال‌های کاربردی Regex

۱. تطبیق با رشته ساده:

jsonPayload.message =~ "timeout"

لاگ‌هایی که پیام آن‌ها شامل کلمه timeout باشد

۲. جست‌وجوی بدون حساسیت به حروف:

labels.subnetwork_name =~ "(?i)foo"

تطبیق با هر حالتی از حروف مانند FOO یا Foo

۳. تطبیق شامل علامت نقل قول:

jsonPayload.message =~ "field1=\"bar.*\""

برای درج نقل قول درون regex باید از \ استفاده شود

۴. استفاده از ^ و $:

شروع با مقدار خاص:

logName =~ "^foo"

پایان با مقدار خاص:

logName =~ "foo$"

۵. بررسی نداشتن تطابق:

labels.pod_name !~ "test-.*"

لاگ‌هایی که pod_name آن‌ها با -test شروع نمی‌شود

۶. ترکیب Boolean:

labels.env =~ ("^prod.*server" OR "^staging.*server")

مثال‌های واقعی از کوئری‌ها

در این بخش چند نمونه کوئری کاربردی آورده شده که می‌تواند برای بررسی سریع لاگ‌ها در سناریوهای مختلف مفید باشد.

• مشاهده لاگ‌های CDN که خطای ۵۰۰ داشتند:

resource.type == "cdnDomain" AND httpRequest.status >= 500

• جست‌وجوی لاگ‌هایی از سرور ابری که خطای خاصی نداشتند:

resource.type == "iaasServer" AND severity != "ERROR"

• یافتن درخواست‌هایی که شامل کلمه‌ی timeout در پیام خطا هستند:

jsonPayload.errorText =~ "timeout"

• حذف لاگ‌هایی که پیام‌شان با nginx شروع می‌شود:

payload.message !~ "^nginx"

• **یافتن لاگ‌هایی که در آن‌ها نام پاد (pod) شامل عبارت **-api نیست:

labels.pod_name !~ "api-"

• بررسی درخواست‌های HTTP فقط از مناطق ir-thr یا ir-teh:

resource.labels.zone IN ("ir-thr", "ir-teh")

• یافتن لاگ‌هایی با مقدار null در فیلد payload.latency:

payload.latency = NULL_VALUE

• ترکیب سرویس CDN، خطاهایی غیر از 404 و پیام حاوی کلمه‌ی cache:

resource.type == "cdnDomain" AND httpRequest.status != 404 AND jsonPayload.message =~ "cache"

جدول مرجع سریع (Cheat Sheet)

ساختار کلی کوئری

<field> <comparison_operator> <value>

نمونه:

resource.type == "cdnDomain"

عملگرهای مقایسه‌ای

عملگر	عملکرد	مثال
==	مساوی	"severity == "ERROR
=!	نامساوی	status != 404
~=	تطبیق Regex	"message =~ "^foo
~!	عدم تطابق Regex	"message !~ "bar$
>	کوچکتر	latency < 1000
=>	کوچکتر یا مساوی	size <= 512
<	بزرگتر	duration > 50
=<	بزرگتر یا مساوی	duration >= 10
IN	عضو در مجموعه	zone IN ("ir-thr", "ir-teh")

عملگرهای منطقی

عملگر	عملکرد	مثال
AND	و	حذف‌شدنی: a==1 b==2
OR	یا	نیاز به پرانتز در ترکیب دارد
NOT	نقیض	می‌توان با - جایگزین کرد

فیلدهای پرتکرار

فیلد	توضیح
resource.type	نوع سرویس: cdnDomain, iaasServer
severity	سطح هشدار: INFO, WARNING, ERROR
httpRequest.status	وضعیت HTTP
jsonPayload.message	پیام در بدنه JSON
labels.pod_name	نام پاد
resource.labels.zone	منطقه‌ جغرافیایی سرویس

مقادیر خاص

مقدار	کاربرد
"string"	رشته
123, 3.14	عدد
NULL_VALUE	مقدار null در JSON
"^regex$"	الگوی Regex

نمونه‌های سریع

هدف	کوئری
خطای CDN	"resource.type=="cdnDomain" AND severity=="ERROR
لاگ با کلمه timeout	"jsonPayload.message =~ "timeout
فیلتر منطقه‌ای	resource.labels.zone IN ("ir-thr", "ir-teh")
پیام بدون nginx	"payload.message !~ "^nginx