شناسایی و ارسال خطاهای پروداکشن مستقیم به ایجنت شما

از آنجا که ایجنت‌ها به ما در ساخت اپلیکیشن‌های پیچیده‌تر کمک می‌کنند، هم انسان‌ها و هم ایجنت‌ها به روش بهتری نیاز دارند تا بر آنچه در محیط پروداکشن دچار خطا می‌شود نظارت داشته باشند. ایجنت‌های کدنویسی در حال حاضر می‌توانند داده‌های قابلیت مشاهده (observability) را کوئری بگیرند، در یک مخزن ناوبری کنند، کد را تغییر دهند، تست بنویسند و یک پول ریکوئست (pull request) باز کنند. آنچه همچنان به صورت دستی باقی مانده، متصل کردن این مراحل به یکدیگر است: تشخیص اینکه شکست‌های مکرر ناشی از یک باگ واحد است، جمع‌آوری لاگ‌ها و تریس‌های مرتبط، ارسال آن کانتکست به یک ایجنت، و بررسی اینکه آیا اصلاح کارساز بوده است یا خیر. بدون این انتقال ساختاریافته، ایجنت باید داده‌های تله‌متری خام را جستجو کند تا قبل از بررسی، دامنه و کانتکست خطا را بازسازی نماید.

امروز، ما قابلیت Issues، یعنی مانیتورینگ خطای داخلی برای کلودفلر ورکرز (Cloudflare Workers) (که اکنون در بتای عمومی است) را برای ساده‌سازی این روند معرفی می‌کنیم. قابلیت Issues می‌تواند کارهای زیر را انجام دهد:

• استثناهای تکرارشده، پاسخ‌های 5xx و لاگ‌های خطا را در یک مشکل واحد گروه‌بندی کند.
• خطا، استک تریس (stack trace)، لاگ‌ها، تریس‌ها و نسخه Worker را به یک ایجنت کدنویسی پیکربندی‌شده ارسال کند.
• جریان کاری پیکربندی‌شده ایجنت را فعال کند؛ از تریاژ کردن یک مشکل گرفته تا کوئری گرفتن داده‌های بیشتر و باز کردن یک پول ریکوئست.

اولین مشکل خود را با پرامپت زیر برای ایجنت خود با استفاده از CF CLI رفع کنید یا برای شروع به مستندات (documentation) مراجعه نمایید:

تشخیص خودکار خرابی‌ها

با یک خط پیکربندی (one line of configuration)، می‌توانید دریافت مشکلاتی را که روی Worker شما شناسایی شده‌اند، بدون نیاز به ابزارگذاری اضافی آغاز کنید. مسائل در رانتیم Workers تعبیه شده‌اند، بنابراین هیچ SDK برای نصب یا پوشش اپلیکیشنی (application wrapper) برای اضافه کردن وجود ندارد.

پس از فعال‌سازی، Issues استثناهای مهارنشده، فرایندهای ناموفق، پاسخ‌های HTTP 5xx، خروجی‌های console.log() و console.error() و لاگ‌هایی که حاوی یک استک تریس هستند را ثبت می‌کند. این ابزار همچنین شرایط زنگ هشدار فرار (runaway alarm conditions) و کدهایی را که حجم زیادی از لاگ‌ها را در داخل حلقه‌ها می‌نویسند، علامت‌گذاری می‌کند.

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

هنگامی که یک مشکل را باز می‌کنید، می‌توانید خطا، استک تریس در صورت وجود، لاگ‌ها و تریس‌های منتهی به آن، نسخه Worker، جزئیات درخواست و روند مشکل در طول زمان را مشاهده کنید، همان‌طور که در زیر نشان داده شده است:

زمینه‌سازی خطاها برای ایجنت شما

شرکت Cloudflare می‌تواند آنچه را که در داخل Worker رخ داده ضبط کند، اما نمی‌داند کدام کاربران، حساب‌ها یا نشست‌ها برای اپلیکیشن شما اهمیت دارند. از API اپن‌تله‌متری (OpenTelemetry API) تعبیه‌شده در رانتیم ورکر (Worker runtime) برای افزودن آن شناسه‌ها (add those identifiers)، بدون نصب پکیج دیگری استفاده کنید:

آن شناسه‌ها با هر بار وقوع ظاهر می‌شوند. در این مشکل، اکنون می‌توانید قبل از ارسال مشکل به یک ایجنت، ببینید آیا خرابی‌ها در یک حساب یا نشست متمرکز شده‌اند یا خیر.

ارسال مشکلات شناسایی‌شده به ایجنت شما

یک مشکل دیگر نیازی ندارد که روی داشبورد بماند در حالی که شخصی یک استک تریس را کپی کرده و در یک پرامپت پیست می‌کند. یک اتوماسیون را یک بار پیکربندی کنید، و هنگامی که یک مشکل از آستانه وقوع عبور می‌کند یا پس از یک دوره آرامش بازمی‌گردد، Issues آن را از طریق اتوماسیون‌ها (Automations) مستقیماً به ایجنت شما ارسال می‌کند. شما می‌توانید انتخاب کنید که اتوماسیون چه زمانی اجرا شود و مشکل به کجا برود.

این کار می‌تواند از طریق روش‌های زیر انجام شود:

• ایجنت‌های کدنویسی داخلی: متصل کردن Claude Code با یک شناسه روال (routine ID) و توکن، Cursor با یک URL وب‌هوک اتوماسیون، یا Devin با یک توکن API و شناسه سازمان.
• وب‌هوک‌های عمومی (Generic webhooks): ارسال کانتکست مشکل به ایجنت خودتان یا پایانه HTTPS.
• مدیریت چت و حادثه (Chat and incident management): مطلع کردن تیم خود از طریق چت یا یک جریان کاری آنکال (on-call).

هنگامی که اتوماسیون اجرا می‌شود، Issues خلاصه خرابی و کانتکست تشخیصی ضبط شده با مشکل را ارسال می‌کند — استثنا، خطا، استک تریس نگاشت شده بر اساس منبع، لاگ‌ها و تریس‌های قبل و بعد، نسخه Worker و کانتکست اپلیکیشنی که اضافه کرده‌اید. برای بررسی عمیق‌تر، می‌توانید ایجنت را به طور جداگانه به کلودفلر MCP (Cloudflare MCP) متصل کنید که به ایجنت اجازه می‌دهد لاگ‌ها و تریس‌های مرتبط را کوئری بگیرد تا بتواند تغییرات کد و تست را پیشنهاد دهد و یک پول ریکوئست باز کند.

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

چگونه Issues دو باگ Workflows را در یک روز کشف و حل کرد

کلودفلر ورک‌فلوز (Cloudflare Workflows)، یک ابزار اولیه که از اپلیکیشن‌های چندمرحله‌ای و طولانی‌مدت پشتیبانی می‌کند، کاملاً بر روی پلتفرم Workers ساخته شده است.

در پس‌زمینه، سرویس‌های آن مراحل، تلاش مجدد (retries) و حالت ذخیره‌شده را پیگیری می‌کنند. این امر Workflows را به مکانی مفید برای تست Issues روی سیستم‌های پروداکشن خودمان تبدیل می‌کند. ظرف یک روز پس از روشن کردن آن، تیم دو مشکل غیرعادی پنهان شده در حجم زیادی از ترافیک را پیدا کرد:

• یک مهاجرت گیر افتاده در حلقه تلاش مجدد: مهاجرت کنترل‌پین Workflows هنگام تلاش برای اعمال مهاجرت‌ها در یک سناریوی خاص (edge case)، به‌طور مکرر به خطای کلید خارجی SQLite برخورد می‌کرد. Issues به تیم Workflows اجازه داد تا مشکل را شناسایی کرده و آن را برطرف کند.
• یک فرآیند حذف که هرگز کامل نشد: Workflows کشف کرد که در طول حذف نمونه‌های Workflow، یک سناریوی خاص وجود دارد که ممکن است از محدودیت زیردرخواست Workers فراتر رفته و حذف را به پایان نرساند. Issues به تیم Workflows کمک کرد تا مشکل را شناسایی کرده و اصلاحی را انجام دهد.

به جای اینکه تیم مجبور شود هزاران قطعه جداگانه از تله‌متری و گزارش‌های کاربر را به هم متصل کند، تنظیمات اتوماسیون آن‌ها این مشکلات را مستقیماً به کلودفلر OS (Cloudflare OS) ارسال کرد که خطاهای کد Workflows را دنبال کرد و اصلاحی را برای هر دو مشکل پیشنهاد داد.

شروع به کار

آماده‌اید ببینید Issues چه چیزی در اپلیکیشن شما پیدا می‌کند؟ برای شروع:

1. مقدار observability.issues.enabled را در فایل wrangler.jsonc خود روی true تنظیم کنید.
2. اولین اتوماسیون خود را در داشبورد کلودفلر (in the Cloudflare dashboard) راه‌اندازی کنید تا مشکلات را به مقصد دلخواه خود، چه یک ایجنت، یک وب‌هوک، ابزار مدیریت حادثه یا پلتفرم چت، ارسال کنید.

اگر ایجنت شما راه‌اندازی را مدیریت می‌کند، می‌تواند از cf CLI جدید نیز برای بازرسی مشکلات و ایجاد اتوماسیون‌ها استفاده کند. برای کسب اطلاعات بیشتر، مستندات (documentation) ما را بررسی کنید!

منبع: blog.cloudflare.com