مشاهده‌پذیری

نظارت بر تولید بر سه پایه استوار است: Sentry برای خطاها، ردگیری‌های OpenTelemetry برای مسیر اصلی و Horizon برای سلامت صف. نشان سلامت سایت در پنل مدیریت (مشاهده کنید سلامت سایت و وظایف ناموفق) آنها را در یک نگاه خلاصه می‌کند.

Sentry

SENTRY_DSN را تنظیم کنید و استثناهای مدیریت‌نشده در سراسر برنامه با ردیابی پشته، زمینه درخواست و فراداده کاربر/فضای کاری به Sentry جریان می‌یابند. ردپای مسیر، ۱۰۰ خط لاگ آخر را برای هر خطا ثبت می‌کند. از طریق sentry-laravel یکپارچه شده است.

فیلترهای مفید در Sentry:

• برچسب workspace_id برای محدود کردن خطاها به یک فضای کاری.
• برچسب agent_id زمانی که خطا از یک درخواست ویجت نشأت می‌گیرد.
• برچسب‌های نسخه با SHA کامیت استقرار مطابقت دارند — برای تشخیص مشکلات برگشتی مفید است.

ردگیری‌های OpenTelemetry

صادرکننده OTEL ردگیری‌ها را به OTEL_EXPORTER_OTLP_ENDPOINT ارسال می‌کند — معمولاً Honeycomb یا Grafana Cloud Tempo. اسپن‌ها مسیر اصلی را می‌پوشانند:

• widget.message.receive — HTTP ورودی، اعتبارسنجی، تأیید JWT.
• rag.curated.match — بررسی مسیر کوتاه.
• rag.embed — فراخوانی جستجوی هوشمند پرس‌وجو.
• rag.vector.search — جستجوی ANN.
• rag.rerank — رمزگشای متقابل.
• rag.prompt.assemble — کار CPU محلی.
• rag.llm.first_token — زمان تا اولین توکن (معیار اصلی).
• rag.llm.stream — مدت زمان کامل پخش.
• rag.persist.async — ذخیره پس از پخش.

هر اسپن با workspace_id، agent_id، conversation_id، ارائه‌دهنده (cloudflare / openai) و هر پرچم برخورد کش برچسب‌گذاری می‌شود. مورد اصلی p95 rag.llm.first_token است — که SLO مسیر اصلی شماست.

Horizon

/horizon داشبورد صف است. برای تولید الزامی است — بدون آن، نسبت به بکلاگ‌ها کور هستید. موارد زیر را تماشا کنید:

• زمان انتظار — مدت زمانی که وظایف قبل از برداشته شدن در صف می‌مانند. سالم کمتر از ۱ ثانیه است؛ زمان بیشتر از ۱۰ ثانیه نیاز به بررسی دارد.
• توان عملیاتی — وظایف در دقیقه به ازای هر صف.
• وظایف ناموفق — هر چیزی که در failed_jobs قرار می‌گیرد نیز در اینجا نشان داده می‌شود.

صف‌هایی که باید نظارت شوند:

صف	محتوای آن
default	متفرقه: رویدادهای مصرف، تشخیص شکاف، گزارش‌های حسابرسی، تحویل وب‌هوک.
crawl	CrawlSourceJob، CrawlPageJob، IngestNotionPageJob، IngestGoogleDocJob. معمولاً عمیق‌ترین صف است.
index	IndexDocumentJob، IndexTextSourceJob. سنگین از نظر جستجوی هوشمند.

لاگ‌ها

لاگ‌نویسی استاندارد لاراول. کانال‌های پیش‌فرض:

• stdout — توسط Laravel Cloud / Docker دریافت می‌شود.
• sentry — سطح خطا و بالاتر.
• slack — سطح بحرانی، به کانال عملیاتی ارسال می‌شود.

لاگ‌ها را به‌صورت محلی با php artisan pail دنبال کنید.

نقطه پایانی سلامت

GET /up آزمایش آمادگی است — در صورت راه‌اندازی برنامه، کد ۲۰۰ را با یک بدنه JSON کوچک برمی‌گرداند. از آن برای بررسی سلامت متعادل‌کننده بار استفاده کنید. برای بررسی‌های عمیق‌تر، App\Support\PlatformAdminHeader بررسی سلامت چندمرحله‌ای را اجرا کرده و نتیجه را از طریق prop اشتراکی Inertia در هر صفحه مدیریت در معرض دید قرار می‌دهد.

معیارهای قابل نظارت

معیارهایی که بیشترین اهمیت را دارند:

• تأخیر p95 اولین توکن — کمتر از ۱ ثانیه.
• تأخیر p95 پاسخ کامل — کمتر از ۵ ثانیه برای پاسخ‌های کوتاه.
• عمق صف اسکن — باید در عرض چند دقیقه تخلیه شود.
• عمق صف پردازش خودکار — باید در عرض چند دقیقه تخلیه شود.
• تعداد وظایف ناموفق — در حالت پایدار ۰. هر عدد بیشتر از ۵۰ نیاز به هشدار دارد.
• نرخ خطای سرویس‌دهنده هوش مصنوعی — کمتر از ۱٪ از پخش‌ها.
• تأخیر پرس‌وجوی ذخیره‌ساز جستجوی هوشمند — p95 کمتر از ۱۰۰ میلی‌ثانیه.

هشدارها

هشدارهای توصیه‌شده PagerDuty / Slack:

• Sentry — خطای جدید مسدودکننده نسخه.
• Honeycomb — p95 اولین توکن بیشتر از ۱.۵ ثانیه به مدت ۵ دقیقه.
• Horizon — تغییر وظایف ناموفق بیشتر از ۱۰ در ۵ دقیقه.
• وب‌هوک Stripe — بیشتر از ۵ شکست تأیید متوالی (عدم تطابق کلید امضا).
• Reverb — فرآیند از کار افتاده است.

نشان سلامت سایت

نشان هدر در پنل مدیریت یک بررسی بصری سریع است که همه چیز پیکربندی شده است. سبز حالت پایدار است. اگر نارنجی شود، منوی کشویی دقیقاً به شما می‌گوید کدام بررسی ناموفق بوده و به صفحه تنظیمات برای رفع آن لینک می‌دهد. مشاهده کنید سلامت سایت و وظایف ناموفق.