Node.js/inspector

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

توفر وحدة المراقب inspector واجهة تطبيقات API للتفاعل مع المراقب V8.

ويمكن الوصول إليه باستخدام:

const inspector = require('inspector');

inspector.open([port[, host[, wait]]])‎

• port من النوع <number>: منفذ الاستماع لاتصالات المراقب. اختياري. القيمة الافتراضية: ما تحدد في واجهة سطر الأوامر CLI.
• host من النوع <string>: المضيف الذي يجب الاستماع له لإجراء اتصالات المراقب. اختياري. القيمة الافتراضية: ما تحدد في واجهة سطر الأوامر CLI.
• wait من النوع <boolean>: المنع حتى إتمام اتصال عميل. اختياري. القيمة الافتراضية: false.

تنشيط المراقب على المضيف والمنفذ. يكافئ node --inspect=[[host:]port]‎، ولكن يمكن أداءه برمجيًا بعد بدء العقدة.

إذا كانت قيمة wait تساوي true، سيتوقف حتى يتصل عميل بمنفذ المراقبة وتمرير التحكم في التدفق (flow control) إلى عميل المُنقِّح (debugger client).

inspector.close()‎

إيقاف المراقب. يتوقف حتى لا توجد أيّة اتصالات نشطة.

inspector.url()‎

• القيمة المُعادة: ‎<string> | <undefined>‎.

إعادة url الخاص بالمراقب النشطة، أو undefined خلاف ذلك.

الصنف inspector.Session

يستخدم inspector.Session لإرسال رسائل إلى نهاية المراقب V8 الخلفية وتلقى استجابات الرسائل وإخطاراتها.

المُنشئ inspector.Session()‎ الجديد

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

إنشاء مثيل جديد من الصنف inspector.Session تحتاج جلسة المراقب أن تكون متصلة من خلال session.connect()‎ قبل إرسال الرسائل إلى نهاية المراقب الخلفية.

inspector.Session هو EventEmitter مع الأحداث التالية:

الحدث 'inspectorNotification'

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

• <Object> كائن رسالة الإخطار.

يُطلق عند تلقي أي إخطار من المراقب V8.

session.on('inspectorNotification', (message) => console.log(message.method));
// Debugger.paused
// Debugger.resumed

فمن الممكن أيضا الاشتراك فقط في الإخطارات ذوات تابع محدد:

الحدث <inspector-protocol-method>

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

• <Object> كائن رسالة الإخطار.

يُطلق عند تلقي إشعار من المراقب بضبط مجال التابع بقيمة <inspector-protocol-method>.

يثبت المقتطف التالي مستمع لحدث 'Debugger.paused'، ويطبع سبب تعليق البرنامج كلما تعلَّق تنفيذه (عبر نقاط التوقف، على سبيل المثال):

session.on('Debugger.paused', ({ params }) => {
  console.log(params.hitBreakpoints);
});
// [ '/the/file/that/has/the/breakpoint.js:11:0' ]

session.connect()‎

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

توصيل جلسة عمل بنهاية المُراقب الخلفية. سيُطرَح استثناء إذا كان هناك بالفعل جلسة عمل متصلة مُنشأة إما عبر واجهة تطبيقات API أو عبر الواجهة الأمامية الموصولة إلى منفذ "Inspector WebSocket".

session.post(method[, params][, callback])‎

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

• method من النوع <string>.
• params من النوع <Object>.
• callback من النوع <Function>.

إرسال رسالة إلى نهاية المراقب الخلفية. ستُخطَر دالة رد الاتصال callback عند تلقي استجابة. دالة رد اتصال callback هي دالة تقبل وسيطين اختياريَين؛ الخطأ والنتيجة الخاصة بالرسالة.

session.post('Runtime.evaluate', { expression: '2 + 2' },
             (error, { result }) => console.log(result));
// Output: { type: 'number', value: 4, description: '4' }

نُشِر أحدث إصدار من بروتوكول المراقب V8 في عارض بروتوكول أدوات مُطوري كروم (Chrome DevTools Protocol Viewer).

ويدعم مراقب العُقَد كافة مجالات بروتوكول أدوات مُطوري كروم المُعلنة في V8. يوفر مجال بروتوكول أدوات مُطوري كروم واجهةً للتفاعل مع أحد وكلاء وقت التشغيل المستخدمة لمراقبة حالة التطبيق والاستماع إلى أحداث وقت التشغيل.

session.disconnect()‎

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

إنهاء جلسة العمل على الفور. ستُستدعى جميع دوال رد الاتصال للرسائل المُعلقة مع وجود خطأ. ويجب استدعاء session.connect()‎ مجددًا ليتمكن من إرسال الرسائل مرة أخرى. سوف تفقد جلسة العمل المُعاد توصيلها جميع حالات المراقب، مثل الوكلاء المُفعَّلين أو نقاط التوقف المُكونَة.

مثال على الاستخدام

مُحلِّل وحدة المعالجة المركزية (CPU Profiler)

خلافاً عن المُنقِّح، تُتاح مُحللِّات V8 من خلال بروتوكول DevTools. هنا مثال بسيط يوضح كيف يتم استخدام مُحلِّل وحدة المعالجة المركزية (CPU Profiler):

const inspector = require('inspector');
const fs = require('fs');
const session = new inspector.Session();
session.connect();

session.post('Profiler.enable', () => {
  session.post('Profiler.start', () => {
    // استدعاء منطق سير الأعمال تحت القياس هنا ...
    // في وقت لاحق ...
    session.post('Profiler.stop', (err, { profile }) => {
      // كتابة الملف الشخصي على القرص ، والتحميل ، الخ
      if (!err) {
        fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));
      }
    });
  });
});

مصادر

• صفحة المراقب (Inspector‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎) في توثيق Node.js الرسمي.