قناة التشخيص

[التاريخ]

الإصدار	التغييرات
v19.2.0, v18.13.0	قناة التشخيص أصبحت الآن مستقرة.
v15.1.0, v14.17.0	تمت الإضافة في: v15.1.0, v14.17.0

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

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

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

توفر الوحدة node:diagnostics_channel واجهة برمجة تطبيقات لإنشاء قنوات مسماة للإبلاغ عن بيانات الرسائل العشوائية لأغراض التشخيص.

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

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

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

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

إذا كنت تنوي أن تنتج وحدتك النمطية بيانات تشخيصية ليستهلكها الآخرون، فمن المستحسن تضمين وثائق للقنوات المسماة المستخدمة جنبًا إلى جنب مع شكل بيانات الرسائل. يجب أن تتضمن أسماء القنوات بشكل عام اسم الوحدة النمطية لتجنب الاصطدامات مع البيانات من الوحدات النمطية الأخرى.

واجهة برمجة التطبيقات العامة

نظرة عامة

فيما يلي نظرة عامة بسيطة على واجهة برمجة التطبيقات العامة.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

// احصل على كائن قناة قابل لإعادة الاستخدام
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // البيانات المستلمة
}

// اشترك في القناة
diagnostics_channel.subscribe('my-channel', onMessage);

// تحقق مما إذا كانت القناة لديها مشترك نشط
if (channel.hasSubscribers) {
  // انشر البيانات في القناة
  channel.publish({
    some: 'data',
  });
}

// إلغاء الاشتراك من القناة
diagnostics_channel.unsubscribe('my-channel', onMessage);

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

// احصل على كائن قناة قابل لإعادة الاستخدام
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // البيانات المستلمة
}

// اشترك في القناة
diagnostics_channel.subscribe('my-channel', onMessage);

// تحقق مما إذا كانت القناة لديها مشترك نشط
if (channel.hasSubscribers) {
  // انشر البيانات في القناة
  channel.publish({
    some: 'data',
  });
}

// إلغاء الاشتراك من القناة
diagnostics_channel.unsubscribe('my-channel', onMessage);

`diagnostics_channel.hasSubscribers(name)`

أُضيف في: v15.1.0، v14.17.0

name <string> | <symbol> اسم القناة
إرجاع: <boolean> إذا كان هناك مشتركون نشطون

تحقق مما إذا كان هناك مشتركون نشطون في القناة المسماة. هذا مفيد إذا كانت الرسالة التي تريد إرسالها قد تكون مكلفة الإعداد.

تعتبر واجهة برمجة التطبيقات هذه اختيارية ولكنها مفيدة عند محاولة نشر الرسائل من التعليمات البرمجية الحساسة للأداء للغاية.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // يوجد مشتركون، قم بإعداد الرسالة ونشرها
}

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

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // يوجد مشتركون، قم بإعداد الرسالة ونشرها
}

`diagnostics_channel.channel(name)`

أُضيف في: v15.1.0، v14.17.0

name <string> | <symbol> اسم القناة
إرجاع: <Channel> كائن القناة المسمى

هذه هي نقطة الدخول الأساسية لأي شخص يريد النشر في قناة مسماة. ينتج كائن قناة تم تحسينه لتقليل الحمل الزائد في وقت النشر قدر الإمكان.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

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

const channel = diagnostics_channel.channel('my-channel');

`diagnostics_channel.subscribe(name, onMessage)`

أُضيف في: v18.7.0، v16.17.0

name <string> | <symbol> اسم القناة
onMessage <Function> معالج لاستقبال رسائل القناة
- message <any> بيانات الرسالة
- name <string> | <symbol> اسم القناة

سجل معالج الرسائل للاشتراك في هذه القناة. سيتم تشغيل معالج الرسائل هذا بشكل متزامن كلما تم نشر رسالة في القناة. أي أخطاء يتم طرحها في معالج الرسائل ستؤدي إلى تشغيل 'uncaughtException'.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // تم استلام البيانات
});

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

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // تم استلام البيانات
});

`diagnostics_channel.unsubscribe(name, onMessage)`

تمت الإضافة في: الإصدار v18.7.0، الإصدار v16.17.0

name <string> | <symbol> اسم القناة
onMessage <Function> معالج الرسائل المشترك السابق المراد إزالته
إرجاع: <boolean> true إذا تم العثور على المعالج، false بخلاف ذلك.

قم بإزالة معالج الرسائل الذي تم تسجيله مسبقًا في هذه القناة باستخدام diagnostics_channel.subscribe(name, onMessage).

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

function onMessage(message, name) {
  // Received data
}

diagnostics_channel.subscribe('my-channel', onMessage);

diagnostics_channel.unsubscribe('my-channel', onMessage);

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

function onMessage(message, name) {
  // Received data
}

diagnostics_channel.subscribe('my-channel', onMessage);

diagnostics_channel.unsubscribe('my-channel', onMessage);

`diagnostics_channel.tracingChannel(nameOrChannels)`

تمت الإضافة في: الإصدار v19.9.0، الإصدار v18.19.0

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

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

nameOrChannels <string> | <TracingChannel> اسم القناة أو الكائن الذي يحتوي على جميع قنوات TracingChannel
إرجاع: <TracingChannel> مجموعة من القنوات التي سيتم تتبعها بها

ينشئ غلاف TracingChannel لـ قنوات TracingChannel المعينة. إذا تم إعطاء اسم، فسيتم إنشاء قنوات التتبع المقابلة في شكل tracing:${name}:${eventType} حيث يتوافق eventType مع أنواع قنوات TracingChannel.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channelsByName = diagnostics_channel.tracingChannel('my-channel');

// or...

const channelsByCollection = diagnostics_channel.tracingChannel({
  start: diagnostics_channel.channel('tracing:my-channel:start'),
  end: diagnostics_channel.channel('tracing:my-channel:end'),
  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),
  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),
  error: diagnostics_channel.channel('tracing:my-channel:error'),
});

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

const channelsByName = diagnostics_channel.tracingChannel('my-channel');

// or...

const channelsByCollection = diagnostics_channel.tracingChannel({
  start: diagnostics_channel.channel('tracing:my-channel:start'),
  end: diagnostics_channel.channel('tracing:my-channel:end'),
  asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),
  asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),
  error: diagnostics_channel.channel('tracing:my-channel:error'),
});

الصنف: `Channel`

أُضيف في: الإصدار 15.1.0، الإصدار 14.17.0

يمثل الصنف Channel قناة مُسماة فردية داخل خط أنابيب البيانات. يُستخدم لتتبع المشتركين ونشر الرسائل عند وجود مشتركين. يوجد ككائن منفصل لتجنب عمليات البحث عن القنوات في وقت النشر، مما يتيح سرعات نشر عالية جدًا ويسمح بالاستخدام المكثف مع تحمل الحد الأدنى من التكلفة. يتم إنشاء القنوات باستخدام diagnostics_channel.channel(name)، إنشاء قناة مباشرة باستخدام new Channel(name) غير مدعوم.

`channel.hasSubscribers`

أُضيف في: الإصدار 15.1.0، الإصدار 14.17.0

الإرجاع: <boolean> إذا كان هناك مشتركون نشطون

تحقق مما إذا كان هناك مشتركون نشطون في هذه القناة. هذا مفيد إذا كانت الرسالة التي تريد إرسالها قد تكون مكلفة للإعداد.

تعتبر واجهة برمجة التطبيقات هذه اختيارية ولكنها مفيدة عند محاولة نشر الرسائل من التعليمات البرمجية الحساسة جدًا للأداء.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

if (channel.hasSubscribers) {
  // يوجد مشتركون، قم بإعداد ونشر الرسالة
}

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

const channel = diagnostics_channel.channel('my-channel');

if (channel.hasSubscribers) {
  // يوجد مشتركون، قم بإعداد ونشر الرسالة
}

`channel.publish(message)`

أُضيف في: الإصدار 15.1.0، الإصدار 14.17.0

message <any> الرسالة المراد إرسالها إلى مشتركي القناة

انشر رسالة إلى أي مشتركين في القناة. سيؤدي هذا إلى تشغيل معالجات الرسائل بشكل متزامن بحيث يتم تنفيذها في نفس السياق.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

channel.publish({
  some: 'message',
});

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

const channel = diagnostics_channel.channel('my-channel');

channel.publish({
  some: 'message',
});

`channel.subscribe(onMessage)`

أضيف في: v15.1.0, v14.17.0

تم إهماله منذ: v18.7.0, v16.17.0

[مستقر: 0 - مهمل]

مستقر: 0 الاستقرار: 0 - مهمل: استخدم diagnostics_channel.subscribe(name, onMessage)

onMessage <الدالة> معالج لاستقبال رسائل القناة
- message <>أية بيانات الرسالة
- name <سلسلة> | <رمز> اسم القناة

لتسجيل معالج رسائل للاشتراك في هذه القناة. سيتم تشغيل معالج الرسائل هذا بشكل متزامن كلما تم نشر رسالة على القناة. أي أخطاء يتم طرحها في معالج الرسائل ستؤدي إلى إطلاق 'uncaughtException'.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

channel.subscribe((message, name) => {
  // بيانات مستلمة
});

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

const channel = diagnostics_channel.channel('my-channel');

channel.subscribe((message, name) => {
  // بيانات مستلمة
});

`channel.unsubscribe(onMessage)`

[السجل]

الإصدار	التغييرات
v18.7.0, v16.17.0	مهمل منذ: v18.7.0, v16.17.0
v17.1.0, v16.14.0, v14.19.0	تمت إضافة قيمة الإرجاع. تمت إضافته إلى القنوات بدون مشتركين.
v15.1.0, v14.17.0	أضيف في: v15.1.0, v14.17.0

[مستقر: 0 - مهمل]

مستقر: 0 الاستقرار: 0 - مهمل: استخدم diagnostics_channel.unsubscribe(name, onMessage)

onMessage <الدالة> المعالج المشترك السابق المراد إزالته
إرجاع: <منطقي> true إذا تم العثور على المعالج، false خلاف ذلك.

قم بإزالة معالج الرسائل الذي تم تسجيله مسبقًا في هذه القناة باستخدام channel.subscribe(onMessage).

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // بيانات مستلمة
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);

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

const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // بيانات مستلمة
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);

`channel.bindStore(store[, transform])`

تمت الإضافة في: الإصدار v19.9.0، الإصدار v18.19.0

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

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

store <AsyncLocalStorage> المخزن الذي سيتم ربط بيانات السياق به
transform <الدالة> تحويل بيانات السياق قبل تعيين سياق المخزن

عند استدعاء channel.runStores(context, ...)، سيتم تطبيق بيانات السياق المحددة على أي مخزن مرتبط بالقناة. إذا كان المخزن قد تم ربطه بالفعل، فسيتم استبدال دالة transform السابقة بالدالة الجديدة. يمكن حذف دالة transform لتعيين بيانات السياق المحددة كسياق مباشر.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';
import { AsyncLocalStorage } from 'node:async_hooks';

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store, (data) => {
  return { data };
});

const diagnostics_channel = require('node:diagnostics_channel');
const { AsyncLocalStorage } = require('node:async_hooks');

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store, (data) => {
  return { data };
});

`channel.unbindStore(store)`

تمت الإضافة في: الإصدار v19.9.0، الإصدار v18.19.0

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

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

store <AsyncLocalStorage> المخزن المراد إلغاء ربطه من القناة.
الإرجاع: <boolean> true إذا تم العثور على المخزن، وfalse خلاف ذلك.

قم بإزالة معالج الرسائل الذي تم تسجيله مسبقًا في هذه القناة باستخدام channel.bindStore(store).

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';
import { AsyncLocalStorage } from 'node:async_hooks';

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store);
channel.unbindStore(store);

const diagnostics_channel = require('node:diagnostics_channel');
const { AsyncLocalStorage } = require('node:async_hooks');

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store);
channel.unbindStore(store);

`channel.runStores(context, fn[, thisArg[, ...args]])`

تمت الإضافة في: الإصدار v19.9.0، v18.19.0

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

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

context <any> رسالة لإرسالها إلى المشتركين وربطها بالمخازن
fn <Function> معالج للتشغيل داخل سياق التخزين المدخل
thisArg <any> المتلقي المراد استخدامه لاستدعاء الدالة.
...args <any> وسائط اختيارية لتمريرها إلى الدالة.

يطبق البيانات المحددة على أي مثيلات AsyncLocalStorage مرتبطة بالقناة طوال مدة الدالة المحددة، ثم ينشر إلى القناة ضمن نطاق تطبيق تلك البيانات على المخازن.

إذا تم إعطاء دالة تحويل إلى channel.bindStore(store) فسيتم تطبيقها لتحويل بيانات الرسالة قبل أن تصبح قيمة السياق للمخزن. يمكن الوصول إلى سياق التخزين السابق من داخل دالة التحويل في الحالات التي تتطلب ربط السياق.

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

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';
import { AsyncLocalStorage } from 'node:async_hooks';

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store, (message) => {
  const parent = store.getStore();
  return new Span(message, parent);
});
channel.runStores({ some: 'message' }, () => {
  store.getStore(); // Span({ some: 'message' })
});

const diagnostics_channel = require('node:diagnostics_channel');
const { AsyncLocalStorage } = require('node:async_hooks');

const store = new AsyncLocalStorage();

const channel = diagnostics_channel.channel('my-channel');

channel.bindStore(store, (message) => {
  const parent = store.getStore();
  return new Span(message, parent);
});
channel.runStores({ some: 'message' }, () => {
  store.getStore(); // Span({ some: 'message' })
});

الفئة: `TracingChannel`

أُضيف في: الإصدار 19.9.0، 18.19.0

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

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

الفئة TracingChannel هي مجموعة من قنوات TracingChannel تعبر معًا عن إجراء واحد قابل للتتبع. يتم استخدامه لإضفاء الطابع الرسمي وتبسيط عملية إنتاج الأحداث لتتبع تدفق التطبيق. يتم استخدام diagnostics_channel.tracingChannel() لإنشاء TracingChannel. كما هو الحال مع Channel، يوصى بإنشاء وإعادة استخدام TracingChannel واحد في المستوى الأعلى من الملف بدلاً من إنشائه ديناميكيًا.

`tracingChannel.subscribe(subscribers)`

أُضيف في: الإصدار 19.9.0، 18.19.0

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

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

subscribers <الكائن> مجموعة من مشتركي قنوات TracingChannel
- start <الدالة> مشترك حدث البدء
- end <الدالة> مشترك حدث النهاية
- asyncStart <الدالة> مشترك حدث البدء غير المتزامن
- asyncEnd <الدالة> مشترك حدث النهاية غير المتزامن
- error <الدالة> مشترك حدث الخطأ

مساعد للاشتراك في مجموعة من الدوال في القنوات المقابلة. هذا هو نفسه استدعاء channel.subscribe(onMessage) على كل قناة على حدة.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.subscribe({
  start(message) {
    // معالجة رسالة البدء
  },
  end(message) {
    // معالجة رسالة النهاية
  },
  asyncStart(message) {
    // معالجة رسالة البدء غير المتزامن
  },
  asyncEnd(message) {
    // معالجة رسالة النهاية غير المتزامن
  },
  error(message) {
    // معالجة رسالة الخطأ
  },
});

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

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.subscribe({
  start(message) {
    // معالجة رسالة البدء
  },
  end(message) {
    // معالجة رسالة النهاية
  },
  asyncStart(message) {
    // معالجة رسالة البدء غير المتزامن
  },
  asyncEnd(message) {
    // معالجة رسالة النهاية غير المتزامن
  },
  error(message) {
    // معالجة رسالة الخطأ
  },
});

`tracingChannel.unsubscribe(subscribers)`

أضيف في: v19.9.0, v18.19.0

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

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

subscribers <Object> مجموعة مشتركي قنوات TracingChannel
- start <Function> مُشترك start event
- end <Function> مُشترك end event
- asyncStart <Function> مُشترك asyncStart event
- asyncEnd <Function> مُشترك asyncEnd event
- error <Function> مُشترك error event
الإرجاع: <boolean> true إذا تم إلغاء الاشتراك بنجاح في جميع المعالجات، و false خلاف ذلك.

مساعد لإلغاء الاشتراك في مجموعة من الدوال من القنوات المقابلة. هذا هو نفسه استدعاء channel.unsubscribe(onMessage) على كل قناة على حدة.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.unsubscribe({
  start(message) {
    // Handle start message
  },
  end(message) {
    // Handle end message
  },
  asyncStart(message) {
    // Handle asyncStart message
  },
  asyncEnd(message) {
    // Handle asyncEnd message
  },
  error(message) {
    // Handle error message
  },
});

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

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.unsubscribe({
  start(message) {
    // Handle start message
  },
  end(message) {
    // Handle end message
  },
  asyncStart(message) {
    // Handle asyncStart message
  },
  asyncEnd(message) {
    // Handle asyncEnd message
  },
  error(message) {
    // Handle error message
  },
});

`tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]])`

أُضيف في: v19.9.0, v18.19.0

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

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

fn <Function> دالة لتضمين تتبع حولها
context <Object> كائن مشترك لربط الأحداث من خلاله
thisArg <any> المستقبل الذي سيستخدم لاستدعاء الدالة
...args <any> وسيطات اختيارية لتمريرها إلى الدالة
Returns: <any> قيمة إرجاع الدالة المعطاة

تتبع استدعاء دالة متزامنة. سينتج هذا دائمًا start حدث و end حدث حول التنفيذ وقد ينتج error حدث إذا طرحت الدالة المعطاة خطأ. سيقوم هذا بتشغيل الدالة المعطاة باستخدام channel.runStores(context, ...) على قناة start التي تضمن أن جميع الأحداث يجب أن تحتوي على أي مخازن مرتبطة مضبوطة لتطابق سياق التتبع هذا.

لضمان تكوين مخططات تتبع صحيحة فقط، سيتم نشر الأحداث فقط إذا كان المشتركون موجودين قبل بدء التتبع. لن تتلقى الاشتراكات التي تتم إضافتها بعد بدء التتبع الأحداث المستقبلية من هذا التتبع، وستظهر عمليات التتبع المستقبلية فقط.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.traceSync(() => {
  // Do something
}, {
  some: 'thing',
});

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

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.traceSync(() => {
  // Do something
}, {
  some: 'thing',
});

`tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]])`

تمت الإضافة في: v19.9.0, v18.19.0

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

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

fn <Function> دالة إرجاع الوعد لتضمين تتبع حولها
context <Object> كائن مشترك لربط أحداث التتبع من خلاله
thisArg <any> المستقبِل المراد استخدامه لاستدعاء الدالة
...args <any> وسيطات اختيارية لتمريرها إلى الدالة
إرجاع: <Promise> متسلسلة من الوعد الذي تم إرجاعه بواسطة الدالة المعطاة

تتبع استدعاء دالة إرجاع الوعد. سيؤدي هذا دائمًا إلى إنتاج start event و end event حول الجزء المتزامن من تنفيذ الدالة، وسينتج asyncStart event و asyncEnd event عند الوصول إلى استمرارية الوعد. وقد ينتج أيضًا error event إذا أطلقت الدالة المعطاة خطأً أو إذا تم رفض الوعد الذي تم إرجاعه. سيؤدي هذا إلى تشغيل الدالة المعطاة باستخدام channel.runStores(context, ...) على قناة start التي تضمن أن جميع الأحداث يجب أن تحتوي على أي متاجر مرتبطة مُعيَّنة لتتوافق مع سياق التتبع هذا.

لضمان تكوين رسوم بيانية للتتبع الصحيحة فقط، سيتم نشر الأحداث فقط إذا كان المشتركون موجودين قبل بدء التتبع. لن تتلقى الاشتراكات التي تتم إضافتها بعد بدء التتبع الأحداث المستقبلية من هذا التتبع، وستظهر عمليات التتبع المستقبلية فقط.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.tracePromise(async () => {
  // Do something
}, {
  some: 'thing',
});

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

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.tracePromise(async () => {
  // Do something
}, {
  some: 'thing',
});

`tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]])`

تمت الإضافة في: الإصدار 19.9.0، الإصدار 18.19.0

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

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

fn <Function> استدعاء باستخدام دالة لتضمين تتبع حولها
position <number> موضع وسيطة مفهرسة من الصفر للاستدعاء المتوقع (افتراضيًا الوسيطة الأخيرة إذا تم تمرير undefined)
context <Object> كائن مشترك لربط أحداث التتبع من خلاله (افتراضيًا {} إذا تم تمرير undefined)
thisArg <any> المستقبل المراد استخدامه لاستدعاء الدالة
...args <any> الوسائط المراد تمريرها إلى الدالة (يجب أن تتضمن الاستدعاء)
الإرجاع: <any> قيمة الإرجاع للدالة المحددة

تتبع استدعاء دالة استقبال الاستدعاء. من المتوقع أن يتبع الاستدعاء الاصطلاح المتعارف عليه للخطأ باعتباره الوسيطة الأولى. سينتج هذا دائمًا start event و end event حول الجزء المتزامن من تنفيذ الدالة، وسينتج asyncStart event و asyncEnd event حول تنفيذ الاستدعاء. قد ينتج أيضًا error event إذا كانت الدالة المحددة تطرح أو تم تعيين الوسيطة الأولى التي تم تمريرها إلى الاستدعاء. سيؤدي هذا إلى تشغيل الدالة المحددة باستخدام channel.runStores(context, ...) على قناة start مما يضمن أن جميع الأحداث يجب أن تحتوي على أي مخازن مرتبطة مضبوطة لتطابق سياق التتبع هذا.

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

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.traceCallback((arg1, callback) => {
  // Do something
  callback(null, 'result');
}, 1, {
  some: 'thing',
}, thisArg, arg1, callback);

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

const channels = diagnostics_channel.tracingChannel('my-channel');

channels.traceCallback((arg1, callback) => {
  // Do something
  callback(null, 'result');
}, 1, {
  some: 'thing',
}, thisArg, arg1, callback);

سيتم أيضًا تشغيل الاستدعاء باستخدام channel.runStores(context, ...) مما يتيح استعادة فقدان السياق في بعض الحالات.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';
import { AsyncLocalStorage } from 'node:async_hooks';

const channels = diagnostics_channel.tracingChannel('my-channel');
const myStore = new AsyncLocalStorage();

// The start channel sets the initial store data to something
// and stores that store data value on the trace context object
channels.start.bindStore(myStore, (data) => {
  const span = new Span(data);
  data.span = span;
  return span;
});

// Then asyncStart can restore from that data it stored previously
channels.asyncStart.bindStore(myStore, (data) => {
  return data.span;
});

const diagnostics_channel = require('node:diagnostics_channel');
const { AsyncLocalStorage } = require('node:async_hooks');

const channels = diagnostics_channel.tracingChannel('my-channel');
const myStore = new AsyncLocalStorage();

// The start channel sets the initial store data to something
// and stores that store data value on the trace context object
channels.start.bindStore(myStore, (data) => {
  const span = new Span(data);
  data.span = span;
  return span;
});

// Then asyncStart can restore from that data it stored previously
channels.asyncStart.bindStore(myStore, (data) => {
  return data.span;
});

`tracingChannel.hasSubscribers`

تمت الإضافة في: v22.0.0, v20.13.0

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

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

الإرجاع: <boolean> صحيح إذا كان أي من القنوات الفردية لديه مشترك، خطأ إذا لم يكن كذلك.

هذه طريقة مساعدة متاحة في مثيل TracingChannel للتحقق مما إذا كان أي من قنوات TracingChannel لديه مشتركون. يتم إرجاع صحيح إذا كان لأي منهم مشترك واحد على الأقل، ويتم إرجاع خطأ بخلاف ذلك.

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel';

const channels = diagnostics_channel.tracingChannel('my-channel');

if (channels.hasSubscribers) {
  // افعل شيئًا
}

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

const channels = diagnostics_channel.tracingChannel('my-channel');

if (channels.hasSubscribers) {
  // افعل شيئًا
}

قنوات TracingChannel

TracingChannel هي مجموعة من عدة قنوات تشخيصية تمثل نقاطًا محددة في دورة حياة تنفيذ إجراء واحد قابل للتتبع. يتم تقسيم السلوك إلى خمس قنوات تشخيصية تتكون من start و end و asyncStart و asyncEnd و error. سيشارك إجراء واحد قابل للتتبع نفس كائن الحدث بين جميع الأحداث، ويمكن أن يكون هذا مفيدًا لإدارة الارتباط من خلال خريطة ضعيفة.

سيتم تمديد كائنات الأحداث هذه بقيم result أو error عندما "تكتمل" المهمة. في حالة مهمة متزامنة، ستكون result هي قيمة الإرجاع وسيكون error أي شيء يتم طرحه من الوظيفة. مع وظائف غير متزامنة تستند إلى رد الاتصال، ستكون result هي الوسيطة الثانية لرد الاتصال بينما سيكون error إما خطأ تم طرحه مرئيًا في حدث end أو الوسيطة الأولى لرد الاتصال في أي من حدثي asyncStart أو asyncEnd.

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

يجب أن تتبع قنوات التتبع نمط تسمية:

tracing:module.class.method:start أو tracing:module.function:start
tracing:module.class.method:end أو tracing:module.function:end
tracing:module.class.method:asyncStart أو tracing:module.function:asyncStart
tracing:module.class.method:asyncEnd أو tracing:module.function:asyncEnd
tracing:module.class.method:error أو tracing:module.function:error

`start(event)`

الاسم: tracing:${name}:start

يمثل حدث start النقطة التي يتم فيها استدعاء الدالة. في هذه المرحلة، قد تحتوي بيانات الحدث على وسائط الدالة أو أي شيء آخر متاح في بداية تنفيذ الدالة.

`end(event)`

الاسم: tracing:${name}:end

يمثل حدث end النقطة التي تُرجع فيها استدعاء الدالة قيمة. في حالة الدالة غير المتزامنة، يكون هذا هو الوقت الذي يتم فيه إرجاع الوعد وليس عندما تقوم الدالة نفسها بإصدار عبارة إرجاع داخليًا. في هذه المرحلة، إذا كانت الدالة التي تم تتبعها متزامنة، فسيتم تعيين الحقل result على القيمة التي تم إرجاعها من الدالة. بدلاً من ذلك، قد يكون الحقل error موجودًا لتمثيل أي أخطاء تم طرحها.

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

`asyncStart(event)`

الاسم: tracing:${name}:asyncStart

يمثل حدث asyncStart الوصول إلى رد الاتصال أو الاستمرار لدالة قابلة للتتبع. في هذه المرحلة، قد تتوفر أشياء مثل وسائط رد الاتصال، أو أي شيء آخر يعبر عن "نتيجة" الإجراء.

بالنسبة للدوال المستندة إلى ردود الاتصال، سيتم تعيين الوسيطة الأولى لرد الاتصال إلى الحقل error، إذا لم تكن undefined أو null، وسيتم تعيين الوسيطة الثانية إلى الحقل result.

بالنسبة للوعود، سيتم تعيين الوسيطة إلى مسار resolve إلى result أو سيتم تعيين الوسيطة إلى مسار reject إلى error.

`asyncEnd(event)`

الاسم: tracing:${name}:asyncEnd

يمثل حدث asyncEnd رد الاتصال لدالة غير متزامنة يتم إرجاعها. ليس من المحتمل أن تتغير بيانات الحدث بعد حدث asyncStart، ومع ذلك قد يكون من المفيد رؤية النقطة التي يكتمل فيها رد الاتصال.

`error(event)`

الاسم: tracing:${name}:error

يمثل حدث error أي خطأ ينتج عن الدالة القابلة للتتبع إما بشكل متزامن أو غير متزامن. إذا تم طرح خطأ في الجزء المتزامن من الدالة التي تم تتبعها، فسيتم تعيين الخطأ إلى حقل error في الحدث وسيتم تشغيل حدث error. إذا تم استلام خطأ بشكل غير متزامن من خلال استدعاء أو رفض وعد، فسيتم أيضًا تعيينه إلى حقل error في الحدث وتشغيل حدث error.

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

القنوات المضمنة

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

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

في حين أن واجهة برمجة تطبيقات diagnostics_channel تعتبر الآن مستقرة، فإن القنوات المضمنة المتاحة حاليًا ليست كذلك. يجب الإعلان عن استقرار كل قناة على حدة.

HTTP

http.client.request.created

request <http.ClientRequest>

يتم إصداره عندما ينشئ العميل كائن طلب. على عكس http.client.request.start، يتم إصدار هذا الحدث قبل إرسال الطلب.

http.client.request.start

request <http.ClientRequest>

يتم إصداره عندما يبدأ العميل طلبًا.

http.client.request.error

request <http.ClientRequest>
error <Error>

يتم إصداره عند حدوث خطأ أثناء طلب العميل.

http.client.response.finish

request <http.ClientRequest>
response <http.IncomingMessage>

يتم إصداره عندما يتلقى العميل استجابة.

http.server.request.start

يتم إصداره عندما يتلقى الخادم طلبًا.

http.server.response.created

request <http.IncomingMessage>
response <http.ServerResponse>

يتم إصداره عندما ينشئ الخادم استجابة. يتم إصدار الحدث قبل إرسال الاستجابة.

http.server.response.finish

يتم إصداره عندما يرسل الخادم استجابة.

الوحدات

module.require.start

event <Object> يحتوي على الخصائص التالية:
- id - الوسيطة التي تم تمريرها إلى require(). اسم الوحدة.
- parentFilename - اسم الوحدة التي حاولت استدعاء require(id).

يتم إصداره عند تنفيذ require(). انظر start event.

module.require.end

event <Object> يحتوي على الخصائص التالية:
- id - الوسيطة التي تم تمريرها إلى require(). اسم الوحدة.
- parentFilename - اسم الوحدة التي حاولت استدعاء require(id).

يتم إصداره عند إرجاع استدعاء require(). انظر end event.

module.require.error

event <Object> يحتوي على الخصائص التالية:
- id - الوسيطة التي تم تمريرها إلى require(). اسم الوحدة.
- parentFilename - اسم الوحدة التي حاولت استدعاء require(id).
error <Error>

يتم إصداره عندما يلقي require() خطأ. انظر error event.

module.import.asyncStart

event <Object> يحتوي على الخصائص التالية:
- id - الوسيطة التي تم تمريرها إلى import(). اسم الوحدة.
- parentURL - كائن URL للوحدة التي حاولت استدعاء import(id).

يتم إصداره عند استدعاء import(). انظر asyncStart event.

module.import.asyncEnd

event <Object> يحتوي على الخصائص التالية:
- id - الوسيطة التي تم تمريرها إلى import(). اسم الوحدة.
- parentURL - كائن URL للوحدة التي حاولت استدعاء import(id).

يتم إصداره عند اكتمال import(). انظر asyncEnd event.

module.import.error

event <Object> يحتوي على الخصائص التالية:
- id - الوسيطة التي تم تمريرها إلى import(). اسم الوحدة.
- parentURL - كائن URL للوحدة التي حاولت استدعاء import(id).
error <Error>

يتم إصداره عندما يلقي import() خطأ. انظر error event.

NET

net.client.socket

socket <net.Socket>

يصدر هذا الحدث عند إنشاء مقبس TCP أو pipe جديد للعميل.

net.server.socket

socket <net.Socket>

يصدر هذا الحدث عند استقبال اتصال TCP أو pipe جديد.

tracing:net.server.listen:asyncStart

server <net.Server>
options <Object>

يصدر هذا الحدث عند استدعاء net.Server.listen()، قبل إعداد المنفذ أو الـ pipe فعليًا.

tracing:net.server.listen:asyncEnd

server <net.Server>

يصدر هذا الحدث عند اكتمال net.Server.listen() وبالتالي يصبح الخادم جاهزًا لقبول الاتصال.

tracing:net.server.listen:error

server <net.Server>
error <Error>

يصدر هذا الحدث عندما تُرجع net.Server.listen() خطأً.

UDP

udp.socket

socket <dgram.Socket>

يصدر هذا الحدث عند إنشاء مقبس UDP جديد.

Process

أضيف في: v16.18.0

child_process

process <ChildProcess>

يصدر هذا الحدث عند إنشاء عملية جديدة.

Worker Thread

أضيف في: v16.18.0

worker_threads

worker Worker

يصدر هذا الحدث عند إنشاء thread جديد.

قناة التشخيص ​

واجهة برمجة التطبيقات العامة ​

نظرة عامة ​

diagnostics_channel.hasSubscribers(name) ​

diagnostics_channel.channel(name) ​

diagnostics_channel.subscribe(name, onMessage) ​

diagnostics_channel.unsubscribe(name, onMessage) ​

diagnostics_channel.tracingChannel(nameOrChannels) ​

الصنف: Channel ​

channel.hasSubscribers ​

channel.publish(message) ​

channel.subscribe(onMessage) ​

channel.unsubscribe(onMessage) ​

channel.bindStore(store[, transform]) ​

channel.unbindStore(store) ​

channel.runStores(context, fn[, thisArg[, ...args]]) ​

الفئة: TracingChannel ​

tracingChannel.subscribe(subscribers) ​

tracingChannel.unsubscribe(subscribers) ​

tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]]) ​

tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]]) ​

tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]]) ​

tracingChannel.hasSubscribers ​

قنوات TracingChannel ​

start(event) ​

end(event) ​

asyncStart(event) ​

asyncEnd(event) ​

error(event) ​

القنوات المضمنة ​

HTTP ​

الوحدات ​

NET ​

UDP ​

Process ​

Worker Thread ​

قناة التشخيص

واجهة برمجة التطبيقات العامة

نظرة عامة

`diagnostics_channel.hasSubscribers(name)`

`diagnostics_channel.channel(name)`

`diagnostics_channel.subscribe(name, onMessage)`

`diagnostics_channel.unsubscribe(name, onMessage)`

`diagnostics_channel.tracingChannel(nameOrChannels)`

الصنف: `Channel`

`channel.hasSubscribers`

`channel.publish(message)`

`channel.subscribe(onMessage)`

`channel.unsubscribe(onMessage)`

`channel.bindStore(store[, transform])`

`channel.unbindStore(store)`

`channel.runStores(context, fn[, thisArg[, ...args]])`

الفئة: `TracingChannel`

`tracingChannel.subscribe(subscribers)`

`tracingChannel.unsubscribe(subscribers)`

`tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]])`

`tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]])`

`tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]])`

`tracingChannel.hasSubscribers`

قنوات TracingChannel

`start(event)`

`end(event)`

`asyncStart(event)`

`asyncEnd(event)`

`error(event)`

القنوات المضمنة

HTTP

الوحدات

NET

UDP

Process

Worker Thread