diagnostics_channel.hasSubscribers(name)

• name <string> | <symbol> Имя канала
• Возвращает: <boolean> Есть ли активные подписчики

Проверяет, есть ли у именованного канала активные подписчики. Это полезно, если подготовка сообщения, которое вы хотите отправить, может быть затратной.

Этот API необязателен, но полезен при публикации сообщений из кода, критичного к производительности.

import diagnostics_channel from 'node:diagnostics_channel';

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // There are subscribers, prepare and publish message
}

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

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // There are subscribers, prepare and publish message
}

diagnostics_channel.channel(name)

• name <string> | <symbol> Имя канала
• Возвращает: <Channel> Объект указанного канала

Это основная точка входа для всех, кто хочет публиковать сообщения в именованный канал. Она создает объект канала, оптимизированный для максимально возможного снижения накладных расходов во время публикации.

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)

• name <string> | <symbol> Имя канала
• onMessage <Function> Обработчик для получения сообщений канала
  • message <any> Данные сообщения
  • name <string> | <symbol> Имя канала

Регистрирует обработчик сообщений для подписки на этот канал. Этот обработчик сообщений будет выполняться синхронно при каждой публикации сообщения в канал. Любые ошибки, возникшие в обработчике сообщений, вызовут событие 'uncaughtException'.

import diagnostics_channel from 'node:diagnostics_channel';

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Received data
});

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

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Received data
});

diagnostics_channel.unsubscribe(name, onMessage)

• name <string> | <symbol> Имя канала
• onMessage <Function> Ранее подписанный обработчик, который нужно удалить
• Возвращает: <boolean> true, если обработчик найден, false в противном случае.

Удаляет обработчик сообщений, ранее зарегистрированный для этого канала с помощью diagnostics_channel.subscribe(name, onMessage).

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)

• nameOrChannels <string> | <TracingChannel> Имя канала или объект, содержащий все каналы TracingChannel
• Возвращает: <TracingChannel> Набор каналов для трассировки

Создает оболочку TracingChannel для заданных каналов TracingChannel. Если задано имя, соответствующие каналы трассировки будут созданы в виде tracing:${name}:${eventType}, где eventType соответствует типам каналов TracingChannel.

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.hasSubscribers

• Возвращает: <boolean> Есть ли активные подписчики

Проверяет, есть ли у этого канала активные подписчики. Это полезно, если подготовка сообщения, которое вы хотите отправить, может быть затратной.

Этот API необязателен, но полезен при публикации сообщений из кода, критичного к производительности.

import diagnostics_channel from 'node:diagnostics_channel';

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

if (channel.hasSubscribers) {
  // There are subscribers, prepare and publish message
}

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

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

if (channel.hasSubscribers) {
  // There are subscribers, prepare and publish message
}

channel.publish(message)

• message <any> Сообщение, отправляемое подписчикам канала

Публикует сообщение для всех подписчиков канала. При этом обработчики сообщений будут вызваны синхронно и выполнятся в том же контексте.

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)

• onMessage <Function> Обработчик для получения сообщений канала
  • message <any> Данные сообщения
  • name <string> | <symbol> Имя канала

Регистрирует обработчик сообщений для подписки на этот канал. Этот обработчик сообщений будет выполняться синхронно при каждой публикации сообщения в канал. Любые ошибки, возникшие в обработчике сообщений, вызовут событие 'uncaughtException'.

import diagnostics_channel from 'node:diagnostics_channel';

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

channel.subscribe((message, name) => {
  // Received data
});

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

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

channel.subscribe((message, name) => {
  // Received data
});

channel.unsubscribe(onMessage)

• onMessage <Function> Ранее подписанный обработчик, который нужно удалить
• Возвращает: <boolean> true, если обработчик найден, false в противном случае.

Удаляет обработчик сообщений, ранее зарегистрированный для этого канала с помощью channel.subscribe(onMessage).

import diagnostics_channel from 'node:diagnostics_channel';

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

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

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);

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

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

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

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);

channel.bindStore(store[, transform])

• store <AsyncLocalStorage> Хранилище, с которым нужно связать данные контекста
• transform <Function> Преобразует данные контекста перед установкой контекста хранилища

При вызове channel.runStores(context, ...) заданные данные контекста будут применены ко всем хранилищам, связанным с каналом. Если хранилище уже связано, предыдущая функция transform будет заменена новой. Функцию transform можно не указывать, чтобы задать переданные данные контекста непосредственно в качестве контекста.

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)

• store <AsyncLocalStorage> Хранилище, связь которого с каналом нужно разорвать.
• Возвращает: <boolean> true, если хранилище найдено, false в противном случае.

Удаляет обработчик сообщений, ранее зарегистрированный для этого канала с помощью channel.bindStore(store).

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

• context <any> Сообщение для отправки подписчикам и привязки к хранилищам
• fn <Function> Обработчик, выполняемый в установленном контексте хранилища
• thisArg <any> Объект-получатель, используемый при вызове функции.
• ...args <any> Необязательные аргументы, передаваемые функции.

Применяет заданные данные ко всем экземплярам AsyncLocalStorage, связанным с каналом, на время выполнения заданной функции, а затем публикует сообщение в канал в области действия, в которой эти данные применены к хранилищам.

Если для channel.bindStore(store) была задана функция преобразования, она будет преобразовывать данные сообщения перед тем, как они станут значением контекста хранилища. Предыдущий контекст хранилища доступен внутри функции преобразования в случаях, когда требуется связать контексты.

Контекст, примененный к хранилищу, должен быть доступен в любом асинхронном коде, продолжающем выполнение, начатое во время заданной функции; однако в некоторых ситуациях может произойти потеря контекста.

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.subscribe(subscribers)

• subscribers <Object> Набор подписчиков каналов TracingChannel
  • start <Function> Подписчик события start
  • end <Function> Подписчик события end
  • asyncStart <Function> Подписчик события asyncStart
  • asyncEnd <Function> Подписчик события asyncEnd
  • error <Function> Подписчик события error

Вспомогательная функция для подписки набора функций на соответствующие каналы. Это эквивалентно отдельному вызову channel.subscribe(onMessage) для каждого канала.

import diagnostics_channel from 'node:diagnostics_channel';

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

channels.subscribe({
  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.subscribe({
  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.unsubscribe(subscribers)

• subscribers <Object> Набор подписчиков каналов TracingChannel
  • start <Function> Подписчик события start
  • end <Function> Подписчик события end
  • asyncStart <Function> Подписчик события asyncStart
  • asyncEnd <Function> Подписчик события asyncEnd
  • error <Function> Подписчик события error
• Возвращает: <boolean> true, если все обработчики успешно отписаны, и false в противном случае.

Вспомогательная функция для отписки набора функций от соответствующих каналов. Это эквивалентно отдельному вызову channel.unsubscribe(onMessage) для каждого канала.

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

• fn <Function> Функция, выполнение которой нужно обернуть трассировкой
• context <Object> Общий объект для связывания событий
• thisArg <any> Объект-получатель, используемый при вызове функции
• ...args <any> Необязательные аргументы, передаваемые функции
• Возвращает: <any> Возвращаемое значение заданной функции

Трассирует вызов синхронной функции. При этом вокруг выполнения всегда создаются события start и end; также может быть создано событие error, если заданная функция выбрасывает ошибку. Заданная функция будет выполнена с помощью channel.runStores(context, ...) на канале start, что гарантирует соответствие всех связанных хранилищ контексту трассировки во всех событиях.

Чтобы гарантировать формирование только корректных графов трассировки, события публикуются только при наличии подписчиков до начала трассировки. Подписчики, добавленные после начала трассировки, не получат последующие события этой трассировки — им будут доступны только будущие трассировки.

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

• fn <Function> Функция, возвращающая Promise, выполнение которой нужно обернуть трассировкой
• context <Object> Общий объект для связывания событий трассировки
• thisArg <any> Объект-получатель, используемый при вызове функции
• ...args <any> Необязательные аргументы, передаваемые функции
• Возвращает: <Promise> Цепочка, созданная на основе Promise, возвращенного заданной функцией

Трассирует вызов функции, возвращающей Promise. При этом вокруг синхронной части выполнения функции всегда создаются события start и end, а при продолжении выполнения Promise создаются события asyncStart и asyncEnd. Также может быть создано событие error, если заданная функция выбрасывает ошибку или возвращенный Promise отклоняется. Заданная функция будет выполнена с помощью channel.runStores(context, ...) на канале start, что гарантирует соответствие всех связанных хранилищ контексту трассировки во всех событиях.

Чтобы гарантировать формирование только корректных графов трассировки, события публикуются только при наличии подписчиков до начала трассировки. Подписчики, добавленные после начала трассировки, не получат последующие события этой трассировки — им будут доступны только будущие трассировки.

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

• fn <Function> Функция с обратным вызовом, выполнение которой нужно обернуть трассировкой
• position <number> Индекс позиции аргумента обратного вызова, начиная с нуля (по умолчанию используется последний аргумент, если передан undefined)
• context <Object> Общий объект для связывания событий трассировки (по умолчанию используется {}, если передан undefined)
• thisArg <any> Объект-получатель, используемый при вызове функции
• ...args <any> Аргументы, передаваемые функции (должны включать обратный вызов)
• Возвращает: <any> Возвращаемое значение заданной функции

Трассирует вызов функции, принимающей обратный вызов. Ожидается, что обратный вызов будет следовать соглашению, при котором первым аргументом передается ошибка. При этом вокруг синхронной части выполнения функции всегда создаются события start и end, а вокруг выполнения обратного вызова — события asyncStart и asyncEnd. Также может быть создано событие error, если заданная функция выбрасывает ошибку или в качестве первого аргумента обратного вызова передано значение. Заданная функция будет выполнена с помощью channel.runStores(context, ...) на канале start, что гарантирует соответствие всех связанных хранилищ контексту трассировки во всех событиях.

Чтобы гарантировать формирование только корректных графов трассировки, события публикуются только при наличии подписчиков до начала трассировки. Подписчики, добавленные после начала трассировки, не получат последующие события этой трассировки — им будут доступны только будущие трассировки.

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, ...), что в некоторых случаях позволяет восстановить потерянный контекст.

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

• Возвращает: <boolean> true, если у какого-либо отдельного канала есть подписчик, и false, если нет.

Это вспомогательный метод экземпляра TracingChannel, который проверяет, есть ли подписчики у каких-либо каналов TracingChannel. Возвращается true, если хотя бы у одного из них есть подписчик, в противном случае возвращается false.

import diagnostics_channel from 'node:diagnostics_channel';

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

if (channels.hasSubscribers) {
  // Do something
}

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

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

if (channels.hasSubscribers) {
  // Do something
}

start(event)

• Имя: tracing:${name}:start

Событие start обозначает момент вызова функции. На этом этапе данные события могут содержать аргументы функции или любые другие сведения, доступные в самом начале выполнения функции.

end(event)

• Имя: tracing:${name}:end

Событие end обозначает момент, когда вызов функции возвращает значение. Для асинхронной функции это происходит в момент возврата промиса, а не тогда, когда сама функция выполняет внутреннюю инструкцию return. На этом этапе, если отслеживаемая функция была синхронной, поле result будет содержать возвращаемое функцией значение. Также может присутствовать поле error, обозначающее любую выброшенную ошибку.

Для отслеживания ошибок рекомендуется подписываться непосредственно на событие error, поскольку отслеживаемое действие может привести к нескольким ошибкам. Например, внутренняя асинхронная задача может завершиться с ошибкой до того, как синхронная часть задачи выбросит ошибку.

asyncStart(event)

• Имя: tracing:${name}:asyncStart

Событие asyncStart обозначает момент достижения обратного вызова или продолжения отслеживаемой функции. На этом этапе могут быть доступны аргументы обратного вызова или любые другие данные, выражающие «результат» действия.

Для функций на основе обратных вызовов первый аргумент обратного вызова будет присвоен полю error, если он не равен undefined или null, а второй аргумент будет присвоен полю result.

Для промисов аргумент пути resolve будет присвоен result, а аргумент пути reject будет присвоен error.

Для отслеживания ошибок рекомендуется подписываться непосредственно на событие error, поскольку отслеживаемое действие может привести к нескольким ошибкам. Например, внутренняя асинхронная задача может завершиться с ошибкой до того, как синхронная часть задачи выбросит ошибку.

asyncEnd(event)

• Имя: tracing:${name}:asyncEnd

Событие asyncEnd обозначает возврат из обратного вызова асинхронной функции. Маловероятно, что данные события изменятся после события asyncStart, однако может быть полезно видеть момент завершения обратного вызова.

error(event)

• Имя: tracing:${name}:error

Событие error обозначает любую ошибку, возникшую в отслеживаемой функции синхронно или асинхронно. Если ошибка выбрасывается в синхронной части отслеживаемой функции, она будет присвоена полю error события, после чего будет вызвано событие error. Если ошибка получена асинхронно через обратный вызов или отклонение промиса, она также будет присвоена полю error события и вызовет событие error.

Один вызов отслеживаемой функции может привести к нескольким ошибкам, поэтому это следует учитывать при обработке данного события. Например, если внутри функции запускается другая асинхронная задача, которая завершается с ошибкой, а затем синхронная часть функции выбрасывает ошибку, будут сгенерированы два события error: одно для синхронной ошибки и одно для асинхронной.

Консоль

HTTP

HTTP/2

Модули

NET

UDP

Процесс

Поток Worker