المفتش (Inspector)

[مستقر: 2 - مستقر]

كود المصدر: lib/inspector.js

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

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

ESMCJS

import * as inspector from 'node:inspector/promises';

const inspector = require('node:inspector/promises');

أو

ESMCJS

import * as inspector from 'node:inspector';

const inspector = require('node:inspector');

واجهة برمجة تطبيقات الوعود (Promises API)

[مستقر: 1 - تجريبي]

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

تمت الإضافة في: v19.0.0

الصنف: `inspector.Session`

يمتد: <EventEmitter>

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

`new inspector.Session()`

تمت الإضافة في: v8.0.0

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

عند استخدام Session، لن يتم تحرير الكائن الناتج بواسطة واجهة برمجة تطبيقات وحدة التحكم (console API)، إلا إذا نفذنا يدويًا الأمر Runtime.DiscardConsoleEntries.

الحدث: `'inspectorNotification'`

تمت الإضافة في: v8.0.0

<Object> كائن رسالة الإشعار

يتم إطلاقه عند تلقي أي إشعار من مفتش V8.

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

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

الحدث: `<inspector-protocol-method>`; {#event-<inspector-protocol-method>;}

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

<Object> كائن رسالة الإشعار

يتم إصداره عند استلام إشعار من المُدقق يحتوي على حقل method مُعيّنًا إلى القيمة \<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

يربط جلسة بالواجهة الخلفية للمُدقق.

`session.connectToMainThread()`

أُضيف في: الإصدار v12.11.0

يربط جلسة بالواجهة الخلفية للمُدقق للخيط الرئيسي. سيتم طرح استثناء إذا لم يتم استدعاء واجهة برمجة التطبيقات هذه في خيط العامل.

`session.disconnect()`

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

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

`session.post(method[, params])`

أُضيف في: الإصدار v19.0.0

method <string>
params <Object>
الإرجاع: <Promise>

ينشر رسالة إلى الواجهة الخلفية للمُدقق.

import { Session } from 'node:inspector/promises';
try {
  const session = new Session();
  session.connect();
  const result = await session.post('Runtime.evaluate', { expression: '2 + 2' });
  console.log(result);
} catch (error) {
  console.error(error);
}
// Output: { result: { type: 'number', value: 4, description: '4' } }

يتم نشر أحدث إصدار من بروتوكول V8 للمُدقق على عارض بروتوكول Chrome DevTools.

يدعم مُدقق Node.js جميع نطاقات بروتوكول Chrome DevTools التي أعلنتها V8. يوفر نطاق بروتوكول Chrome DevTools واجهة للتفاعل مع أحد عوامل وقت التشغيل المستخدمة لفحص حالة التطبيق والاستماع إلى أحداث وقت التشغيل.

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

بصرف النظر عن مصحح الأخطاء، تتوفر العديد من أدوات V8 Profilers من خلال بروتوكول DevTools.

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

إليك مثال يوضح كيفية استخدام محلل وحدة المعالجة المركزية (CPU):

import { Session } from 'node:inspector/promises';
import fs from 'node:fs';
const session = new Session();
session.connect();

await session.post('Profiler.enable');
await session.post('Profiler.start');
// Invoke business logic under measurement here...

// some time later...
const { profile } = await session.post('Profiler.stop');

// Write profile to disk, upload, etc.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));

محلل الذاكرة المكدسة (Heap)

إليك مثال يوضح كيفية استخدام محلل الذاكرة المكدسة (Heap):

import { Session } from 'node:inspector/promises';
import fs from 'node:fs';
const session = new Session();

const fd = fs.openSync('profile.heapsnapshot', 'w');

session.connect();

session.on('HeapProfiler.addHeapSnapshotChunk', (m) => {
  fs.writeSync(fd, m.params.chunk);
});

const result = await session.post('HeapProfiler.takeHeapSnapshot', null);
console.log('HeapProfiler.takeHeapSnapshot done:', result);
session.disconnect();
fs.closeSync(fd);

واجهة برمجة تطبيقات الاستدعاء (Callback API)

صنف: `inspector.Session`

يمتد من: <EventEmitter>

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

`new inspector.Session()`

تمت الإضافة في: v8.0.0

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

عند استخدام Session، لن يتم تحرير الكائن الناتج عن واجهة برمجة تطبيقات وحدة التحكم (console API)، ما لم ننفذ أمر Runtime.DiscardConsoleEntries يدويًا.

الحدث: `'inspectorNotification'`

تمت إضافته في: الإصدار 8.0.0

<Object> كائن رسالة الإشعار

يُطلق هذا الحدث عند تلقي أي إشعار من V8 Inspector.

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

من الممكن أيضًا الاشتراك فقط في الإشعارات التي لها طريقة محددة:

الحدث: `<inspector-protocol-method>`؛ {#event-<inspector-protocol-method>;_1}

تمت إضافته في: الإصدار 8.0.0

<Object> كائن رسالة الإشعار

يُطلق هذا الحدث عند تلقي إشعار Inspector تم تعيين حقله method إلى قيمة \<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()`

تمت إضافته في: الإصدار 8.0.0

يقوم بتوصيل جلسة عمل بالواجهة الخلفية لـ Inspector.

`session.connectToMainThread()`

تمت إضافته في: الإصدار 12.11.0

يقوم بتوصيل جلسة عمل بالواجهة الخلفية لـ Inspector في مؤشر الترابط الرئيسي. سيتم طرح استثناء إذا لم يتم استدعاء واجهة برمجة التطبيقات هذه في مؤشر ترابط Worker.

`session.disconnect()`

تمت إضافته في: الإصدار 8.0.0

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

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

[سجل التغييرات]

الإصدار	التغييرات
الإصدار 18.0.0	تمرير استدعاء غير صالح إلى وسيطة `callback` يطرح الآن `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
الإصدار 8.0.0	تمت إضافته في: الإصدار 8.0.0

method <string>
params <Object>
callback <Function>

ينشر رسالة إلى الواجهة الخلفية لـ Inspector. سيتم إعلام callback عند تلقي رد. callback هي دالة تقبل وسيطتين اختياريتين: خطأ ونتيجة خاصة بالرسالة.

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

يتم نشر أحدث إصدار من بروتوكول V8 Inspector على عارض بروتوكول Chrome DevTools.

يدعم Node.js Inspector جميع مجالات بروتوكول Chrome DevTools التي أعلنتها V8. يوفر مجال بروتوكول Chrome DevTools واجهة للتفاعل مع أحد وكلاء وقت التشغيل المستخدمين لفحص حالة التطبيق والاستماع إلى أحداث وقت التشغيل.

لا يمكنك تعيين reportProgress إلى true عند إرسال أمر HeapProfiler.takeHeapSnapshot أو HeapProfiler.stopTrackingHeapObjects إلى V8.

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

بالإضافة إلى مصحح الأخطاء، تتوفر العديد من مُحلِّلات V8 Profilers من خلال بروتوكول DevTools.

محلل CPU

فيما يلي مثال يوضح كيفية استخدام محلل CPU:

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

session.post('Profiler.enable', () => {
  session.post('Profiler.start', () => {
    // Invoke business logic under measurement here...

    // some time later...
    session.post('Profiler.stop', (err, { profile }) => {
      // Write profile to disk, upload, etc.
      if (!err) {
        fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));
      }
    });
  });
});

محلل الذاكرة المؤقتة (Heap)

فيما يلي مثال يوضح كيفية استخدام محلل الذاكرة المؤقتة:

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

const fd = fs.openSync('profile.heapsnapshot', 'w');

session.connect();

session.on('HeapProfiler.addHeapSnapshotChunk', (m) => {
  fs.writeSync(fd, m.params.chunk);
});

session.post('HeapProfiler.takeHeapSnapshot', null, (err, r) => {
  console.log('HeapProfiler.takeHeapSnapshot done:', err, r);
  session.disconnect();
  fs.closeSync(fd);
});

الكائنات الشائعة

`inspector.close()`

[السجل]

الإصدار	التغييرات
v18.10.0	يتم عرض واجهة برمجة التطبيقات في سلاسل العمل (worker threads).
v9.0.0	تمت الإضافة في: v9.0.0

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

`inspector.console`

<Object> كائن لإرسال الرسائل إلى وحدة تحكم الفاحص البعيدة.

require('node:inspector').console.log('a message');

لا تتمتع وحدة تحكم الفاحص بتكافؤ واجهة برمجة التطبيقات (API) مع وحدة تحكم Node.js.

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

[التاريخ]

الإصدار	التغييرات
v20.6.0	تُرجع الآن `inspector.open()` كائن `Disposable`.

port <number> المنفذ للاستماع لاتصالات المدقق. اختياري. افتراضي: ما تم تحديده في CLI.
host <string> المضيف للاستماع لاتصالات المدقق. اختياري. افتراضي: ما تم تحديده في CLI.
wait <boolean> حظر حتى يتم توصيل عميل. اختياري. افتراضي: false.
يُرجع: <Disposable> كائن Disposable يستدعي inspector.close().

تفعيل المدقق على المضيف والمنفذ. مكافئ لـ node --inspect=[[host:]port], ولكن يمكن القيام بذلك برمجيًا بعد بدء تشغيل node.

إذا كانت قيمة wait هي true, فسيتم الحظر حتى يتم توصيل عميل بمنفذ الفحص ويتم تمرير التحكم في التدفق إلى عميل التصحيح.

راجع تحذير الأمان بشأن استخدام معلمة host.

`inspector.url()`

يُرجع: <string> | <undefined>

إرجاع عنوان URL للمدقق النشط، أو undefined إذا لم يكن هناك أي مدقق نشط.

bash

$ node --inspect -p 'inspector.url()'
Debugger listening on ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34
For help, see: https://nodejs.org/en/docs/inspector
ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34

$ node --inspect=localhost:3000 -p 'inspector.url()'
Debugger listening on ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a
For help, see: https://nodejs.org/en/docs/inspector
ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a

$ node -p 'inspector.url()'
undefined

`inspector.waitForDebugger()`

إضافة في: v12.7.0

يحظر حتى يرسل عميل (موجود أو متصل لاحقًا) أمر Runtime.runIfWaitingForDebugger.

سيتم طرح استثناء إذا لم يكن هناك مدقق نشط.

التكامل مع أدوات المطورين

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

// سيتم إطلاق حدث `Network.requestWillBeSent`.
inspector.Network.requestWillBeSent({
  requestId: 'request-id-1',
  timestamp: Date.now() / 1000,
  wallTime: Date.now(),
  request: {
    url: 'https://nodejs.org/en',
    method: 'GET',
  },
});

`inspector.Network.requestWillBeSent([params])`

إضافة في: v22.6.0, v20.18.0

[مستقر: 1 - تجريبي]

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

params <Object>

هذه الميزة متاحة فقط مع تمكين العلامة --experimental-network-inspection.

يبث حدث Network.requestWillBeSent إلى الواجهات الأمامية المتصلة. يشير هذا الحدث إلى أن التطبيق على وشك إرسال طلب HTTP.

`inspector.Network.responseReceived([params])`

إضافة في: v22.6.0, v20.18.0

[مستقر: 1 - تجريبي]

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

params <Object>

هذه الميزة متاحة فقط مع تمكين العلامة --experimental-network-inspection.

يبث حدث Network.responseReceived إلى الواجهات الأمامية المتصلة. يشير هذا الحدث إلى أن استجابة HTTP متاحة.

`inspector.Network.loadingFinished([params])`

أضيف في: v22.6.0, v20.18.0

[مستقر: 1 - تجريبي]

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

params <Object>

هذه الميزة متاحة فقط مع تمكين علامة --experimental-network-inspection.

يبث حدث Network.loadingFinished إلى الواجهات الأمامية المتصلة. يشير هذا الحدث إلى أن تحميل طلب HTTP قد انتهى.

`inspector.Network.loadingFailed([params])`

أضيف في: v22.7.0, v20.18.0

[مستقر: 1 - تجريبي]

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

params <Object>

هذه الميزة متاحة فقط مع تمكين علامة --experimental-network-inspection.

يبث حدث Network.loadingFailed إلى الواجهات الأمامية المتصلة. يشير هذا الحدث إلى أن تحميل طلب HTTP قد فشل.

دعم نقاط التوقف

يسمح نطاق Debugger في بروتوكول Chrome DevTools لـ inspector.Session بالاتصال ببرنامج وتعيين نقاط توقف للتنقل عبر التعليمات البرمجية.

ومع ذلك، يجب تجنب تعيين نقاط التوقف باستخدام inspector.Session في نفس سلسلة الرسائل، والتي يتم توصيلها بواسطة session.connect()، حيث أن البرنامج الذي يتم إرفاقه وإيقافه مؤقتًا هو المصحح نفسه تمامًا. بدلاً من ذلك، حاول الاتصال بالسلسلة الرئيسية بواسطة session.connectToMainThread() وتعيين نقاط التوقف في سلسلة عامل، أو الاتصال ببرنامج Debugger عبر اتصال WebSocket.

المفتش (Inspector) ​

واجهة برمجة تطبيقات الوعود (Promises API) ​

الصنف: inspector.Session ​

new inspector.Session() ​

الحدث: 'inspectorNotification' ​

الحدث: &lt;inspector-protocol-method&gt;; {#event-<inspector-protocol-method>;} ​

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

session.post(method[, params]) ​

مثال للاستخدام ​

محلل وحدة المعالجة المركزية (CPU) ​

محلل الذاكرة المكدسة (Heap) ​

واجهة برمجة تطبيقات الاستدعاء (Callback API) ​

صنف: inspector.Session ​

new inspector.Session() ​

الحدث: 'inspectorNotification' ​

الحدث: &lt;inspector-protocol-method&gt;؛ {#event-<inspector-protocol-method>;_1} ​

session.connect() ​

session.connectToMainThread() ​

session.disconnect() ​

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

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

محلل CPU ​

محلل الذاكرة المؤقتة (Heap) ​

الكائنات الشائعة ​

inspector.close() ​

inspector.console ​

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

inspector.url() ​

inspector.waitForDebugger() ​

التكامل مع أدوات المطورين ​

inspector.Network.requestWillBeSent([params]) ​

inspector.Network.responseReceived([params]) ​

inspector.Network.loadingFinished([params]) ​

inspector.Network.loadingFailed([params]) ​

دعم نقاط التوقف ​

المفتش (Inspector)

واجهة برمجة تطبيقات الوعود (Promises API)

الصنف: `inspector.Session`

`new inspector.Session()`

الحدث: `'inspectorNotification'`

الحدث: `<inspector-protocol-method>`; {#event-<inspector-protocol-method>;}

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

`session.post(method[, params])`

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

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

محلل الذاكرة المكدسة (Heap)

واجهة برمجة تطبيقات الاستدعاء (Callback API)

صنف: `inspector.Session`

`new inspector.Session()`

الحدث: `'inspectorNotification'`

الحدث: `<inspector-protocol-method>`؛ {#event-<inspector-protocol-method>;_1}

`session.connect()`

`session.connectToMainThread()`

`session.disconnect()`

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

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

محلل CPU

محلل الذاكرة المؤقتة (Heap)

الكائنات الشائعة

`inspector.close()`

`inspector.console`

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

`inspector.url()`

`inspector.waitForDebugger()`

التكامل مع أدوات المطورين

`inspector.Network.requestWillBeSent([params])`

`inspector.Network.responseReceived([params])`

`inspector.Network.loadingFinished([params])`

`inspector.Network.loadingFailed([params])`

دعم نقاط التوقف