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. Если указанная функция выбрасывает ошибку или возвращенный Promise отклоняется, также может создаваться событие error. Указанная функция выполняется с помощью 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

Модули

Сеть

UDP

Процесс

Поток Worker