تتبع الأحداث (Trace Events) في Node.js

مؤشر الاستقرار: 1 - تجريبي

يوفر تتبع الأحداث آلية لتركيز معلومات التتبع التي  تولدت بواسطة V8، ونواه Node.js، وبرمجية مساحة المستخدم (userspace code).

يمكن تفعيل التتبع بواسطة راية سطر الأوامر ‎--trace-event-categories أو باستخدام وحدة trace_events. وتقبل راية ‎‎--‎trace-event-categories قائمة بأسماء الفئات المفصولة بفاصلات.

والفئات المتاحة هي:

    • node - عنصر نائب (placeholder) فارغ.

    • node.async_hooks - يتيح التقاط بيانات التتبع async_hooks المُفصَّلة. أحداث async_hooks لها asyncId فريد وخاصيتا triggerId و triggerAsyncId الخاصة.

    • node.bootstrap - يتيح التقاط معالم إقلاع Node.js.

    • node.fs.sync - يتيح التقاط بيانات التتبع لتوابع مُزامَنة نظام الملفات.

    • node.perf - يتيح التقاط قياسات واجهة تطبيقات الأداء (Performance API).

        ◦ node.perf.usertiming - يتيح التقاط قياسات وعلامات توقيت المستخدم لواجهة تطبيقات الأداء (Performance API User Timing) فقط.

        ◦ node.perf.timerify - يتيح التقاط قياسات Performance API timerify فقط.

    • node.promises.rejections - يتيح التقاط بيانات التتبع متتبعًا عدد مرات رفض Promise غير المعالجة و handled-after-rejections.

    • node.vm.script - يتيح التقاط بيانات التتبع لتوابع وحدة vm مثل runInNewContext()‎ و runInContext()‎ و runInThisContext()‎

    • v8 - أحداث V8 ذات صلة بـ GC، والترجمة (compiling)، والتنفيذ.

تكون الفئات node و node.async_hooks و v8 مفعلة بشكل افتراضي.

node --trace-event-categories v8,node,node.async_hooks server.js

تتطلب الإصدارات السابقة من Node.js استخدام الراية ‎--trace-events-enabled لتفعيل أحداث التتبع. وقد أزيل هذا الشرط. ومع ذلك، يمكن استخدام الراية ‎--traceevents-enabled وستُفعِّل فئات أحداث التتبع node و node.async_hooks و v8 بشكل افتراضي.

node --trace-events-enabled

// يكافئ

node --trace-event-categories v8,node,node.async_hooks

وبدلاً من ذلك، يمكن تفعيل أحداث التتبع باستخدام الوحدة trace_vents:

const trace_events = require('trace_events');
const tracing = trace_events.createTracing({ categories: ['node.perf'] });
tracing.enable();  // يتيح التقاط تتبع الحدث للفئة'node.perf'

// التشغيل

tracing.disable();  // إيقاف التقاط تتبع الحدث للفئة'node.perf'

سيؤدي تشغيل Node.js مع تفعيل التتبع إلى إنتاج ملفات السجل التي يمكن فتحها في علامة التبويب chrome://tracing من المتصفح Chrome. ويسمى ملف التسجيل افتراضياً node_trace. ${rotation}.log، حيث ‎${rotation}‎ هو معرّف تزايد تدوير السجل. ,يمكن تحديد نمط مسار الملف باستخدام --trace-event-file-pattern والذي يقبل سلسلة قالب تدعم ‎${rotation}‎ و ‎${pid}‎. فعلى سبيل المثال:

node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js

بدءا من إصدار Node.js 10.0.0، يستخدم نظام التتبع نفس مصدر الوقت المستخدم من قبل ‎process.hrtime()‎ ولكن يعبَّر عن الختم الزمني لوحدة trace-event بالميكروثانية، على عكس process.hrtime()‎ الذي يُعيده بالنانوثانية.

وحدة 'trace_vents'

أُضيفت مع الإصدار: v10.0.0.

الكائن 'Tracing'

أُضيف مع الإصدار: v10.0.0.

ويستخدم الكائن Tracing لتفعيل أو تعطيل التتبع لمجموعات من الفئات. ويستخدم التابع  trace_events.createTracing()‎ لإنشاء كائنات مماثلة.

ويكون الكائن Tracing معطلًا عند إنشاءه. يضيف استدعاء التابع tracing.enable()‎ الفئات إلى مجموعة من فئات أحداث التتبع المُفعَّلة. ويُزيل استدعاء التابع tracing.disable()‎ الفئات من مجموعة من فئات أحداث التتبع المُفعَّلة.

tracing.categories

أُضيف مع الإصدار: v10.0.0.

    • القيمة المُعادة: من النوع <string>.

قائمة مفصولة بفاصلات تحتوي على فئات أحداث التتبع التي يغطيها كائن Tracing هذا.

tracing.disable()‎

أُضيف مع الإصدار: v10.0.0.

يعطِّل كائن Tracing هذا.

ستتعطل فقط فئات أحداث التتبع غير المشمولة من قِبَل كائنات Tracing المُفعَّلة الأخرى وغير المحددة بواسطة الراية ‎--trace-event-categories.

const trace_events = require('trace_events');
const t1 = trace_events.createTracing({ categories: ['node', 'v8'] });
const t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] });
t1.enable();
t2.enable();

// طباعة 'node,node.perf,v8'
console.log(trace_events.getEnabledCategories());

t2.disable(); // فقط ستعطل إطلاق فئة 'node.perf'

// طباعة 'node,v8'
console.log(trace_events.getEnabledCategories());

tracing.enable()‎

أُضيف مع الإصدار: v10.0.0.

تفعيل كائن Tracing هذا لمجموعة الفئات التي يغطيها كائن  Tracing.

tracing.enabled

أُضيف مع الإصدار: v10.0.0.

    • من النوع <boolean> وتكون قيمتها true فقط إذا كان الكائن Tracing مُفعَّلًا.

trace_events.createTracing(options)‎

أُضيف مع الإصدار: v10.0.0.

    • options من النوع  <Object>.

        ◦ categories من النوع ‎<string[]>‎ وهي مصفوفة من أسماء فئات التتبع. تُحوَّل القيم المدرجة في المصفوفة إلى سلسلة جبرًا كلما كان ذلك ممكنًا. وسينطلق خطأ إذا كان لا يمكن فرض القيمة.

    • القيمة المُعادة: من النوع <Tracing>.

إنشاء وإعادة كائن Tracing للمجموعة المعطاة من الفئات categories.

trace_events.getEnabledCategories()‎

أُضيف مع الإصدار: v10.0.0.

    • القيمة المُعادة: من النوع <string>.

يُعيد قائمة مفصولة بفاصلات لكل فئات أحداث التتبع المُفعَّلة حالياً. وهو يحدد المجموعة الحالية من فئات أحداث التتبع المُفعَّلة بواسطة اتحاد من جميع كائنات Tracing المُفعَّلة حاليًا مع أي فئة  مُفعَّلة باستخدام الراية  ‎--trace-event-categories.

وبالنظر إلى الملف  test.js أدناه، سيطبع الأمر node --trace-event-categories node.perf test.js على الشاشة 'node.async_hooks,node.perf'.

const trace_events = require('trace_events');
const t1 = trace_events.createTracing({ categories: ['node.async_hooks'] });
const t2 = trace_events.createTracing({ categories: ['node.perf'] });
const t3 = trace_events.createTracing({ categories: ['v8'] });

t1.enable();
t2.enable();

console.log(trace_events.getEnabledCategories());

مصادر

صفحة تتبع الأحداث (Trace Events) في توثيق Node.js الرسمي.