كيف تصمم Workflow يترك سجلًا واضحًا لكل خطوة؟

في أي نظام أتمتة جاد، لا تكفي فكرة أن المهمة انتهت بنجاح؛ فالسؤال الحقيقي الذي يطرحه المهندس عند الفشل هو: أين توقفت العملية، وما البيانات التي كانت بحوزتها حين توقفت؟ تصميم Workflow يترك سجلًا واضحًا لكل خطوة ليس رفاهية تقنية، بل هو الفرق بين تشخيص يستغرق دقائق وسباق تخمين قد يمتد ساعات. السجل الجيد يحوّل النظام من صندوق أسود إلى مسار مرئي يمكن تتبعه وإعادة بناء أحداثه. في هذا المقال نشرح كيف تبدأ من تعريف بنية السجل قبل كتابة منطق التنفيذ، وكيف تربط الخطوات بمعرّف واحد، وتختار البيانات التي تستحق التدوين، وتحمي الخصوصية دون إفشال قابلية المراقبة. سنقدّم إرشادات عملية قابلة للتطبيق فورًا، مع أمثلة افتراضية واضحة نميّزها صراحة عن القواعد العامة.

ابدأ بتعريف مخطط السجل قبل كتابة أول خطوة

أكثر خطأ متكرر هو إضافة عبارات الطباعة أثناء كتابة الكود ثم محاولة ترتيبها لاحقًا. الأفضل أن تعرّف مخطط السجل أولًا: ما الحقول الإلزامية التي سترافق كل خطوة؟ عادة تحتاج معرّف التنفيذ، واسم الخطوة، والطابع الزمني، ونوع الحدث، والكائن المتأثر، وحالة النجاح أو الفشل. هذا المخطط يعمل كعقد بين كل الأجزاء، فلا يخترع كل فريق حقولًا خاصة به. عندما توحّد الحقول مبكرًا يصبح تحليل السجل آليًا ممكنًا، وتنخفض تكلفة البحث اليدوي عند الأعطال.

مثال افتراضي: تخيل Workflow يزامن بيانات عملاء بين خدمتين. لو اتفق الفريق مسبقًا على حقول ثابتة مثل اسم الخطوة ورقم النسخة ومعرّف السجل، فإن رسالة واحدة تكفي لمعرفة أن الفشل حدث في خطوة التحقق قبل الإرسال. اجعل المخطط موثّقًا وقابلًا للترقيم، وخصص رقم إصدار لكل تعديل جوهري. بهذه الطريقة لا تنكسر أدوات التحليل القديمة، ويستطيع أي مهندس جديد فهم سجل لم يكتبه بنفسه دون سؤال أحد.

معرّف تتبع واحد يربط كل خطوات التنفيذ

لكل تشغيل سجل متماسك، يجب أن يوجد معرّف فريد يُنشأ عند بدء ال ـ Workflow ويُمرّر إلى كل خطوة وكل خدمة تُستدعى. هذا المعرّف، الذي يسمى غالبًا معرّف التتبع أو معرّف التشغيل، هو الخيط الذي يحوّل آلاف الأسطر المتناثرة إلى قصة واحدة. من دون هذا التمرير ستجد نفسك تبحث يدويًا عن السجلات المتقاربة زمنيًا، وهو أسلوب هش ينهار عند التشغيل المتوازي.

عمليًا، احمل المعرّف داخل كائن سياق ينتقل بين الدوال والخدمات، وأضفه تلقائيًا إلى كل سطر سجل بدلًا من كتابته يدويًا. في الأنظمة الموزعة يمكن إضافة معرّف أصلي ومعرّف فرعي لكل خطوة لتوضيح العلاقة بين الأب وأبنائه. هذا التسلسل الهرمي يسمح بمعرفة أن خطوة الإرسال فشلت لأن خطوة التحقق سبق أن أعادت نتيجة غير متوقعة، دون تخمين.

السجل المهيكل أفضل من الجمل النصية الحرّة

السجل النصي الحر، مثل رسالة تقول إن العملية فشلت، مريح في البداية لكنه يصعب البحث فيه لاحقًا. الأفضل كتابة السجل بصيغة مهيكلة مثل أزواج مفتاح وقيمة أو كائن JSON، حيث يحمل كل حدث حقولًا ثابتة الأسماء. هكذا تستطيع الاستعلام عن كل الخطوات التي فشلت في نوع معين، أو حساب متوسط مدة خطوة محددة، من دون تعبيرات بحث هشة تعتمد على صياغة نصية عابرة.

عند الكتابة المهيكلة التزم بأسماء حقول ثابتة وحروف موحدة، لأن تغيير الاسم من خطوة لأخرى يكسر الاستعلامات. اجعل القيم المتغيرة في موضع مخصص وليس داخل نص حر، وخصص حقولًا منفصلة للكائن والنتيجة ورمز الخطأ. القاعدة العملية: إن كان الحقل مهمًا للبحث أو التنبيه فليكن حقلًا مستقلًا، وإن كان شرحًا بشريًا فليكن في حقل رسالة منفصل.

مستويات السجل: متى تستخدم info و warn و error

الخلط بين مستويات السجل يغرق الفريق في ضجيج لا قيمة له. امنح كل مستوى معنى واضحًا: معلومات للخطوات الطبيعية التي تثبت التقدم، وتحذير للحالات غير المتوقعة التي لم تفشل بعد، وخطأ للفشل الذي يحتاج تدخلًا. هذا التصنيف يسمح بتصفية السجل حسب الحاجة بدلًا من قراءة كل شيء في كل مرة. حين تكون المستويات متسقة تصبح اللوحات والتنبيهات مبنية على أساس موثوق لا على تخمين.

لا تسجل كل تفصيل داخلي في المستوى المعلوماتي، لأن ذلك يخفي الخطوات المهمة بين مئات الأسطر. الأفضل تسجيل نقاط القرار وانتقالات الحالة والمخرجات النهائية فقط. اكتب أيضًا في دليل الفريق قاعدة متفقًا عليها لما يستحق المستوى الأعلى، حتى لا يختلف المهندسون في التقدير. الاتساق هنا أهم من الكمال، لأن السجل الذي لا يفهمه غيرك لا قيمة له عند وقوع الحادث.

سجّل انتقالات الحالة لا الأحداث المتفرقة

إذا كان ال ـ Workflow يمر بحالات معروفة مثل الاستلام والتحقق والمعالجة والإرسال والانتهاء، فالأفضل تسجيل الانتقال بين الحالة السابقة والحالة الجديدة صراحة. هذا يجعل السجل يصف مسار العملية كاملًا، ويسمح بإعادة بناء الحالة الأخيرة حتى لو فُقد جزء من البيانات. أما تسجيل الأحداث المتفرقة وحدها فيجبرك على استنتاج الترتيب ذهنيًا، وهو أمر غير موثوق عند تعدد التشغيلات.

ميزة أخرى لسجلات الانتقال أنها تكشف الأخطاء المنطقية التي لا يلتقطها الاختبار العادي، مثل الوصول إلى حالة غير مسموح بها أو تكرار خطوة مرتين. اجعل كل انتقال يسجل السبب والجهة المسببة والمدة المستغرقة. بهذه الطريقة يصبح السجل وسيلة تشخيص ووسيلة تدقيق في الوقت نفسه، وهو ما تحتاجه أي مؤسسة تتعامل مع عمليات حساسة أو مؤثرة على بيانات العملاء.

المدخلات والمخرجات: ماذا تسجّل من البيانات

قرار تدوين البيانات الحساس قرار موازنة. تسجيل كل المدخلات والمخرجات يفيد التشخيص لكنه قد يحوّل السجل إلى مخزن أسرار. الحل أن تسجل ما يكفي لإعادة إنتاج المشكلة من دون كشف البيانات الحساسة: مثلًا اكتب أن الحقل موجود ولماذا يفشل التحقق، أو سجل بصمة مختصرة بدلًا من القيمة الكاملة. بهذه المقاربة تحافظ على قابلية المراقبة مع احترام حدود الخصوصية.

مثال افتراضي: Workflow يرسل ملفًا، لا داعي لتدوين محتوى الملف كاملًا، بل اسمه وحجمه ونوعه وبصمته. أما معرّفات المستخدمين فأبقِها إن كانت لازمة للربط، مع تقنيع الحقول الشخصية. وثّق سياسة واضحة لما يُسجّل وما يُحجب، وراجعها مع الفريق الأمني، لأن قرار الحجب المتأخر غالبًا يعني حذف سجلات تاريخية بأكملها بعد فوات الأوان.

الفشل وإعادة المحاولة: سجل يشرح ما حدث فعلًا

عند الفشل لا يكفي كتابة أن الخطوة فشلت. سجّل رمز الخطأ والرسالة التقنية واسم المكوّن الذي أعاد الخطأ، وأضف مرجعًا إن كان الأثر الكامل مخزّنًا في مكان آخر. هذا يمكّن من تمييز الفشل المؤقت بسبب الشبكة من الفشل المنطقي الذي سيتكرر ما لم يتغير شيء. الفصل بين النوعين يوجّه جهود المعالجة بدلًا من تكرار المحاولات بلا طائل.

عند إعادة المحاولة سجّل كل محاولة برقمها ونتيجتها والمدة قبل الإعادة. الأهم تسمية مفتاح يمنع التنفيذ المزدوج، حتى تعرف هل إعادة الإرسال آمنة أم لا. هذا السجل التفصيلي يجيب عن السؤال الأكثر إزعاجًا: هل المشكلة في العملية نفسها أم في إعادة تكرارها بدون ضبط؟ حين يكون الجواب واضحًا من السجل تنخفض مدة الاستجابة كثيرًا.

الطوابع الزمنية والمدد الزمنية وضبط الساعات

الطابع الزمني سيئ الاستخدام أكثر ضررًا من غيابه. استخدم توقيتًا موحدًا وواضحًا، ويفضل التوقيت العالمي الموحد مع ذكر المنطقة عند الحاجة للعرض. هذا يمنع الالتباس عند جمع سجلات من خوادم في مناطق زمنية مختلفة، وهو خطأ شائع يجعل الترتيب الزمني للأحداث غير موثوق، ويؤدي إلى استنتاجات خاطئة عن تسلسل الأعطال.

لا تعتمد على الفروق بين الطوابع لحساب المدة إن كانت الساعات غير مضبوطة؛ سجّل زمن البداية وزمن النهاية ثم المدة المحسوبة داخليًا. هذا يسمح بتمييز الخطوات البطيئة فعلًا من الخطوات التي بدت بطيئة بسبب انحراف الساعات. وأضف عند الإمكان معرّف الخادم أو مثيل التشغيل، لأن تشغيل نفس الخطوة على أكثر من خادم يجعل السجل بلا هوية مضلّلًا.

الخصوصية والاحتفاظ: سجل آمن وقابل للتشغيل

السجل الجيد يحقق هدفين متوازيين: يكفي للتشخيص ولا يكشف ما لا يجب كشفه. صنّف البيانات مسبقًا إلى عامة وحساسة وسرية، وحدد أي حقل يُحجب كليًا وأي حقل يُقنّع جزئيًا. اجعل هذه القواعد في طبقة مركزية بدلًا من تركها لكل مطوّر، لأن الاعتماد على الانضباط الفردي يفشل مع الوقت وتزايد حجم الفريق وتعاقب الأعضاء عليه.

حدد أيضًا مدة الاحتفاظ لكل نوع سجل، فسجلات التدقيق الأمني تحتاج عمرًا أطول من سجلات التصحيح المطوّلة. وافصل بين سجل التدقيق الذي يوثق من فعل ماذا ومتى، وسجل التصحيح الذي يشرح كيف تم التنفيذ تقنيًا. هذا الفصل يبسّط الصلاحيات، ويمنع أن يحتوي سجل التدقيق الرسمي على تفاصيل تقنية بلا معنى قانوني، ويقلل حجم البيانات المخزّنة.

اجعل السجل قابلًا للقراءة والبحث والتنبيه

السجل الذي لا يمكن البحث فيه بسرعة شبه معدوم الفائدة. صمّم الحقول بحيث تجيب عن أسئلة مثل: أين توقف هذا التشغيل، وما الخطوات التي تجاوزت مدتها المعتادة، وكم مرة فشلت خطوة الإرسال هذا الأسبوع. معرّف التتبع والحقول المهيكلة يجعلان هذه الأسئلة استعلامات بسيطة بدلًا من جهد يدوي طويل عند كل حادث يقترب.

تجاوز البحث اليدوي إلى التنبيهات واللوحات لما يستحق المتابعة المستمرة، مثل ارتفاع معدل الفشل أو تعطّل خطوة حيوية. حدد مالكًا لكل تنبيه حتى لا يتحول إلى ضجيج مهمل. وثّق مسارًا واضحًا من التنبيه إلى السجل الخام، فينتقل المناوب من المؤشر إلى السبب في خطوات قليلة بدلًا من التخمين أو انتظار مالك الخدمة.

اختبر السجل كما تختبر الكود

قابلية المراقبة ليست نتيجة تلقائية للكود الجيد، بل خاصية تحتاج اختبارًا مستقلًا. أضف اختبارات تتحقق من وجود الحقول الإلزامية في مخرجات السجل ومن صحة تنسيقها. هذا يمنع تسرب سجل ناقص إلى الإنتاج بسبب تعديل عابر، ويجعل الوضوح جزءًا من تعريف الاكتمال لأي مهمة جديدة، فلا تُعدّ الميزة منجزة قبل أن يكون أثرها قابلًا للتتبع.

راجع السجل خلال اختبار قبول واقعي: شغّل السيناريو ثم حاول الإجابة عن أسئلة التشخيص باستخدام السجل وحده. إن اضطررت لقراءة الكود لتفهم ما حدث فالسجل ناقص. أضف ما ينقص وكرر المحاولة، ثم وثّق أمثلة السجل المتوقع في دليل التشغيل ليستخدمها الفريق مرجعًا في الأعطال القادمة ويسرّع الاستجابة.

أسئلة شائعة

ما أهم حقل يجب أن يحتوي عليه سجل كل خطوة؟

معرّف التتبع هو الحقل الأهم لأنه يربط كل القطع ببعضها، لكنه لا يعمل وحده. احرص على وجود اسم الخطوة، والطابع الزمني، ونوع الحدث، وحالة النتيجة. هذه الحقول مجتمعة تسمح لك بالإجابة عن سؤالين فورًا: أين حدث الشيء، وفي أي تشغيل بالتحديد. من دون معرّف تتبع يتحول التحليل إلى تخمين.

هل يجب تسجيل كل المدخلات والمخرجات في السجل؟

لا، تسجيل كل شيء يحوّل السجل إلى مخزن أسرار ويرفع الكلفة دون فائدة واضحة. سجّل ما يكفي لإعادة إنتاج المشكلة: نوع البيانات، وحالة التحقق، وبصمة الملف بدلًا من محتواه. احجب البيانات الشخصية أو قنّعها وفق سياسة موثقة، وراجع هذه السياسة دوريًا مع الفريق الأمني لأن القرار الخاطئ يصعب تصحيحه لاحقًا.

كيف أمنع إعادة المحاولة من تشويش السجل؟

سجّل كل محاولة كحدث مستقل مع رقم المحاولة ونتيجتها والمدة قبل الإعادة، واربطها جميعًا بمعرّف التتبع نفسه. استخدم مفتاحًا يمنع التنفيذ المزدوج حتى تعرف إن كانت الإعادة آمنة. بهذه الطريقة يظهر التسلسل بوضوح: المحاولة الأولى فشلت لسبب مؤقت، والثانية نجحت، أو تكرر الفشل نفسه لأسباب منطقية تحتاج إصلاحًا.

هل السجل المهيكل مناسب لمشروع صغير؟

نعم، والفائدة أكبر مما يبدو لأن الأنظمة الصغيرة تنمو بسرعة. البدء بأزواج مفتاح وقيمة بسيطة لا يستهلك جهدًا كبيرًا، لكنه يمنحك أساسًا قابلًا للتوسع لاحقًا. الأهم أن تختار أسماء حقول ثابتة من البداية وتوثقها، فتصبح أدوات البحث والتنبيه ممكنة عند الحاجة إليها دون إعادة كتابة كل شيء.