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

[السجل]

الإصدار	التغييرات
v19.2.0، v18.13.0	أصبحت `diagnostics_channel` مستقرة.
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) {
  // البيانات المُستقبَلة
}

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

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

const diagnostics_channel = require('node:diagnostics_channel')

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

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')

// أو...

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')

// أو...

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`

مضاف في: v15.1.0، v14.17.0

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

`channel.hasSubscribers`

مضاف في: v15.1.0، v14.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)`

مضاف في: v15.1.0، v14.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 <Function> مُعالِج الاستقبال لرسائل القناة
- message <any> بيانات الرسالة
- name <string> | <symbol> اسم القناة

تسجيل مُعالِج رسائل للاشتراك في هذه القناة. سيتم تشغيل مُعالِج الرسائل هذا بشكل متزامن كلما نُشرت رسالة إلى القناة. ستؤدي أي أخطاء تُلقى في مُعالِج الرسائل إلى إطلاق حدث '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 <Function> مُعالِج المُشترك السابق لإزالته
المُرجَع: <boolean> 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 <Function> تحويل بيانات السياق قبل تعيين سياق المخزن

عندما يتم استدعاء 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 <أي> رسالة لإرسالها إلى المشتركين وربطها بالمخازن
fn <دالة> مُعالِج يتم تشغيله ضمن سياق التخزين المُدخَل
thisArg <أي> المستقبِل الذي سيتم استخدامه لإجراء استدعاء الدالة.
...args <أي> وسيطات اختيارية لإرسالها إلى الدالة.

يُطبّق البيانات المُعطاة على أيّ مثيل من 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`

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

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

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

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

`tracingChannel.subscribe(subscribers)`

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

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

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

subscribers <Object> مجموعة من مشتركي قنوات TracingChannel
- start <Function> مشترِك حدث start
- end <Function> مشترِك حدث end
- asyncStart <Function> مشترِك حدث asyncStart
- asyncEnd <Function> مشترِك حدث asyncEnd
- error <Function> مشترِك حدث 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) {
    // معالجة رسالة asyncStart
  },
  asyncEnd(message) {
    // معالجة رسالة asyncEnd
  },
  error(message) {
    // معالجة رسالة الخطأ
  },
})

const diagnostics_channel = require('node:diagnostics_channel')

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

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

`tracingChannel.unsubscribe(subscribers)`

مضاف في: v19.9.0، v18.19.0

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

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

subscribers <Object> مجموعة من المشتركين في قنوات TracingChannel Channels
- 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) {
    // معالجة رسالة البدء
  },
  end(message) {
    // معالجة رسالة النهاية
  },
  asyncStart(message) {
    // معالجة رسالة asyncStart
  },
  asyncEnd(message) {
    // معالجة رسالة asyncEnd
  },
  error(message) {
    // معالجة رسالة الخطأ
  },
})

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.unsubscribe({
  start(message) {
    // معالجة رسالة البدء
  },
  end(message) {
    // معالجة رسالة النهاية
  },
  asyncStart(message) {
    // معالجة رسالة asyncStart
  },
  asyncEnd(message) {
    // معالجة رسالة asyncEnd
  },
  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> وسيطات اختيارية لإرسالها إلى الدالة
القيمة المُرجعَة: <any> قيمة الإرجاع للدالة المعطاة

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

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

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.traceSync(
  () => {
    // قم بشيء ما
  },
  {
    some: 'thing',
  }
)

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.traceSync(
  () => {
    // قم بشيء ما
  },
  {
    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 وحدث end حول الجزء المُزامِن من تنفيذ الدالة، وسيؤدي إلى إنشاء حدث asyncStart وحدث asyncEnd عند الوصول إلى استمرار الوعد. قد يُنتج أيضًا حدث error إذا ألقت الدالة المُعطاة خطأً أو رفض الوعد المُرجع. سيتم تشغيل الدالة المُعطاة باستخدام channel.runStores(context, ...) على قناة start التي تضمن أن جميع الأحداث يجب أن تحتوي على أي مخازن مُرتبطة مُعينة لتطابق سياق هذا التتبع.

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

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.tracePromise(
  async () => {
    // قم بشيء ما
  },
  {
    some: 'thing',
  }
)

const diagnostics_channel = require('node:diagnostics_channel')

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

channels.tracePromise(
  async () => {
    // قم بشيء ما
  },
  {
    some: 'thing',
  }
)

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

مضاف في: v19.9.0، v18.19.0

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

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

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

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

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

ESMCJS

import diagnostics_channel from 'node:diagnostics_channel'

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

channels.traceCallback(
  (arg1, callback) => {
    // قم بشيء ما
    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) => {
    // قم بشيء ما
    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()

// قناة البدء تُعيّن بيانات المخزن الأولية إلى شيء ما
// وتخزن قيمة بيانات المخزن تلك على كائن سياق التتبع
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// ثم يمكن لـ asyncStart الاستعادة من تلك البيانات التي تم تخزينها مسبقًا
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()

// قناة البدء تُعيّن بيانات المخزن الأولية إلى شيء ما
// وتخزن قيمة بيانات المخزن تلك على كائن سياق التتبع
channels.start.bindStore(myStore, data => {
  const span = new Span(data)
  data.span = span
  return span
})

// ثم يمكن لـ asyncStart الاستعادة من تلك البيانات التي تم تخزينها مسبقًا
channels.asyncStart.bindStore(myStore, data => {
  return data.span
})

`tracingChannel.hasSubscribers`

مضاف في: v22.0.0، v20.13.0

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

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

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

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

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 عبارة عن مجموعة من العديد من قنوات diagnostics_channels التي تمثل نقاطًا محددة في دورة حياة التنفيذ لإجراء واحد يمكن تعقبه. يتم تقسيم السلوك إلى خمس قنوات diagnostics_channels تتكون من start، end، asyncStart، asyncEnd، و error. سيشارك إجراء واحد قابل للتتبع نفس كائن الحدث بين جميع الأحداث، وهذا يمكن أن يكون مفيدًا لإدارة الارتباط من خلال weakmap.

سيتم توسيع كائنات الحدث هذه بقيم 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.

module.require.end

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

يُصدر عندما تُرجع مكالمة require(). انظر حدث end.

module.require.error

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

يُصدر عندما تُلقي require() خطأ. انظر حدث error.

module.import.asyncStart

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

يُصدر عندما يتم استدعاء import(). انظر حدث asyncStart.

module.import.asyncEnd

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

يُصدر عندما يكتمل import(). انظر حدث asyncEnd.

module.import.error

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

يُصدر عندما تُلقي import() خطأ. انظر حدث error.

شبكة

net.client.socket

socket <net.Socket>

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

net.server.socket

socket <net.Socket>

يتم إصداره عند استلام اتصال TCP أو أنبوب جديد.

tracing:net.server.listen:asyncStart

server <net.Server>
options <Object>

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

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 جديد.

عملية

مضاف في: v16.18.0

child_process

process <ChildProcess>

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

مؤشر ترابط عامل

مضاف في: v16.18.0

worker_threads

worker Worker

يتم إصداره عند إنشاء مؤشر ترابط جديد.

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

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

نظرة عامة ​

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 ​

الوحدات النمطية ​

شبكة ​

UDP ​

عملية ​

مؤشر ترابط عامل ​

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

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

نظرة عامة

`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

الوحدات النمطية

شبكة

UDP

عملية

مؤشر ترابط عامل