مُفتّش (Inspector)

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

مستقر: 2 استقرار: 2 - مستقر

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

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

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

ESM

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

CJS

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

أو

ESM

import * as inspector from 'node:inspector'

CJS

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، لن يتم إصدار مُخرجات الكائن بواسطة واجهة برمجة تطبيقات وحدة التحكم، ما لم نقم يدويًا بتنفيذ أمر 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> كائن رسالة الإشعار

يتم إصداره عند استلام إشعار مفتش تم تعيين حقل الطريقة الخاص به على قيمة \<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)
}
// الإخراج: { result: { type: 'number', value: 4, description: '4' } }

تم نشر أحدث إصدار من بروتوكول مفتش V8 على Chrome DevTools Protocol Viewer.

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

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

بخلاف مُصحح الأخطاء، تتوفر مُحسّنات V8 مُتعددة من خلال بروتوكول DevTools.

مُحسّن وحدة المعالجة المركزية

فيما يلي مثال يُظهر كيفية استخدام مُحسّن وحدة المعالجة المركزية:

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')
// استدعاء منطق العمل تحت القياس هنا...

// بعد مرور بعض الوقت...
const { profile } = await session.post('Profiler.stop')

// كتابة الملف الشخصي على القرص، أو تحميله، إلخ.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile))

مُحسّن الكومة

فيما يلي مثال يُظهر كيفية استخدام مُحسّن الكومة:

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)

واجهة برمجة التطبيقات القائمة على المُنعطفات العودية

الصنف: inspector.Session

• يمتد: <EventEmitter>

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

new inspector.Session()

مُضاف في: v8.0.0

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

عند استخدام Session، لن يتم إصدار المُخرجات التي أنتجها واجهة برمجة التطبيقات لوحدة التحكم، ما لم نقم يدويًا بتنفيذ الأمر 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>;_1}

مضاف في: 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

يُوصِل جلسةً إلى الخلفية المُفتّشة.

session.connectToMainThread()

مضاف في: v12.11.0

يُوصِل جلسةً إلى الخلفية المُفتّشة لخيط التشغيل الرئيسي. سيتم طرح استثناء إذا لم يتم استدعاء هذا API على خيط عامل.

session.disconnect()

مضاف في: v8.0.0

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

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

[السجل]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُستدعي غير صالح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v8.0.0	مضاف في: v8.0.0

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

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

session.post('Runtime.evaluate', { expression: '2 + 2' }, (error, { result }) => console.log(result))
// الإخراج: { type: 'number', value: 4, description: '4' }

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

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

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

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

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

مُحسّن وحدة المعالجة المركزية

فيما يلي مثال يُوضح كيفية استخدام مُحسّن وحدة المعالجة المركزية:

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', () => {
    // قم باستدعاء منطق العمل قيد القياس هنا...

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

مُحسّن الكومة

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

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	تمّ الكشف عن واجهة برمجة التطبيقات في خيوط العامل.
v9.0.0	تمت الإضافة في: v9.0.0

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

inspector.console

• <Object> كائن لإرسال الرسائل إلى وحدة التحكم البعيدة لمُفتّش الأخطاء.

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

لا تتمتع وحدة تحكم مُفتّش الأخطاء بنفس مُساواة واجهة برمجة التطبيقات مع وحدة تحكم Node.js.

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

[السجل]

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

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

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

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

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

inspector.url()

• المُرجَع: <string> | <undefined>

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

$ 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 DevTools. يمكن لأدوات واجهة المستخدم الأمامية المتصلة بمثيل 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 فشل في التحميل.

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

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

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