أحداث التتبع

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

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

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

يوفر مُعامل node:trace_events آلية لمركزية معلومات التتبع التي تم إنشاؤها بواسطة V8، ونواة Node.js، ورمز مساحة المستخدم.

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

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

• node: عنصر نائب فارغ.

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

• node.bootstrap: يُمكّن التقاط معالم تمهيد Node.js.

• node.console: يُمكّن التقاط مُخرجات console.time() و console.count().

• node.threadpoolwork.sync: يُمكّن التقاط بيانات التتبع للعمليات المتزامنة لمجموعة مؤشر الترابط، مثل blob و zlib و crypto و node_api.

• node.threadpoolwork.async: يُمكّن التقاط بيانات التتبع للعمليات غير المتزامنة لمجموعة مؤشر الترابط، مثل blob و zlib و crypto و node_api.

• node.dns.native: يُمكّن التقاط بيانات التتبع لاستعلامات DNS.

• node.net.native: يُمكّن التقاط بيانات التتبع للشبكة.

• node.environment: يُمكّن التقاط معالم بيئة Node.js.

• node.fs.sync: يُمكّن التقاط بيانات التتبع لطرق النظام الملفات المتزامنة.

• node.fs_dir.sync: يُمكّن التقاط بيانات التتبع لطرق دليل النظام الملفات المتزامنة.

• node.fs.async: يُمكّن التقاط بيانات التتبع لطرق النظام الملفات غير المتزامنة.

• node.fs_dir.async: يُمكّن التقاط بيانات التتبع لطرق دليل النظام الملفات غير المتزامنة.

• node.perf: يُمكّن التقاط قياسات واجهة برمجة التطبيقات للأداء.

  • node.perf.usertiming: يُمكّن التقاط قياسات وعلامات توقيت المستخدم لواجهة برمجة التطبيقات للأداء فقط.
  • node.perf.timerify: يُمكّن التقاط قياسات timerify لواجهة برمجة التطبيقات للأداء فقط.

• node.promises.rejections: يُمكّن التقاط بيانات التتبع التي تتبع عدد رفض الوعود غير المُعالجة والرفض المُعالجة لاحقًا.

• node.vm.script: يُمكّن التقاط بيانات التتبع لطرق runInNewContext() و runInContext() و runInThisContext() لوحدة node:vm.

• v8: أحداث V8 مرتبطة بـ GC، والترجمة، والتنفيذ.

• node.http: يُمكّن التقاط بيانات التتبع لطلب/استجابة http.

• node.module_timer: يُمكّن التقاط بيانات التتبع لتحميل وحدة CJS.

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

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

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

node --trace-events-enabled

# ما يعادل {#is-equivalent-to}

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

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

const trace_events = require('node: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

لضمان إنشاء ملف السجل بشكل صحيح بعد أحداث الإشارة مثل SIGINT أو SIGTERM أو SIGBREAK، تأكد من وجود المُعالجات المناسبة في التعليمات البرمجية الخاصة بك، مثل:

process.on('SIGINT', function onSigint() {
  console.info('Received SIGINT.')
  process.exit(130) // أو رمز الخروج المناسب حسب نظام التشغيل والإشارة
})

يستخدم نظام التتبع نفس مصدر الوقت الذي يستخدمه process.hrtime(). ومع ذلك، يتم التعبير عن طوابع زمن حدث التتبع بوحدات الميكروثانية، على عكس process.hrtime() الذي يُرجع النانو ثانية.

لا تتوفر ميزات هذه الوحدة في مؤشرات الترابط Worker.

الوحدة النمطية node:trace_events

أضيف في: 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('node: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.

const trace_events = require('node:trace_events')
const categories = ['node.perf', 'node.async_hooks']
const tracing = trace_events.createTracing({ categories })
tracing.enable()
// قم بأداء بعض الأشياء
tracing.disable()

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('node: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())

أمثلة

جمع بيانات أحداث التتبع بواسطة مُفتّش الأخطاء

'use strict'

const { Session } = require('node:inspector')
const session = new Session()
session.connect()

function post(message, data) {
  return new Promise((resolve, reject) => {
    session.post(message, data, (err, result) => {
      if (err) reject(new Error(JSON.stringify(err)))
      else resolve(result)
    })
  })
}

async function collect() {
  const data = []
  session.on('NodeTracing.dataCollected', chunk => data.push(chunk))
  session.on('NodeTracing.tracingComplete', () => {
    // done
  })
  const traceConfig = { includedCategories: ['v8'] }
  await post('NodeTracing.start', { traceConfig })
  // do something
  setTimeout(() => {
    post('NodeTracing.stop').then(() => {
      session.disconnect()
      console.log(data)
    })
  }, 1000)
}

collect()