سجلاتنا كانت فوضى: كيف أنقذنا التسجيل المنظم (Structured Logging) من جحيم التنقيح

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

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

INFO: Payment process started for user 123
WARNING - Could not validate credit card for order 9876.
Error processing payment for user XYZ. Details: network timeout.
[2023-10-27 02:15:30] INFO: User 456 successfully completed purchase.

كنت أبحث عن كلمة “error” أو “fail”، ولكن النتائج كانت خليطاً عجيباً. بعضها يحتوي على هوية المستخدم (user ID) وبعضها لا. بعضها يذكر تفاصيل الخطأ وبعضها يكتفي بكلمة “Error”. بعد ساعة من التحديق في الشاشة، شعرت بالإحباط يسيطر عليّ. صرخت في نفسي “يا زلمة شو هالفوضى! كيف بدنا نلاقي إشي بهالزحمة؟”.

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

ما هو التسجيل التقليدي (غير المنظم)؟ ولماذا هو كارثة صامتة؟

التسجيل غير المنظم هو ما يفعله معظمنا بشكل طبيعي في بداية مسيرتنا البرمجية. ببساطة، هو كتابة رسائل نصية حرة إلى ملف أو إلى الطرفية (console) لوصف ما يحدث في التطبيق. تبدو هكذا:

log.info("بدأ المستخدم عملية تسجيل الدخول.");
log.error("فشلت عملية الدفع للمستخدم " + userId + " بسبب: " + errorMsg);

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

• صعوبة البحث والفلترة: هل تريد العثور على كل الأخطاء المتعلقة بمستخدم معين؟ حظاً موفقاً في كتابة تعابير نمطية (Regular Expressions) معقدة للبحث في نصوص عشوائية.
• صيغة غير متسقة: مطور يكتب “User ID:” وآخر يكتب “userId=” وثالث لا يكتبها إطلاقاً. هذه الفوضى تجعل التحليل الآلي شبه مستحيل.
• غير صديق للآلات: هذه السجلات مصممة ليقرأها البشر (بصعوبة)، وليس لتفهمها الآلات. لا يمكنك بسهولة إدخالها في أنظمة المراقبة والتحليل لإنشاء رسوم بيانية أو تنبيهات ذكية.
• فقدان السياق: الرسالة “Payment Failed” وحدها لا تكفي. أين هوية المستخدم؟ هوية الطلب؟ كم كان المبلغ؟ كل هذه المعلومات تضيع في بحر النصوص.

دخول البطل: التسجيل المنظم (Structured Logging)

بعد ليلة التنقيح المظلمة تلك، عقدنا اجتماعاً للفريق وكان القرار واضحاً: يجب أن نعامل سجلاتنا كبيانات (Data)، وليس كنصوص عشوائية. وهنا يأتي دور التسجيل المنظم.

ما هو بالضبط؟

التسجيل المنظم هو ممارسة تسجيل الأحداث كأزواج من المفاتيح والقيم (key-value pairs) بدلاً من سلسلة نصية حرة. أشهر صيغة مستخدمة هي JSON، لأنها مقروءة للبشر وسهلة الفهم للآلات.

لنقارن بين المثالين:

قبل (تسجيل غير منظم):

“Error processing payment for user with ID 5582 for order 9876, amount $99.99. Reason: Insufficient funds.”

بعد (تسجيل منظم بصيغة JSON):

{
  "timestamp": "2023-10-27T02:30:00Z",
  "level": "error",
  "message": "Payment processing failed",
  "event_type": "payment_failure",
  "user_id": 5582,
  "order_id": "ord-9876",
  "amount": 99.99,
  "currency": "USD",
  "reason": "insufficient_funds"
}

هل ترى الفرق؟ المعلومة نفسها، لكنها الآن منظمة، متسقة، وقابلة للاستعلام. لم نعد بحاجة لتخمين مكان هوية المستخدم أو سبب الفشل. كل شيء في مكانه الصحيح.

لماذا هو الحل السحري؟ (الفوائد العملية)

1. بحث وتحليل فائق السرعة: يمكنك الآن استخدام أدوات تحليل السجلات (مثل ELK Stack, Graylog, Datadog) لتشغيل استعلامات تشبه استعلامات قواعد البيانات. مثال: level:error AND reason:"insufficient_funds". يمكنك العثور على المشكلة في ثوانٍ بدلاً من ساعات.
2. تنبيهات ذكية ودقيقة: بدلاً من التنبيه عند ظهور كلمة “error”، يمكنك الآن إنشاء قواعد أكثر ذكاءً. مثلاً: “أرسل تنبيهاً لفريق الدعم إذا زاد عدد الأخطاء من نوع payment_failure عن 10 في الدقيقة الواحدة”.
3. الرؤية الشاملة (Observability): التسجيل المنظم هو حجر الأساس في بناء أنظمة قابلة للمراقبة. عندما تضيف “معرّف ارتباط” (Correlation ID) لكل سجل، يمكنك تتبع طلب المستخدم عبر خدمات متعددة (Microservices) ورؤية القصة الكاملة لرحلته داخل نظامك.
4. التناسق والتوحيد القياسي: يجبر الفريق على التفكير في “ماذا” نسجل بدلاً من “كيف” نكتب الرسالة. هذا يخلق لغة مشتركة بين كل المطورين والخدمات.

كيف نبدأ؟ دليل عملي مع أمثلة

الانتقال للتسجيل المنظم أسهل مما تتوقع. معظم لغات البرمجة لديها مكتبات قوية تدعم هذا المفهوم بشكل مباشر.

الخطوة الأولى: اختيار المكتبة المناسبة

لا تخترع العجلة. ابحث عن مكتبة تسجيل منظمة مشهورة في لغتك. في عالم بايثون، مكتبة structlog هي خيار ممتاز، ولكن يمكنك أيضاً تحقيق ذلك باستخدام مكتبة logging المدمجة مع مُنسّق JSON.

الخطوة الثانية: التطبيق العملي (مثال بايثون)

لنرَ الفرق بشكل عملي. هذا مثال بسيط باستخدام مكتبة logging القياسية في بايثون (الطريقة القديمة):

import logging

logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

def process_order(user_id, order_id):
    logging.info(f"Processing order {order_id} for user {user_id}.")
    try:
        # ... بعض المنطق البرمجي الذي قد يفشل
        raise ValueError("Insufficient stock")
    except ValueError as e:
        logging.error(f"Failed to process order {order_id} for user {user_id}. Reason: {e}")

process_order("user-123", "order-abc")

الناتج (غير منظم):

2023-10-27 10:20:30,123 - INFO - Processing order order-abc for user user-123.
2023-10-27 10:20:30,124 - ERROR - Failed to process order order-abc for user user-123. Reason: Insufficient stock

الآن، لنقم بنفس الشيء باستخدام مكتبة structlog للحصول على سجلات منظمة:

import structlog

# تهيئة structlog لطباعة JSON
structlog.configure(
    processors=[
        structlog.processors.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer(),
    ]
)

log = structlog.get_logger()

def process_order_structured(user_id, order_id):
    # ربط السياق باللوجر
    s_log = log.bind(user_id=user_id, order_id=order_id)
    
    s_log.info("order_processing_started")
    try:
        # ... بعض المنطق البرمجي الذي قد يفشل
        raise ValueError("Insufficient stock")
    except ValueError as e:
        s_log.error("order_processing_failed", reason=str(e), error_code=5001)

process_order_structured("user-123", "order-abc")

الناتج (منظم بصيغة JSON):

{"user_id": "user-123", "order_id": "order-abc", "level": "info", "timestamp": "2023-10-27T10:25:45.123Z", "event": "order_processing_started"}
{"user_id": "user-123", "order_id": "order-abc", "reason": "Insufficient stock", "error_code": 5001, "level": "error", "timestamp": "2023-10-27T10:25:45.124Z", "event": "order_processing_failed"}

لاحظ كيف أن كل سطر هو كائن JSON صالح. الحقول user_id و order_id موجودة في كل من سجل المعلومات وسجل الخطأ بشكل تلقائي بفضل bind. هذا هو السحر بعينه!

نصائح من “الختيار” (خبرة أبو عمر)

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

• وحدوا المفاتيح (Standardize Keys): قبل أن يكتب فريقك سطراً واحداً من السجلات المنظمة، اجلسوا معاً واتفقوا على أسماء المفاتيح. هل هو userId, user_id, أم userIdentifier؟ اتفقوا على معيار واحد والتزموا به. هذا يوفر عليكم الكثير من الألم لاحقاً.
• أضف السياق دائمًا (Always Add Context): لا تكتفِ بتسجيل رسالة الخطأ. أضف كل ما يمكن أن يساعدك في فهم المشكلة: هوية الطلب (request ID)، هوية الجلسة (session ID)، اسم الخدمة، الإصدار، إلخ. استخدم “معرّف الارتباط” (Correlation ID) لربط جميع السجلات المتعلقة بطلب واحد معًا.
• لا تسجل معلومات حساسة أبداً! (Never Log Sensitive Data): هذه قاعدة ذهبية. تجنب تسجيل كلمات المرور، أرقام بطاقات الائتمان، أرقام الهوية الشخصية، أو أي معلومات تعريف شخصية (PII). هذا ليس فقط ممارسة سيئة، بل قد يكون غير قانوني في بعض الأماكن.
• استخدم مستويات التسجيل بحكمة: لا تجعل كل شيء INFO.
  • DEBUG: للمعلومات التفصيلية التي تحتاجها فقط أثناء التطوير.
  • INFO: للأحداث الهامة في دورة حياة التطبيق (بدء التشغيل، طلب جديد).
  • WARN: لأشياء غير متوقعة ولكنها لا تكسر النظام (مثل محاولة فاشلة ثم نجاح).
  • ERROR: للأخطاء التي تحتاج إلى تدخل فوري.
• الأداء مهم: عملية التسجيل، خاصة الكتابة على القرص، يمكن أن تكون بطيئة. استخدم مكتبات تدعم التسجيل غير المتزامن (Asynchronous Logging) لكي لا تبطئ تطبيقك الرئيسي.

الخلاصة: من الفوضى إلى الوضوح 🚀

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

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

يلا يا جماعة، رتبوا سجلاتكم، بترتاحوا وبتريّحوا.