تخطّى إلى المحتوى الرئيسي
التسجيل المنظّم في Node.js وNestJS باستخدام Pino 10: كيف نضيف معرّف الطلب ونخفي الأسرار ونحافظ على تتبّع الأخطاء

التسجيل المنظّم في Node.js وNestJS باستخدام Pino 10: كيف نضيف معرّف الطلب ونخفي الأسرار ونحافظ على تتبّع الأخطاء

November 19, 2026
هندسة الأنظمة الخلفية
8 دقيقة قراءة

العنوان الرئيسي: التسجيل المنظّم (Structured logging) يكتب كل حدث سجل ككائن JSON بحقول ثابتة مثل level وtime وmsg وrequestId، بحيث تستطيع منصة السجلات تصفية الأسطر وربطها بدل البحث النصي عبر grep. نستخدم Pino 10 لهذا الغرض في Node.js وNestJS، والعمل الحقيقي ليس في تثبيته، بل في تمرير معرّف الطلب عبر الكود غير المتزامن، وإخفاء الترويسات التي يسجّلها pino-http افتراضيًا، وتمرير الأخطاء بطريقة تحفظ تتبّع المكدس (stack trace).

كانت خدماتنا المبنية على Node.js تسجّل باستخدام console.log والسلاسل النصية المركّبة. ينجح ذلك حتى يعمل طلبان في الوقت نفسه: تتداخل الأسطر، ولا شيء يربط خطأ قاعدة البيانات بطلب HTTP الذي سبّبه، ولغة الاستعلام الوحيدة هي grep. أصلحت مكتبة Pino، وهي مسجّل JSON منخفض الكلفة لـ Node.js، شكل المخرجات بسرعة؛ أما ضبط الحقول الصحيحة فاستغرق وقتًا أطول. هذه ملاحظاتنا من نقل واجهات Express وNestJS البرمجية إلى Pino 10.3 مع pino-http وnestjs-pino.

أهم النقاط

• كائن JSON واحد لكل سطر: يكتب Pino صيغة JSON مفصولة بأسطر (NDJSON) تحتوي على level رقمي (30 يعني info و50 يعني error) ووقت time بالميلي ثانية، مع دمج حقولنا الخاصة.

• الترويسات تُسجَّل افتراضيًا: مُسلسِل الطلبات (request serializer) الذي يستخدمه pino-http من حزمة pino-std-serializers يتضمن كل ترويسات الطلب، لذلك تصل قيم Authorization وCookie إلى السجلات ما لم تغطّها مسارات redact.

• معرّف الطلب دون تمرير المسجّل يدويًا: يضيف AsyncLocalStorage في Node.js مع خيار mixin في Pino حقل requestId إلى كل سطر يُكتب أثناء الطلب، وتفعل nestjs-pino الشيء نفسه في NestJS.

• الخطأ أولًا: منذ الإصدار 6 من Pino يتجاهل الاستدعاء logger.error('failed', err) المتغير err بالكامل، بينما يحتفظ logger.error({ err }, 'failed') بنوع الخطأ ورسالته وتتبّع المكدس.

• المخرجات المنسّقة أداة تطوير: عمليات الإنتاج تكتب JSON إلى stdout وتتولى المنصة نقله، أما pino-pretty فيعمل محليًا فقط.

ما الذي يقدمه التسجيل المنظّم ولا يقدمه console.log؟

يمنح التسجيل المنظّم كل سطر سجل حقولًا قابلة للاستعلام، فيصبح طلب «كل أسطر الأخطاء لطلب واحد في خدمة المدفوعات» عملية تصفية بدل تعبير نمطي (regex). سلسلة نصية مثل 'Payment failed for order 123' تحمل المعلومات نفسها، لكن منصة السجلات لا تستطيع فهرسة رقم الطلبية داخلها، ولا شيء يربط السطر بالطلب الذي أنتجه.

قارنّا بين ثلاثة خيارات قبل اعتماد Pino:

• console.log: مخرجات نصية حرة، ومعرّفات الطلب تُضاف يدويًا، ولا إخفاء للأسرار، ولا حقول سياق مرتبطة.

• ConsoleLogger المدمج في NestJS 11 مع json: true: كائن JSON واحد لكل سطر ومستويات عبر خيار logLevels، لكن معرّفات الطلب والإخفاء تبقى يدوية، والسياق مجرد سلسلة نصية واحدة.

• Pino 10 مع pino-http أو nestjs-pino: كائن JSON واحد لكل سطر، ومعرّف طلب يُضاف تلقائيًا لكل طلب، ومسارات redact مدمجة، وخيار level يُقرأ من LOG_LEVEL، ومسجّلات فرعية بحقول مرتبطة عبر logger.child().

يُعد ConsoleLogger المدمج في NestJS 11 مع json: true خيارًا معقولًا لخدمة صغيرة. اخترنا Pino لأنه يضيف الأمرين اللذين كنا نعيد بناءهما يدويًا باستمرار: سياق خاص بكل طلب، وإخفاء الأسرار.

كيف نضيف معرّف الطلب إلى كل سطر سجل في Node.js؟

نخزّن معرّف الطلب في AsyncLocalStorage عند بداية كل طلب ونعيده من دالة mixin في Pino. تحتفظ AsyncLocalStorage، المستوردة من node:async_hooks، بقيمة متاحة عبر كل await وكل دالة رد نداء تعمل داخل als.run()، لذلك يستطيع كود في عمق طبقة المستودع (repository) التسجيل بالمسجّل المشترك والحصول على المعرّف الصحيح.

يتكون إعدادنا في Express من ثلاثة أجزاء. وحدة تنشئ new AsyncLocalStorage<{ requestId: string; userId?: string }>() ومسجّل Pino تعيد دالة mixin فيه نسخة من المخزن الحالي: mixin: () => ({ ...logContext.getStore() }). ووسيط (middleware) يقرأ ترويسة x-request-id الواردة ويقبلها فقط إذا طابقت النمط /^[\w-]{1,64}$/، وإلا ينشئ معرّفًا جديدًا عبر randomUUID() من node:crypto، ثم يعيده في ترويسة الاستجابة x-request-id ويستدعي logContext.run({ requestId }, next). بعدها يحمل كل استدعاء تسجيل أثناء معالجة ذلك الطلب قيمة requestId نفسها.

كلّفتنا تفصيلتان وقتًا. الأولى أن توثيق Pino ينص على أن Pino يعدّل الكائن الذي تعيده mixin()، لذلك فإن إعادة المخزن نفسه تسمح لاستدعاء تسجيل بكتابة حقول داخل سياق الطلب، والنسخة عبر عامل النشر (spread) تمنع ذلك. والثانية أن ترويسة x-request-id الواردة مُدخل من المستخدم، لذلك نقبلها فقط إذا طابقت نمطًا قصيرًا وآمنًا. إعادة المعرّف في ترويسة الاستجابة تسمح بإرفاقه في بلاغات الأخطاء، ويستطيع الوسيط الذي يعمل بعد المصادقة إضافة userId إلى المخزن ليظهر في كل الأسطر اللاحقة.

كيف نُعدّ Pino في NestJS دون فقدان سجلات الإقلاع؟

في NestJS نستخدم nestjs-pino، وهي تغلّف pino-http وتحتفظ بمسجّل فرعي خاص بالطلب داخل AsyncLocalStorage، فتحصل الخدمات على معرّف الطلب دون أي من الكود السابق. يتكون الإعداد من ثلاثة أجزاء: الوحدة، والإقلاع، والحقن.

في AppModule نستورد LoggerModule.forRoot({ pinoHttp: { ... } }) مع خمسة خيارات: level من LOG_LEVEL؛ ودالة genReqId(req, res) تعيد استخدام قيمة x-request-id الواردة إن كانت صالحة أو تنشئ UUID وتضعه في الاستجابة؛ ومسارات redact لكل من req.headers.authorization وreq.headers.cookie وres.headers["set-cookie"]؛ وautoLogging: { ignore: (req) => req.url === '/health' }؛ وناقل pino-pretty خارج بيئة الإنتاج فقط.

في main.ts ننشئ التطبيق عبر NestFactory.create(AppModule, { bufferLogs: true }) ثم نستدعي app.useLogger(app.get(Logger)) مع استيراد Logger من nestjs-pino. يحتفظ الخيار bufferLogs: true بالسجلات التي يكتبها NestJS أثناء بناء شجرة الوحدات، ثم يمررها عبر Pino بمجرد تنفيذ useLogger()؛ ومن دونه تخرج أسطر الإقلاع بصيغة Nest النصية الافتراضية وبقية الأسطر بصيغة JSON.

تصبح قيمة genReqId في pino-http هي req.id في كل سطر، ويمنع autoLogging.ignore فحوصات الصحة (health checks) من كتابة سطر «request completed» كل بضع ثوانٍ.

في الخدمات نحقن PinoLogger عبر @InjectPinoLogger(PaymentsService.name) ونسجّل دائمًا بكائن أولًا، مثل this.logger.info({ orderId }, 'capturing payment'). ولإضافة حقل إلى كل الأسطر المتبقية في الطلب الحالي، مثل معرّف المستخدم بعد أن يتحقق حارس (guard) من هويته، توفر nestjs-pino الدالة PinoLogger.assign({ userId }).

لماذا تظهر رموز Bearer وملفات تعريف الارتباط في السجلات؟

تظهر رموز Bearer وملفات تعريف ارتباط الجلسة في السجلات لأن pino-http يحوّل الطلب الوارد عبر pino-std-serializers، وهذا المُسلسِل يتضمن كائن headers كاملًا. ومُسلسِل الاستجابة يتضمن الترويسات من res.getHeaders()، ومنها set-cookie. لا يُخفى شيء ما لم يُدرج في خيار redact في Pino، لذلك أول ما نفحصه في أي إعداد جديد لـ pino-http هو سطر طلب واحد.

القواعد التي نتبعها لمسارات الإخفاء:

• المسارات حساسة لحالة الأحرف، وNode.js يحوّل أسماء الترويسات الواردة إلى أحرف صغيرة، لذلك يكون المسار req.headers.authorization وليس req.headers.Authorization.

• أسماء الترويسات التي تحتوي على شرطة تحتاج إلى صيغة الأقواس، مثل res.headers["set-cookie"].

• قيمة الإخفاء الافتراضية هي [Redacted]، أما redact: { paths, remove: true } فيحذف المفتاح بالكامل.

• يشير توثيق Pino إلى أن مسارات البدل (wildcard) أعلى كلفة من المسارات الصريحة، وأن مسارات الإخفاء يجب ألا تأتي أبدًا من مدخلات المستخدم، لذلك نكتب مسارات صريحة للأشكال التي نسجّلها.

• لا يسجّل pino-http أجسام الطلبات افتراضيًا، لذلك لا تتسرب حقول مثل password إلا عندما يسجّل كودنا كائن DTO كاملًا. نحن نسجّل حقولًا محددة بدلًا من ذلك.

الإخفاء يحمي فقط المسارات التي تذكّرها أحدهم، لذلك نختبره. حالة اختبار صغيرة في node:test تنشئ مسجّل Pino بقائمة REDACT_PATHS المشتركة وبتدفق Writable في الذاكرة كوجهة، وتسجّل طلبًا وهميًا قيمة ترويسة authorization فيه هي 'Bearer test-secret-123'، ثم تتحقق من أن المخرجات لا تحتوي أبدًا على test-secret-123 وأنها تحتوي على [Redacted].

لماذا يُسقط Pino تتبّع المكدس للخطأ؟

يُسقط Pino الخطأ عندما يُمرَّر بعد الرسالة، لأن الوسائط الإضافية منذ الإصدار 6 من Pino لا تُستخدم إلا لملء العناصر النائبة بأسلوب printf مثل %s. الاستدعاء logger.error('payment capture failed', err) يكتب الرسالة ويتجاهل err بصمت: لا نوع، ولا رسالة، ولا تتبّع مكدس.

الحل هو ترتيب الوسائط. الاستدعاء logger.error({ err, orderId }, 'payment capture failed') يمرر err عبر مُسلسِل الأخطاء الافتراضي في Pino، وهو pino.stdSerializers.err، الذي يُخرج نوع الخطأ ورسالته وتتبّع المكدس. ويعمل logger.error(err) وحده أيضًا: يغلّف Pino كائن Error الممرَّر كوسيط أول داخل { err } ويستخدم err.message كقيمة msg.

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

هل نستخدم pino-pretty أو ناقلًا (transport) في الإنتاج؟

لا. في الإنتاج نكتب JSON خامًا إلى stdout ونترك المنصة تجمعه: مشغّل السجلات في Docker، أو سجلات التشغيل في Vercel، أو مُجمِّع OpenTelemetry. أداة pino-pretty، التي تحوّل JSON الخاص بـ Pino إلى نص ملوّن، مخصصة للتطوير المحلي فقط، لأن منصات السجلات لا تستطيع تحليل مخرجاتها.

عندما يجب أن تذهب السجلات إلى وجهة أخرى، يشغّل pino.transport() الناقل في خيط عامل (worker thread) بعيدًا عن حلقة الأحداث الرئيسية. ومع ذلك نفضّل stdout مع مُجمِّع خارجي، لأن الناقل داخل عملية التطبيق شيء إضافي يجب تفريغه أثناء الإيقاف.

التحكم في المستوى هو الإعداد الآخر في الإنتاج. يستبدل Pino دوال المستويات المعطّلة بدالة فارغة (no-op)، لذلك لا يكلّف logger.debug() شيئًا يُذكر عند المستوى info، لكن وسائطه تُقيَّم مع ذلك. لحمولة debug مكلفة نحيط الاستدعاء بالشرط logger.isLevelEnabled('debug'). وضبط LOG_LEVEL=debug على نسخة واحدة أثناء حادث يمنحنا التفاصيل دون تعديل الكود.

الأسئلة الشائعة

س: هل console.log كافٍ لسجلات Node.js في الإنتاج؟

ج: للسكربتات والخدمات الصغيرة أحادية الغرض، غالبًا نعم، خاصة مع ConsoleLogger في NestJS 11 بوضع json: true. وعندما تحتاج الخدمة إلى ربط الأسطر بكل طلب أو إخفاء الأسرار، يصبح مسجّل منظّم مثل Pino مجديًا.

س: هل نسجّل أجسام الطلبات والاستجابات مع pino-http؟

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

س: كيف نربط سجلات Pino بتتبّعات OpenTelemetry؟

ج: نضيف trace_id وspan_id الخاصين بالـ span النشط إلى كل سطر، إما عبر @opentelemetry/instrumentation-pino أو بقراءة trace.getSpan(context.active()) داخل دالة mixin. ومع وجود معرّف الطلب ومعرّف التتبّع في كل سطر، نستطيع الانتقال من تتبّع بطيء إلى سجلاته مباشرة.

س: ما الترويسة التي يجب أن تحمل معرّف الطلب؟

ج: الترويسة x-request-id هي العرف الشائع، والعديد من الوكلاء العكسيين (proxies) وموازنات الأحمال تضبطها أو تمررها بالفعل. اقبل القيمة الواردة فقط بعد التحقق من طولها وأحرفها، وأنشئ UUID في غير ذلك.