تحلیل خودکار خطاهای n8n با Claude و OpenRouter

تحلیل گردش‌کارهای ناموفق با Claude از طریق OpenRouter و ثبت در Sheets با هشدار

این گردش کار به طور خودکار شکست‌های اجرای n8n را تشخیص می‌دهد، از Claude 3.5 Sonnet از طریق OpenRouter برای تحلیل علت ریشه‌ای استفاده می‌کند و این اطلاعات را از طریق کانال‌های مختلف منتشر می‌کند، از جمله ثبت در Google Sheets و ارسال هشدار از طریق ایمیل، Slack و Discord. همچنین مکانیزمی برای کاهش خستگی از هشدار با شناسایی و سرکوب بالقوه خطاهای تکراری را در بر می‌گیرد.

دسته‌بندی‌ها: DevOps، خلاصه‌سازی با هوش مصنوعی

لینک کاتالوگ Axeto: https://axeto.ai/n8n

نمای کلی گردش کار

این گردش کار برای نظارت قوی نمونه‌های n8n طراحی شده است و بینش‌های عملی در مورد شکست‌های اجرایی ارائه می‌دهد.

• تشخیص شکست: از Error Trigger در n8n برای ثبت بلادرنگ شکست‌های گردش کار استفاده می‌کند.
• زمینه‌سازی: داده‌های مرتبط را از اجرای ناموفق استخراج و نرمال‌سازی می‌کند.
• تحلیل مبتنی بر هوش مصنوعی: از Claude 3.5 Sonnet از طریق OpenRouter برای تحلیل شکست، شناسایی علت ریشه‌ای و پیشنهاد مراحل اصلاحی استفاده می‌کند.
• استخراج اطلاعات: پاسخ هوش مصنوعی را تجزیه و تحلیل می‌کند تا امتیاز اطمینان را استخراج کرده و یک امضای منحصربه‌فرد برای خطا ایجاد کند، که به حذف موارد تکراری کمک می‌کند.
• ثبت متمرکز: اطلاعات دقیق خطا، از جمله تحلیل هوش مصنوعی را در یک Google Sheet ثبت می‌کند.
• هشدار چند کاناله: اعلان‌ها را به Email، Slack و Discord ارسال می‌کند.
• مدیریت خستگی از هشدار: منطقی را برای شناسایی و احتمالاً سرکوب هشدارها برای خطاهای تکراری در یک پنجره زمانی مشخص پیاده‌سازی می‌کند.

موارد استفاده کلیدی:

• نظارت فعال عملیاتی: سلامت و عملکرد نمونه‌های n8n را پیگیری کنید.
• پاسخ سریع به حوادث: دلایل شکست را به سرعت درک کرده و رفع‌های پیشنهادی را از هوش مصنوعی دریافت کنید.
• ردیابی یکپارچه خطا: گزارش‌های خطا را در Google Sheets ادغام کرده و هشدارها را در چندین پلتفرم ارتباطی دریافت کنید.

---

تحلیل جزئیات بلاک‌ها

بلاک ۱: دریافت و نرمال‌سازی خطا

هدف: این بلاک بار داده (payload) خام خطا را از یک گردش کار ناموفق n8n دریافت کرده و آن را به یک فرمت استاندارد برای پردازش بعدی تبدیل می‌کند.

نودها:

1. Error Trigger (n8n-nodes-base.errorTrigger)

* نقش: نقطه شروع گردش کار که به طور خودکار هنگام ناموفق بودن هر گردش کار n8n دیگری فعال می‌شود.

* پیکربندی: هیچ پارامتر خاصی لازم نیست؛ این نود به مکانیزم مدیریت خطای داخلی n8n متکی است.

* ورودی/خروجی: ورودی دریافت نمی‌کند. زمینه اجرای کامل گردش کار ناموفق را خروجی می‌دهد.

* ملاحظات: اطمینان حاصل کنید که این گردش کار فعال است و برای اجرا در صورت بروز خطا در تنظیمات n8n شما پیکربندی شده است. ساختار بار داده ممکن است بین نسخه‌های مختلف n8n کمی متفاوت باشد.

2. Normalize Error Payload (n8n-nodes-base.set)

* نقش: فیلدهای کلیدی خروجی Error Trigger را به یک شمای سازگار استاندارد می‌کند.

* فیلدهای کلیدی ایجاد شده:

* workflow_name: نام گردش کار ناموفق.

* workflow_id: شناسه منحصر به فرد گردش کار ناموفق.

* execution_id: شناسه منحصر به فرد اجرای ناموفق.

* execution_mode: حالتی که اجرا در آن انجام شده است (مثلاً 'standard', 'test').

* failed_node: نام نودی که باعث خطا شده است.

* error_message: پیام خطای اصلی.

* error_stack: ردیابی پشته خطا (در صورت عدم وجود به صورت پیش‌فرض 'N/A' است).

* timestamp: زمان خطا در فرمت ISO.

* trigger_type: نوع تریگر که گردش کار را آغاز کرده است.

* input_payload: نسخه رشته‌ای کوتاه شده از داده‌های ورودی اولیه.

* environment: یک مقدار ثابت (مثلاً "production") برای نشان دادن محیط.

* receiver_emails: آرایه‌ای که در ابتدا خالی است و گیرندگان ایمیل را نگه می‌دارد.

* اتصالات: ورودی را از Error Trigger دریافت کرده و خروجی را به Prepare AI Context ارسال می‌کند.

* موارد مرزی: اگر شیء خطا وجود نداشته باشد یا بدشکل باشد، برخی فیلدها ممکن است خالی باشند. اگر اعلان‌های ایمیلی مد نظر است، اطمینان حاصل کنید که receiver_emails پر شده است.

---

بلاک ۲: کاهش زمینه ("استخراج از میانه به بیرون")

هدف: این بلاک به طور هوشمندانه بخش‌های مرتبط‌تر تعریف گردش کار و داده‌های اجرای ناموفق را انتخاب و ساختاربندی می‌کند تا یک زمینه مختصر برای هوش مصنوعی ایجاد کند و در محدودیت توکن باقی بماند.

نودها:

1. Prepare AI Context (n8n-nodes-base.code)

* نقش: یک نمایش JSON متمرکز از داده‌های گردش کار و اجرا را تولید می‌کند که حول نقطه شکست متمرکز شده است.

* منطق: یک پیمایش "از میانه به بیرون" (مشابه جستجوی اول سطح - Breadth-First Search) را با شروع از failed_node پیاده‌سازی می‌کند. این نود شامل نودهای اطراف و داده‌های اجرای آن‌ها تا یک حد کاراکتر تعریف شده (MAX_CONTEXT_CHARS، پیش‌فرض ۵۰,۰۰۰) می‌شود تا اطمینان حاصل شود که LLM اطلاعات مرتبط را بدون تجاوز از پنجره زمینه خود دریافت می‌کند.

* خروجی‌های کلیدی:

* workflow_json: نسخه رشته‌ای و فیلتر شده از تعریف گردش کار.

* execution_json: نسخه رشته‌ای و فیلتر شده از داده‌های اجرا.

* _extraction_stats: فراداده مربوط به فرآیند استخراج زمینه (نودهای شامل شده، تعداد جهش‌ها، اندازه تخمینی).

* اتصالات: ورودی را از Normalize Error Payload دریافت کرده و خروجی را به AI Error Analysis ارسال می‌کند.

* موارد مرزی: کیفیت زمینه هوش مصنوعی به در دسترس بودن workflowData.nodes، workflowData.connections و داده‌های اجرای اجرا بستگی دارد. اگر failed_node یافت نشود، زمینه ممکن است ناقص باشد.

---

بلاک ۳: تحلیل علل ریشه‌ای با هوش مصنوعی (Claude از طریق OpenRouter)

هدف: این بلاک زمینه آماده شده و جزئیات خطا را به Claude 3.5 Sonnet از طریق OpenRouter ارسال می‌کند و درخواست تحلیل ساختاریافته خطا را می‌دهد.

نودها:

1. OpenRouter Chat Model (@n8n/n8n-nodes-langchain.lmChatOpenRouter)

* نقش: به API OpenRouter برای دسترسی به مدل‌های زبان مختلف متصل می‌شود.

* پیکربندی:

* Model: anthropic/claude-3.5-sonnet مشخص شده است.

* Credentials: نیاز به یک کلید API OpenRouter دارد که در n8n پیکربندی شده باشد.

* اتصالات: خروجی آن (رابط مدل زبان) به نود AI Error Analysis تغذیه می‌شود.

* حالت‌های شکست: مشکلات مربوط به اعتبار کلید API، در دسترس بودن سرویس OpenRouter، محدودیت‌های نرخ (rate limits) یا قطع شدن شبکه می‌تواند این مرحله را مختل کند.

2. AI Error Analysis (@n8n/n8n-nodes-langchain.chainLlm)

* نقش: یک prompt دقیق شامل زمینه فیلتر شده گردش کار/اجرا و فراداده خطا را می‌سازد، سپس آن را به LLM پیکربندی شده ارسال می‌کند. این نود خروجی‌های خاصی مانند علت ریشه‌ای، مراحل رفع مشکل و امتیاز اطمینان هوش مصنوعی با فرمت CONFIDENCE: x.x را درخواست می‌کند.

* Prompting: Prompt به گونه‌ای طراحی شده است که LLM را در تحلیل زمینه JSON ارائه شده و جزئیات خطا راهنمایی کند.

* خروجی: معمولاً پاسخ هوش مصنوعی را در یک فیلد text برمی‌گرداند (اگرچه بسته به نسخه نود ممکن است از output استفاده شود).

* اتصالات: ورودی را از Prepare AI Context دریافت کرده و خروجی خود را به Extract AI Confidence ارسال می‌کند.

* موارد مرزی: دقت تحلیل به شدت به اثربخشی prompt و کیفیت زمینه ورودی بستگی دارد. اطمینان حاصل کنید که فیلد خروجی (text یا output) با آنچه نودهای پایین‌دستی انتظار دارند مطابقت دارد.

---

بلاک ۴: استخراج اطمینان، تولید امضا و آماده‌سازی لاگ

هدف: این بلاک پاسخ هوش مصنوعی را پردازش می‌کند تا معیارهای کلیدی را استخراج کند، یک شناسه پایدار برای خطا ایجاد کند و یک رکورد کامل را برای لاگ‌نویسی فرمت کند.

نودها:

1. Extract AI Confidence (n8n-nodes-base.code)

* نقش: متن پاسخ هوش مصنوعی را تجزیه و تحلیل می‌کند تا امتیاز اطمینان را پیدا و استخراج کند، که معمولاً در خطی مانند CONFIDENCE: x.x یافت می‌شود.

* منطق: از عبارات منظم (regular expressions) برای یافتن امتیاز استفاده می‌کند، آن را اعتبارسنجی می‌کند که در محدوده ۰ تا ۱ قرار گیرد و در صورت عدم یافتن یا نامعتبر بودن، به طور پیش‌فرض ۰.۵ تعیین می‌کند.

* اتصالات: ورودی را از AI Error Analysis گرفته و خروجی را به Generate Error Signature ارسال می‌کند.

* موارد مرزی: اگر فرمت پاسخ هوش مصنوعی به طور قابل توجهی منحرف شود، ممکن است امتیاز اطمینان به درستی استخراج نشود.

2. Generate Error Signature (n8n-nodes-base.code)

* نقش: یک امضای منحصر به فرد و نرمال شده برای خطا ایجاد می‌کند تا حذف موارد تکراری هشدارها را تسهیل کند.

* منطق:

* پیام خطا را با جایگزینی عناصر پویا مانند مُهر زمانی، اعداد طولانی، UUIDها و رشته‌های عمومی با نگهدارنده‌ها (TIMESTAMP, NUMBER, STRING, و غیره) نرمال می‌کند.

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

* خروجی‌ها: error_signature و normalized_error.

* اتصالات: ورودی را از Extract AI Confidence دریافت کرده و خروجی را به Prepare Log Record ارسال می‌کند.

* موارد مرزی: نرمال‌سازی بیش از حد می‌تواند منجر به اشتراک‌گذاری امضای یکسان توسط خطاهای مختلف شود، در حالی که نرمال‌سازی ناکافی ممکن است در حذف موارد تکراری خطاهای واقعاً یکسان شکست بخورد.

3. Prepare Log Record (n8n-nodes-base.set)

* نقش: تمام نقاط داده لازم را در یک فرمت ساختاریافته جمع‌آوری می‌کند که برای لاگ‌نویسی در Google Sheets و برای استفاده در اعلان‌ها مناسب است.

* فیلدهای کلیدی جمع‌آوری شده: شامل فیلدهای اصلی از بلاک ۱، error_signature تولید شده، aiRootCause و aiFixSummary استخراج شده (کوتاه شده)، aiConfidence و یک سطح severity ثابت.

* اتصالات: ورودی را از Generate Error Signature گرفته و خروجی را به Log to Google Sheets ارسال می‌کند.

* موارد مرزی: به فرمت‌بندی خاص در پاسخ هوش مصنوعی (فیلد text، جدا شده با دو خط جدید) متکی است. اگر ساختار خروجی هوش مصنوعی تغییر کند، استخراج aiRootCause و aiFixSummary ممکن است شکست بخورد.

---

بلاک ۵: کنترل لاگ‌نویسی و خستگی هشدار

هدف: این بلاک رکورد خطای آماده شده را به یک Google Sheet اضافه می‌کند و سپس وقوع اخیر همان امضای خطا را بررسی می‌کند تا تعیین کند آیا هشدارها باید سرکوب یا تنزل رتبه یابند یا خیر.

نودها:

1. Log to Google Sheets (n8n-nodes-base.googleSheets)

* نقش: داده‌های خطای ساختاریافته را به عنوان یک ردیف جدید در یک Google Sheet مشخص اضافه می‌کند.

* پیکربندی: نیاز به اعتبار Google Sheets و شناسه Spreadsheet و نام Sheet هدف دارد. از عملیات 'append' استفاده کرده و فیلدهای ورودی را به طور خودکار با ستون‌های Sheet مطابقت می‌دهد.

* اتصالات: ورودی را از Prepare Log Record دریافت کرده و خروجی را به Check Alert Fatigue ارسال می‌کند.

* حالت‌های شکست: مشکلات مربوط به دسترسی به API Google Sheets، اعتبارنامه‌های نادرست یا عدم تطابق هدرهای Sheet می‌تواند باعث شکست شود.

2. Check Alert Fatigue (n8n-nodes-base.code)

* نقش: منطقی را برای جلوگیری از سیل هشدار با بررسی موارد تکراری امضای خطا در یک دوره زمانی اخیر تعریف شده پیاده‌سازی می‌کند.

* منطق: تعداد قابل پیکربندی از ورودی‌های اخیر (LOOKBACK_COUNT) را در Google Sheet (در TIME_WINDOW_HOURS) بررسی می‌کند. اگر امضاهای مطابق یافت شوند، پرچم‌هایی مانند alert_suppressed و downgrade_urgency را تنظیم می‌کند.

* اتصالات: ورودی را از Log to Google Sheets گرفته و پرچم‌های خود را به Send Email ارسال می‌کند.

* ملاحظه حیاتی: اثربخشی این نود به شدت به نحوه بازگرداندن داده‌ها توسط Log to Google Sheets بستگی دارد. اگر فقط ردیف تازه اضافه شده را برگرداند، $('Log to Google Sheets').all() حاوی داده‌های تاریخی نخواهد بود و بررسی خستگی را بی‌اثر می‌کند. یک پیاده‌سازی قوی نیاز به واکشی جداگانه ردیف‌های اخیر یا اطمینان از دسترسی نود به کل داده‌های Sheet دارد. تجزیه مُهر زمانی نیز نیازمند فرمت ISO سازگار در Sheet است.

---

بلاک ۶: اعلان‌ها (ایمیل → فَن‌اوت Slack/Discord/Webhook)

هدف: این بلاک انتشار هشدارها را به کانال‌های ارتباطی مختلف مدیریت می‌کند، با یک ایمیل شروع شده و سپس به سایر سرویس‌ها فَن‌اوت می‌شود.

نودها:

1. Send Email (n8n-nodes-base.gmail)

* نقش: یک ایمیل اعلان اولیه ارسال می‌کند که خلاصه‌ای از جزئیات خطا و تحلیل هوش مصنوعی را ارائه می‌دهد.

* پیکربندی: نیاز به اعتبار Gmail و پیکربندی فرستنده، گیرندگان (احتمالاً با استفاده از فیلد receiver_emails از بلاک ۱)، موضوع و بدنه ایمیل (احتمالاً با فرمت HTML) دارد.

* اتصالات: ورودی را از Check Alert Fatigue دریافت کرده و خروجی را به Send Slack Message ارسال می‌کند.

* حالت‌های شکست: اعتبارنامه‌های ایمیل نامعتبر، آدرس‌های گیرنده نادرست یا مشکلات مربوط به API Gmail.

2. Send Slack Message (n8n-nodes-base.slack)

* نقش: یک اعلان به یک کانال Slack پیکربندی شده ارسال می‌کند.

* پیکربندی: نیاز به اعتبار Slack و پیکربندی کانال، محتوای پیام و احتمالاً منشن کاربران دارد.

* اتصالات: ورودی را از Send Email دریافت کرده و خروجی را به Send Discord Message ارسال می‌کند.

3. Send Discord Message (n8n-nodes-base.discord)

* نقش: یک اعلان به یک کانال یا webhook دیسکورد پیکربندی شده ارسال می‌کند.

* پیکربندی: نیاز به اعتبار Discord یا URL webhook و پیکربندی محتوای پیام دارد.

* اتصالات: ورودی را از Send Slack Message دریافت کرده و خروجی را به Send Webhook ارسال می‌کند.

4. Send Webhook (n8n-nodes-base.httpRequest)

* نقش: یک درخواست HTTP عمومی ارسال می‌کند که برای ادغام با سایر سیستم‌ها یا نقاط پایانی webhook سفارشی مفید است.

* پیکربندی: نیاز به URL هدف و متد HTTP (مثلاً POST) به همراه هرگونه هدر یا پیکربندی بار داده لازم دارد.

* اتصالات: ورودی را از Send Discord Message دریافت می‌کند.

نکته: پرچم‌های خستگی هشدار (alert_suppressed, downgrade_urgency) از Check Alert Fatigue باید در پیکربندی این نودهای اعلان برای ارسال شرطی یا اصلاح هشدارها استفاده شوند. به عنوان مثال، اگر alert_suppressed درست باشد، نودهای Slack، Discord و Webhook ممکن است غیرفعال شوند یا پیام کم‌اهمیت‌تری ارسال کنند.