خودکارسازی هشدار خطا با n8n: ادغام ایمیل و جیرا

تجمیع هشدار خطا و ارسال گزارش‌های یکپارچه از طریق ایمیل و جیرا

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

دسته‌بندی‌ها: DevOps

کاتالوگ Axeto.ai: گردش کارهای n8n

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

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

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

موارد استفاده هدف:

• متمرکز کردن هشدار خطا از هر API لاگ JSON (مانند پلتفرم‌های نظارتی، پشته‌های ELK، نقاط پایانی سفارشی).
• کاهش نویز اعلان‌ها از طریق دسته‌بندی و حذف موارد تکراری.
• ادغام ردیابی خطا با هر دو ایمیل و جیرا برای مدیریت جامع حوادث.

۱.۱ تریگر و دریافت داده

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

۱.۲ پردازش و حذف موارد تکراری

لاگ‌های خام به موارد (items) جداگانه تبدیل می‌شوند، برای پردازش کارآمد دسته‌بندی شده و سپس در هر دسته از حالت تکراری خارج می‌شوند. گردش کار بررسی می‌کند که آیا پس از حذف موارد تکراری، خطاهای قابل اقدام باقی مانده‌اند یا خیر.

۱.۳ ارزیابی شدت و اعلان‌های حیاتی

هر خطا بر اساس تطابق کلمات کلیدی به عنوان critical یا normal طبقه‌بندی می‌شود. خطاهای حیاتی باعث ارسال فوری هشدارهای ایمیلی می‌شوند.

۱.۴ ایجاد مسئله جیرا، جمع‌آوری و خلاصه ایمیل

بارهای داده (payloads) برای مسائل جیرا ساخته می‌شوند، درخواست‌ها محدودیت نرخ دارند و مسائل جیرا ایجاد می‌شوند. نتایج ایجاد مسئله جیرا و هشدارهای ایمیلی حیاتی ادغام می‌شوند. در نهایت، یک ایمیل خلاصه یکپارچه تولید و ارسال می‌شود.

---

۲. تحلیل گره به گره

بلوک ۱: تریگر و دریافت داده

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

گره‌ها:

• Schedule Trigger
• HTTP Request
• IF (آیا لاگ دارد؟)

#### گره: Schedule Trigger

• نوع: scheduleTrigger
• نقش: نقطه ورود گردش کار که اجرای آن را در فواصل منظم آغاز می‌کند.
• پیکربندی: تنظیم شده برای اجرا هر ۱ ساعت.
• ورودی/خروجی: داده‌ها را به گره HTTP Request خروجی می‌دهد.
• نسخه: گره استاندارد scheduleTrigger.
• ملاحظات شکست: اجرای از دست رفته در صورت در دسترس نبودن نمونه n8n، مگر اینکه از یک مکانیزم زمان‌بندی خارجی استفاده شود.

#### گره: HTTP Request

• نوع: httpRequest
• نقش: دریافت داده‌های خام لاگ از یک نقطه پایانی API REST مشخص شده.
• پیکربندی:

* URL: https://example.com/api/logs (نقطه پایانی API واقعی خود را جایگزین کنید).

* Authentication: نیاز به یک اعتبارنامه HTTP پیکربندی شده (genericCredentialType) دارد.

* Method: در صورت عدم تنظیم صریح، به طور پیش‌فرض GET است.

• ورودی/خروجی: ورودی را از Schedule Trigger دریافت کرده و داده‌ها را به گره IF خروجی می‌دهد.
• ملاحظات شکست: خطاهای احراز هویت (401/403)، مشکلات DNS/TLS، مهلت زمانی (timeouts)، یا پاسخ‌های غیر JSON می‌توانند باعث شکست شوند. گره‌های پایین‌دستی انتظار دارند که پاسخ حاوی یک آرایه logs تحت $json.logs باشد.

#### گره: IF (آیا لاگ دارد؟)

• نوع: if
• نقش: به عنوان یک دروازه شرطی عمل می‌کند و تعیین می‌کند که آیا پردازش لاگ ادامه یابد یا به تولید خلاصه پرش شود.
• شرط: Array.isArray($json.logs) ? $json.logs.length : 0 بزرگتر از 0.
• خروجی‌ها:

* True: به گره "Parse & Flatten Logs" ادامه می‌دهد.

* False: به گره "Generate Summary" ادامه می‌دهد.

• ملاحظات شکست: اگر پاسخ API از نام فیلد دیگری غیر از logs استفاده کند، این شرط به اشتباه ارزیابی می‌شود و مقدار false برمی‌گرداند. سیم‌کشی فعلی مسیر "بدون لاگ" را مستقیماً به "Generate Summary" ارسال می‌کند، که ممکن است گزارش‌های گمراه‌کننده یا خالی تولید کند اگر گره‌های خلاصه به درستی آن را مدیریت نکنند.

---

بلوک ۲: پردازش و حذف موارد تکراری

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

گره‌ها:

• Code (Parse & Flatten Logs)
• Split In Batches
• Code (Deduplicate Batch)
• IF (آیا خطای جدیدی وجود دارد؟)

#### گره: Code (Parse & Flatten Logs)

• نوع: code
• نقش: آرایه logs ورودی را به موارد مجزای n8n تبدیل می‌کند و هر ورودی لاگ را قابل پردازش به صورت جداگانه می‌سازد.
• منطق: items[0].json.logs || [] را می‌خواند و هر ورودی لاگ l را به { json: l } نگاشت می‌کند.
• ورودی/خروجی: ورودی را از گره IF "Has Logs?" (شاخه true) دریافت کرده و به Split In Batches خروجی می‌دهد.
• ملاحظات شکست: پردازش یک آرایه logs بسیار بزرگ می‌تواند مصرف حافظه و زمان اجرا را افزایش دهد. اشیاء تودرتو در ورودی‌های لاگ بدون تغییر عبور داده می‌شوند.

#### گره: Split In Batches

• نوع: splitInBatches
• نقش: موارد لاگ را به دسته‌های کوچکتر تقسیم می‌کند تا بار پردازش را کنترل کرده و حذف موارد تکراری را تسهیل کند.
• پیکربندی:

* Batch Size: 20 مورد.

• ورودی/خروجی: ورودی را از "Parse & Flatten Logs" دریافت کرده و به "Deduplicate Batch" خروجی می‌دهد.
• ملاحظات شکست: همانطور که در حال حاضر پیکربندی شده است، این گره فاقد اتصال حلقه باز برای پردازش دسته‌های بعدی است. این بدان معناست که ممکن است فقط دسته اول پردازش شود. برای پردازش تمام لاگ‌ها، معمولاً یک الگوی دسته‌بندی حلقه استاندارد (اتصال گره پایین‌دستی به Split In Batches) مورد نیاز است.

#### گره: Code (Deduplicate Batch)

• نوع: code
• نقش: موارد خطای تکراری را در دسته فعلی بر اساس یک کلید تولید شده حذف می‌کند.
• منطق: یک dedupeKey منحصر به فرد با استفاده از فیلدهایی مانند id، message و timestamp ایجاد می‌کند. موارد ورودی را که کلیدهایشان قبلاً در دسته دیده شده‌اند، فیلتر کرده و dedupeKey را به هر مورد اضافه می‌کند.
• ورودی/خروجی: ورودی را از Split In Batches دریافت کرده و به گره IF "Any New Errors?" خروجی می‌دهد.
• ملاحظات شکست: حذف موارد تکراری فقط در حافظه برای دسته فعلی انجام می‌شود و بین دسته‌ها یا اجرای گردش کار حفظ نمی‌شود. تغییرات جزئی در message یا timestamp می‌تواند مانع از حذف موارد تقریباً تکراری شود. اگر فیلد id وجود نداشته باشد، حذف موارد تکراری فقط بر message و timestamp متکی است.

#### گره: IF (آیا خطای جدیدی وجود دارد؟)

• نوع: if
• نقش: بررسی می‌کند که آیا مورد فعلی پس از حذف موارد تکراری حاوی داده‌ای است یا خیر.
• شرط: Object.keys($json).length > 0 درست است.
• خروجی‌ها:

* True: به گره "Assess Severity" ادامه می‌دهد.

* False: به گره "Generate Summary" ادامه می‌دهد.

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

---

بلوک ۳: ارزیابی شدت و اعلان‌های حیاتی

مرور کلی: این بلوک سطح شدت (critical یا normal) را به هر خطا اختصاص می‌دهد. خطاهای حیاتی اعلان ایمیلی فوری را آغاز می‌کنند، در حالی که تمام خطاهای منحصربه‌فرد برای ایجاد مسئله در جیرا آماده می‌شوند.

گره‌ها:

• Code (Assess Severity)
• IF (آیا خطای حیاتی وجود دارد؟)
• Email Send (Critical Alert Email)
• Code (Prepare Jira Issue)

#### گره: Code (Assess Severity)

• نوع: code
• نقش: هر مورد خطا را با فیلد severity بر اساس تطابق کلمات کلیدی غنی می‌کند.
• منطق: بررسی می‌کند که آیا level یا message حاوی کلمات کلیدی مانند "critical"، "fatal" یا "panic" (بدون در نظر گرفتن بزرگی و کوچکی حروف) است. در صورت یافتن، severity: 'critical' و در غیر این صورت severity: 'normal' را اختصاص می‌دهد.
• ورودی/خروجی: ورودی را از "Any New Errors?" (شاخه true) دریافت کرده و به گره IF "Critical Errors?" و گره Code "Prepare Jira Issue" تقسیم می‌شود.
• ملاحظات شکست: اگر فیلدهای level یا message وجود نداشته باشند، شدت به طور پیش‌فرض normal خواهد بود. تطابق کلمات کلیدی می‌تواند منجر به مثبت کاذب یا منفی کاذب شود؛ در صورت دسترسی به سطوح شدت عددی ساختاریافته، استفاده از آن‌ها را در نظر بگیرید.

#### گره: IF (آیا خطای حیاتی وجود دارد؟)

• نوع: if
• نقش: موارد را فیلتر کرده و فقط موارد طبقه‌بندی شده به عنوان critical را به مسیر اعلان فوری هدایت می‌کند.
• شرط: $json.severity برابر با "critical".
• ورودی/خروجی: ورودی را از "Assess Severity" دریافت می‌کند. شاخه true به "Critical Alert Email" هدایت می‌شود. موارد غیر حیاتی از این مسیر عبور نمی‌کنند.
• ملاحظات شکست: هیچ شاخه خروجی "false" استفاده نمی‌شود، به این معنی که موارد غیر حیاتی به سادگی از اعلان ایمیل فوری عبور می‌کنند.

#### گره: Email Send (Critical Alert Email)

• نوع: emailSend
• نقش: برای خطاهای حیاتی اعلان ایمیلی فوری ارسال می‌کند.
• پیکربندی:

* To: user@example.com (ایمیل گیرنده را جایگزین کنید).

* From: user@example.com (ایمیل فرستنده را جایگزین کنید).

* Subject: Critical Error Alert – {{ $json.message }}.

* Body: به طور صریح پیکربندی نشده است؛ ممکن است مقادیر پیش‌فرض اعمال شود. برای محتوای غنی‌تر، پیکربندی بدنه HTML یا متنی را در نظر بگیرید.

• ورودی/خروجی: ورودی را از "Critical Errors?" (شاخه true) دریافت کرده و به "Collect Issue Keys" (به عنوان ورودی ایندکس ۱) خروجی می‌دهد.
• ملاحظات شکست: مشکلات اعتبارنامه SMTP، رد شدن توسط رله ایمیل، یا آدرس‌های ایمیل نامعتبر می‌توانند باعث شکست شوند. اگر فیلد $json.message وجود نداشته باشد، خط موضوع ناقص خواهد بود.

#### گره: Code (Prepare Jira Issue)

• نوع: code
• نقش: یک بار (payload) اولیه برای ایجاد یک مسئله در جیرا می‌سازد.
• منطق:

* Project Key: 'PROJ' (کلید پروژه جیرا خود را جایگزین کنید).

* Summary: به صورت [SEVERITY] <اولین ۸۰ کاراکتر پیام> فرمت‌بندی می‌شود.

* Description: کل بار (payload) JSON مورد خطا، با استفاده از رشته و تورفتگی.

• ورودی/خروجی: ورودی را از "Assess Severity" دریافت کرده و به گره "Rate Limit Wait" خروجی می‌دهد.
• ملاحظات شکست: جیرا ممکن است به فیلدهای اضافی (مانند issuetype) یا فرمت‌بندی توضیحات خاص (مانند Atlassian Document Format برای Jira Cloud) نیاز داشته باشد. اگر فیلد message تعریف نشده باشد، خلاصه خالی خواهد بود و ممکن است باعث شود جیرا ایجاد مسئله را رد کند.

---

بلوک ۴: ایجاد مسئله در جیرا، جمع‌آوری و خلاصه ایمیل

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

گره‌ها:

• Wait (Rate Limit Wait)
• Jira (Create Jira Issue)
• Merge (Collect Issue Keys)
• Code (Generate Summary)
• Set (Format Summary Email)
• Email Send (Daily Summary Email)

#### گره: Wait (Rate Limit Wait)

• نوع: wait
• نقش: تاخیر بین درخواست‌ها را برای جلوگیری از رسیدن به محدودیت‌های نرخ API جیرا پیاده‌سازی می‌کند.
• پیکربندی: مدت زمان مشخص نشان داده نشده است و باید در رابط کاربری پیکربندی شود.
• ورودی/خروجی: ورودی را از "Prepare Jira Issue" دریافت کرده و به "Create Jira Issue" خروجی می‌دهد.
• ملاحظات شکست: اگر مدت زمان تنظیم نشده باشد، محدودیت نرخ ممکن است مؤثر نباشد. برای حجم بالا، پیاده‌سازی مکانیزم‌های تلاش مجدد تطبیقی یا عقب‌نشینی (backoff) را در نظر بگیرید.

#### گره: Jira (Create Jira Issue)

• نوع: jira
• نقش: بر اساس بار (payload) آماده شده، یک مسئله در جیرا ایجاد می‌کند.
• پیکربندی:

* Resource: باید روی "Issue" تنظیم شود.

* Operation: باید روی "Create" تنظیم شود.

* فیلدها باید از خروجی گره "Prepare Jira Issue" نگاشت شوند.

• اعتبارنامه‌ها: نیاز به اعتبارنامه‌های پیکربندی شده جیرا (OAuth2 یا توکن API، بسته به نسخه جیرا شما) دارد.
• ورودی/خروجی: ورودی را از "Rate Limit Wait" دریافت کرده و به "Collect Issue Keys" (به عنوان ورودی ایندکس ۰) خروجی می‌دهد.
• ملاحظات شکست: شکست‌ها می‌توانند به دلیل اعتبارنامه‌های گمشده، مجوزهای ناکافی، کلیدهای پروژه نامعتبر، یا فیلدهای الزامی گمشده رخ دهند. توضیحات Jira Cloud ممکن است به Atlassian Document Format (ADF) نیاز داشته باشند.

#### گره: Merge (Collect Issue Keys)

• نوع: merge
• نقش: جریان‌های خروجی از ایجاد مسئله در جیرا و مسیرهای اعلان ایمیلی حیاتی را ترکیب می‌کند.
• پیکربندی: حالت ادغام باید در تنظیمات گره بررسی شود.
• ورودی/خروجی:

* ورودی ۰: داده‌ها را از "Create Jira Issue" دریافت می‌کند.

* ورودی ۱: داده‌ها را از "Critical Alert Email" دریافت می‌کند.

* داده‌های ترکیبی را به گره "Generate Summary" خروجی می‌دهد.

• ملاحظات شکست: اگر یک جریان ورودی هیچ موردی ارائه ندهد (به عنوان مثال، هیچ ایمیل حیاتی ارسال نشده باشد)، رفتار ادغام به حالت انتخاب شده بستگی دارد و ممکن است داده‌ها را مسدود یا حذف کند. ترکیب طرح‌های مورد متفاوت (نتایج جیرا در مقابل تأییدیه‌های ایمیل) می‌تواند منطق تولید خلاصه را پیچیده کند.

#### گره: Code (Generate Summary)

• نوع: code
• نقش: آمار را جمع‌آوری کرده و داده‌ها را برای ایمیل خلاصه آماده می‌کند.
• منطق:

* تمام موارد ورودی را در یک آرایه all جمع‌آوری می‌کند.

* total موارد پردازش شده را محاسبه می‌کند.

* موارد critical را بر اساس کلمات کلیدی در فیلد summary شمارش می‌کند.

* یک شیء حاوی total، critical، issues (موارد جمع‌آوری شده) و یک timestamp خروجی می‌دهد.

• ورودی/خروجی: ورودی را از شاخه‌های مختلف (مانند "Has Logs?" false، "Any New Errors?" false، "Collect Issue Keys") دریافت کرده و به "Format Summary Email" خروجی می‌دهد.
• ملاحظات شکست: این منطق فرض می‌کند که موارد دارای فیلد .summary هستند، که ممکن است اگر موارد از گره "Critical Alert Email" یا مسیر "no logs" نشأت گرفته باشند، وجود نداشته باشد. این می‌تواند منجر به شمارش نادرست موارد حیاتی و یک آرایه issues مختلط شود. برای شمارش دقیق خطاهای حیاتی، این معیار را قبل از گره‌های Jira/ایمیل محاسبه کنید.

#### گره: Set (Format Summary Email)

• نوع: set
• نقش: برای ساختاردهی فیلدها برای ایمیل خلاصه نهایی، مانند موضوع و بدنه، در نظر گرفته شده است.
• پیکربندی: در حال حاضر خالی است (options: {})، به این معنی که فیلدهای subject یا body را به طور صریح تنظیم نمی‌کند.
• ورودی/خروجی: ورودی را از "Generate Summary" دریافت کرده و به "Daily Summary Email" خروجی می‌دهد.
• ملاحظات شکست: گره "Daily Summary Email" به $json.subject ارجاع می‌دهد. بدون پیکربندی در این گره Set، موضوع ایمیل احتمالاً گمشده یا پیش‌فرض خواهد بود.

#### گره: Email Send (Daily Summary Email)

• نوع: emailSend
• نقش: ایمیل خلاصه تجمیع شده را ارسال می‌کند.
• پیکربندی: نیاز به پیکربندی برای گیرنده(ها)، فرستنده، موضوع و بدنه دارد. موضوع و بدنه باید با استفاده از عباراتی که به داده‌های جمع‌آوری شده ارجاع می‌دهند، به طور پویا پر شوند.
• ورودی/خروجی: ورودی را از "Format Summary Email" دریافت می‌کند.
• ملاحظات شکست: مشابه ایمیل هشدار حیاتی، پیکربندی SMTP و آدرس‌های معتبر حیاتی هستند. اطمینان حاصل کنید که موضوع و بدنه با استفاده از ارجاعات به داده‌های تجمیع شده به درستی فرمت‌بندی شده‌اند.