أحداث التتبع

[مستقر: 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: تمكن التقاط بيانات التتبع التي تتبع عدد عمليات رفض Promise غير المعالجة والمعالجة بعد الرفض.

• 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('تم استلام SIGINT.');
  process.exit(130);  // أو رمز خروج قابل للتطبيق اعتمادًا على نظام التشغيل والإشارة
});

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

الميزات من هذه الوحدة غير متوفرة في سلاسل عمليات Worker.

وحدة node:trace_events

أُضيفت في: الإصدار 10.0.0

الكائن Tracing

أُضيفت في: الإصدار 10.0.0

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

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

tracing.categories

أُضيفت في: الإصدار 10.0.0

• <string>

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

tracing.disable()

أُضيفت في: الإصدار 10.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()

أُضيفت في: الإصدار 10.0.0

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

tracing.enabled

أُضيفت في: الإصدار 10.0.0

• <boolean> true فقط إذا تم تمكين الكائن Tracing.

trace_events.createTracing(options)

أُضيفت في: الإصدار 10.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();
// do stuff
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', () => {
    // تم
  });
  const traceConfig = { includedCategories: ['v8'] };
  await post('NodeTracing.start', { traceConfig });
  // افعل شيئًا
  setTimeout(() => {
    post('NodeTracing.stop').then(() => {
      session.disconnect();
      console.log(data);
    });
  }, 1000);
}

collect();