ابزارهای لاگ ابری

با فعال‌کردن Toolset مربوط به logs، دستیار می‌تواند Space ،Sink و Forwarderهای لاگ ابری را از طریق MCP مدیریت کند. برای نمونه، می‌توانید از دستیار بخواهید فقط خطاهای CDN را به یک Space مشخص بفرستد.

برای فعال‌سازی، در تنظیمات کلاینت مقدار زیر را در هدر X-Mcp-Toolsets قرار دهید:

X-Mcp-Toolsets: logs

اگر هم‌زمان به دیتابیس ابری هم نیاز دارید، مقدار logs,dbaas را بنویسید.

مفاهیم اصلی

• Space

  محل نگه‌داری لاگ‌ها با Region و دوره‌ی نگه‌داری (Retention) مشخص است.

• Sink

  قانون مسیریابی است. Sink لاگ‌های منطبق را به یک Space یا Forwarder می‌فرستد.

• Forwarder

  مقصد خارجی برای ارسال لاگ است: Splunk ،HTTP یا فضای ابری آروان‌کلاد.

• ARQL

  زبان فیلتر برای inclusionRule و exclusionRule در Sink است.

ترتیب معمول کار این است که ابتدا Space یا Forwarder را بسازید، سپس Sink را به آن وصل کنید.

ابزارهای Space

برای مدیریت Spaceها از ابزارهای زیر استفاده کنید:

ابزار	کار	پارامترهای مهم
logs_space_list	فهرست Spaceها	page, perPage, q
logs_space_get	جزییات یک Space	spaceId
logs_space_create	ساخت Space	name, region, retentionDays, description
logs_space_update	تغییر توضیح یا Retention	spaceId, description, retentionDays
logs_space_delete	درخواست حذف Space	spaceId

هنگام ساخت Space این قوانین را رعایت کنید:

• name فقط حروف، رقم و خط تیره (-) داشته باشد و در حساب شما یکتا باشد.
• retentionDays بین ۱ تا ۴۰۰ روز باشد.
• region الزامی است؛ برای نمونه ir-thr.

اگر هنگام ساخت Space ،Sink یا Forwarder خطای نام دریافت کردید، احتمالن نام کاراکتر غیرمجاز دارد یا تکراری است. نامی یکتا انتخاب کنید که فقط حروف، رقم و خط تیره داشته باشد.

ابزارهای Sink

برای مدیریت Sinkها از ابزارهای زیر استفاده کنید:

ابزار	کار	پارامترهای مهم
logs_sink_list	فهرست Sinkها	page, perPage, q
logs_sink_get	جزییات یک Sink	sinkId
logs_sink_create	ساخت Sink برای مسیریابی لاگ	name, destinationType, destinationId, inclusionRule, exclusionRule, disabled
logs_sink_update	تغییر توضیح، قوانین ARQL یا وضعیت فعال یا غیرفعال	sinkId, description, inclusionRule, exclusionRule, disabled
logs_sink_delete	حذف Sink	sinkId

برای destinationType یکی از دو مقدار زیر را بفرستید:

مقدار	معنی destinationId
logSpace	نام Space مقصد
logForwarder	نام Forwarder مقصد

توجه داشته باشید که destinationId شناسه‌ی UUID نیست و همان نام منبع مقصد است.

اگر هنگام ساخت یا ویرایش Sink خطای 422 دریافت کردید، ARQL نامعتبر است یا مقصد اشتباه وارد شده است. منبع logs://docs/arql را بخوانید و destinationId را با نام مقصد پر کنید.

ابزارهای Forwarder

برای مدیریت Forwarderها از ابزارهای زیر استفاده کنید:

ابزار	کار	پارامترهای مهم
logs_forwarder_list	فهرست Forwarderها	page, perPage, q
logs_forwarder_get	جزییات یک Forwarder	forwarderId
logs_forwarder_create	ساخت Forwarder	name, destinationType, destinationConfig
logs_forwarder_update	تغییر توضیح یا تنظیمات مقصد	forwarderId, description, destinationConfig
logs_forwarder_delete	حذف Forwarder	forwarderId

destinationType در Forwarder یکی از مقدارهای زیر است و هر نوع فیلد مخصوص خودش را در destinationConfig می‌خواهد:

نوع	فیلدهای لازم در destinationConfig
splunk	endpoint, hecToken
http	endpoint؛ اختیاری: basicAuthUsername, basicAuthPassword, headers
arvancloudStorage	bucketName, region؛ اختیاری: compressionMethod (مقدار uncompressed یا gzip)، hiveCompatiblePartitioning

توجه داشته باشید که نوع مقصد (destinationType) پس از ساخت قابل تغییر نیست و فقط توضیح و تنظیمات مقصد را می‌توانید به‌روز کنید.

نوشتن قوانین Sink با ARQL

برای نوشتن قوانین فیلتر، دستیار می‌تواند منبع logs://docs/arql (با نام logs_arql) را بخواند. این منبع نحو ARQL و معنای inclusion و exclusion را توضیح می‌دهد.

Sink هر لاگ را این‌گونه بررسی می‌کند: اگر exclusionRule تنظیم شده باشد و لاگ با آن منطبق شود، Sink آن لاگ را رد می‌کند. اگر inclusionRule تنظیم شده باشد، فقط لاگ‌های منطبق پذیرفته می‌شوند. در غیر این حالت لاگ پذیرفته می‌شود.

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

severity == "ERROR" AND resource.type == "cdn"
resource.attributes.domain == "api.example.com"
NOT (payload.path == "/health" OR payload.path == "/ready")

مستندات کامل‌تر ARQL در راهنمای ARQL آمده است.

پرامپت آماده

پرامپت logs_route_domain_logs راهنمای گام‌به‌گام برای هدایت لاگ یک دامنه به Space یا Forwarder است. آرگومان‌های مهم این پرامپت به این شکل است:

• domain

  دامنه‌ای را که لاگ‌هایش را هدایت می‌کنید وارد کنید، مثل api.example.com. این آرگومان اجباری است.

• destination

  نوع مقصد را مشخص می‌کند و یکی از مقدارهای space ،splunk ،http یا arvancloudStorage است. این آرگومان اجباری است.

• spaceName / region

  نام و Region مربوط به Space را وارد کنید. این آرگومان‌ها فقط وقتی مقصد Space است اجباری‌اند.

• forwarderName

  نام Forwarder را وارد کنید. این آرگومان فقط وقتی مقصد Forwarder است اجباری است.

• endpoint / hecToken

  آدرس و توکن مربوط را وارد کنید. این آرگومان‌ها برای مقصد Splunk یا HTTP اجباری‌اند.

• bucketName / storageRegion

  نام باکت و Region فضای ابری را وارد کنید. این آرگومان‌ها برای مقصد فضای ابری اجباری‌اند.

سناریوهای رایج

ساخت Space و دیدن وضعیت

در چت بنویسید:

لیست Spaceهای Logs من را نشان بده. یک Space به نام prod-logs در region ir-thr با retention 30 روز بساز.

دستیار معمولن logs_space_list و سپس logs_space_create را صدا می‌زند و spaceId را برمی‌گرداند.

مسیریابی خطاهای CDN به Space

در چت بنویسید:

یک Sink به نام cdn-errors بساز که لاگ‌های با severity ERROR و resource.type cdn را به Space prod-logs بفرستد. قبل از نوشتن rule منبع ARQL را بخوان.

دستیار ابتدا منبع logs://docs/arql را می‌خواند و سپس logs_sink_create را با این مقدارها اجرا می‌کند:

• destinationType: logSpace
• destinationId: prod-logs
• inclusionRule: برای نمونه "severity == "ERROR" AND resource.type == "cdn

ارسال لاگ به Splunk یا فضای ابری

در چت بنویسید:

Forwarder splunk-prod بساز: نوع splunk، endpoint را از من بپرس، hecToken را هم بعدا می‌دهم. Forwarder s3-archive برای arvancloudStorage بساز: bucket my-logs-bucket، region ir-thr-at1، compression gzip.

پس از ساخت Forwarder، یک Sink با destinationType=logForwarder و destinationId برابر نام Forwarder بسازید.

هدایت لاگ یک دامنه با پرامپت

در چت بنویسید:

از پرامپت route domain logs استفاده کن: domain=api.example.com، destination=space، spaceName=prod-logs، region=ir-thr.

دستیار پرامپت logs_route_domain_logs را می‌گیرد و Space یا Sink لازم را می‌سازد یا دوباره استفاده می‌کند.

به‌روزرسانی و حذف امن

در چت بنویسید:

retention Space prod-logs را به 60 روز تغییر بده. Sink cdn-errors را موقت disable کن. Space test-old را پیدا کن. قبل از حذف id و نام را نشان بده و منتظر تایید من بمان.

توجه داشته باشید که حذف Space ،Sink یا Forwarder ممکن است برگشت‌پذیر نباشد. اگر دستیار تایید خواست و مطمین نیستید، عملیات را تایید نکنید.

نمونه‌ پیکربندی کلاینت

برای این‌که فقط ابزارهای لاگ ابری در دسترس کلاینت باشد، پیکربندی را به‌شکل زیر بنویسید و به‌جای YOUR-MACHINE-USER-UUID شناسه‌ی ماشین یوزر خود را قرار دهید:

{
  "mcpServers": {
    "arvancloud": {
      "url": "https://mcp.arvancloud.ir",
      "headers": {
        "Arvancloud-Api-Key": "apikey YOUR-MACHINE-USER-UUID",
        "X-Mcp-Toolsets": "logs"
      }
    }
  }
}

اگر پس از اتصال خطای 401 دریافت کردید، کلید API نامعتبر یا خالی است، مقدار Arvancloud-Api-Key را بررسی کنید. اگر خطای 400 روی اتصال MCP دیدید، مقدار X-Mcp-Toolsets خالی یا نامعتبر است و باید آن را روی logs یا logs,dbaas بگذارید. اگر ابزارهای لاگ ابری دیده نمی‌شوند، هدر Toolset و دسترسی‌های ماشین یوزر را بررسی کنید.

جزییات Cursor ،Claude و OpenCode در تنظیم کلاینت‌ها آمده است. نمونه‌های بیش‌تری از جمله‌های چت را در نمونه درخواست‌ها ببینید.