Канал диагностики

Модуль node:diagnostics_channel предоставляет API для создания именованных каналов, предназначенных для передачи произвольных данных сообщений в диагностических целях.

Доступ к нему можно получить с помощью:

import diagnostics_channel from 'node:diagnostics_channel';

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

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

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

Публичный API

Обзор

Ниже приведён краткий обзор публичного API.

import diagnostics_channel from 'node:diagnostics_channel';

// Get a reusable channel object
const channel = diagnostics_channel.channel('my-channel');

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

// Subscribe to the channel
diagnostics_channel.subscribe('my-channel', onMessage);

// Check if the channel has an active subscriber
if (channel.hasSubscribers) {
  // Publish data to the channel
  channel.publish({
    some: 'data',
  });
}

// Unsubscribe from the channel
diagnostics_channel.unsubscribe('my-channel', onMessage);

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

// Get a reusable channel object
const channel = diagnostics_channel.channel('my-channel');

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

// Subscribe to the channel
diagnostics_channel.subscribe('my-channel', onMessage);

// Check if the channel has an active subscriber
if (channel.hasSubscribers) {
  // Publish data to the channel
  channel.publish({
    some: 'data',
  });
}

// Unsubscribe from the channel
diagnostics_channel.unsubscribe('my-channel', onMessage);

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'),
});

diagnostics_channel.boundedChannel(nameOrChannels)

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

Создаёт оболочку BoundedChannel для указанных каналов. Если указано имя, соответствующие каналы будут созданы в форме tracing:${name}:${eventType}, где eventType — это start или end.

BoundedChannel — это упрощённая версия TracingChannel, которая отслеживает только синхронные операции. Она включает только события start и end, без событий asyncStart, asyncEnd или error, что делает её подходящей для трассировки операций, не связанных с асинхронным продолжением или обработкой ошибок.

import { boundedChannel, channel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

// or...

const wc2 = boundedChannel({
  start: channel('tracing:my-operation:start'),
  end: channel('tracing:my-operation:end'),
});

const { boundedChannel, channel } = require('node:diagnostics_channel');

const wc = boundedChannel('my-operation');

// or...

const wc2 = boundedChannel({
  start: channel('tracing:my-operation:start'),
  end: channel('tracing:my-operation:end'),
});

Класс: Channel

Класс Channel представляет отдельный именованный канал в конвейере данных. Он используется для отслеживания подписчиков и публикации сообщений, когда они присутствуют. Канал существует в виде отдельного объекта, чтобы избежать поиска каналов во время публикации, обеспечивая высокую скорость публикации и возможность интенсивного использования при минимальных затратах. Каналы создаются с помощью diagnostics_channel.channel(name); напрямую создавать канал с помощью new Channel(name) не поддерживается.

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

channel.withStoreScope(data)

• data <any> Сообщение для привязки к хранилищам
• Возвращает: {RunStoresScope} Объект области действия с возможностью освобождения ресурсов

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

Этот метод позволяет использовать явное управление ресурсами JavaScript (синтаксис using с Symbol.dispose) для управления контекстами хранилищ без обёртывания в замыкание.

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

const store = new AsyncLocalStorage();
const ch = channel('my-channel');

ch.bindStore(store, (message) => {
  return { ...message, timestamp: Date.now() };
});

{
  using scope = ch.withStoreScope({ request: 'data' });
  // Store is entered, data is published
  console.log(store.getStore()); // { request: 'data', timestamp: ... }
}
// Store is automatically restored on scope exit

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

const store = new AsyncLocalStorage();
const ch = channel('my-channel');

ch.bindStore(store, (message) => {
  return { ...message, timestamp: Date.now() };
});

{
  using scope = ch.withStoreScope({ request: 'data' });
  // Store is entered, data is published
  console.log(store.getStore()); // { request: 'data', timestamp: ... }
}
// Store is automatically restored on scope exit

Класс: RunStoresScope

Класс RunStoresScope представляет область действия с возможностью освобождения ресурсов, созданную с помощью channel.withStoreScope(data). Он управляет жизненным циклом контекстов хранилищ и обеспечивает их корректное восстановление при выходе из области действия.

Для корректного освобождения ресурсов необходимо использовать синтаксис using.

Класс: TracingChannel

Класс TracingChannel представляет собой набор каналов TracingChannel, которые вместе описывают одно действие, поддающееся трассировке. Он используется для формализации и упрощения создания событий, отслеживающих поток выполнения приложения. Для создания TracingChannel используется diagnostics_channel.tracingChannel(). Как и в случае с Channel, рекомендуется создавать и повторно использовать один TracingChannel на верхнем уровне файла, а не создавать их динамически.

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> Функция, вызов которой нужно обернуть трассировкой
• context <Object> Общий объект для сопоставления событий трассировки
• thisArg <any> Получатель, который будет использоваться при вызове функции
• ...args <any> Необязательные аргументы, передаваемые функции
• Возвращает: <any> Возвращаемое значение указанной функции или результат вызова .then(...) для возвращаемого значения, если у канала трассировки есть активные подписчики. Если возвращаемое значение не является Promise или thenable-объектом, оно возвращается как есть с выдачей предупреждения.

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

Если значение, возвращённое fn, не является Promise или thenable-объектом, оно будет возвращено с предупреждением, а события asyncStart и asyncEnd создаваться не будут.

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

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
}

Класс: BoundedChannel

Класс BoundedChannel — это упрощенная версия TracingChannel, которая отслеживает только синхронные операции. Он состоит из двух каналов (start и end) вместо пяти, без событий asyncStart, asyncEnd и error. Благодаря этому он подходит для трассировки операций, не включающих асинхронные продолжения или обработку ошибок.

Как и в случае с TracingChannel, рекомендуется создавать и повторно использовать один экземпляр BoundedChannel на верхнем уровне файла, а не создавать их динамически.

boundedChannel.hasSubscribers

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

Проверяет, есть ли подписчики у канала start или end.

import { boundedChannel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

if (wc.hasSubscribers) {
  // There are subscribers, perform traced operation
}

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

const wc = boundedChannel('my-operation');

if (wc.hasSubscribers) {
  // There are subscribers, perform traced operation
}

boundedChannel.subscribe(handlers)

• handlers <Object> Набор подписчиков каналов
  • start <Function> Подписчик события начала
  • end <Function> Подписчик события завершения

Подписывается на события ограниченного канала. Это эквивалентно вызову channel.subscribe(onMessage) для каждого канала отдельно.

import { boundedChannel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

wc.subscribe({
  start(message) {
    // Handle start
  },
  end(message) {
    // Handle end
  },
});

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

const wc = boundedChannel('my-operation');

wc.subscribe({
  start(message) {
    // Handle start
  },
  end(message) {
    // Handle end
  },
});

boundedChannel.unsubscribe(handlers)

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

Отписывается от событий ограниченного канала. Это эквивалентно вызову channel.unsubscribe(onMessage) для каждого канала отдельно.

import { boundedChannel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

const handlers = {
  start(message) {},
  end(message) {},
};

wc.subscribe(handlers);
wc.unsubscribe(handlers);

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

const wc = boundedChannel('my-operation');

const handlers = {
  start(message) {},
  end(message) {},
};

wc.subscribe(handlers);
wc.unsubscribe(handlers);

boundedChannel.run(context, fn[, thisArg[, ...args]])

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

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

import { boundedChannel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

const result = wc.run({ operationId: '123' }, () => {
  // Perform operation
  return 42;
});

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

const wc = boundedChannel('my-operation');

const result = wc.run({ operationId: '123' }, () => {
  // Perform operation
  return 42;
});

boundedChannel.withScope([context])

• context <Object> Общий объект для сопоставления событий
• Возвращает: {BoundedChannelScope} Объект области видимости, освобождаемый при уничтожении

Создает область видимости, освобождаемую при уничтожении, для трассировки синхронной операции с использованием явного управления ресурсами в JavaScript (синтаксис using). Эта область автоматически публикует события start и end, входит в связанные хранилища и выполняет очистку при освобождении.

import { boundedChannel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

const context = { operationId: '123' };
{
  using scope = wc.withScope(context);
  // Stores are entered, start event is published

  // Perform work and set result on context
  context.result = 42;
}
// End event is published, stores are restored automatically

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

const wc = boundedChannel('my-operation');

const context = { operationId: '123' };
{
  using scope = wc.withScope(context);
  // Stores are entered, start event is published

  // Perform work and set result on context
  context.result = 42;
}
// End event is published, stores are restored automatically

Класс: BoundedChannelScope

Класс BoundedChannelScope представляет область видимости, освобождаемую при уничтожении и созданную с помощью boundedChannel.withScope(context). Он управляет жизненным циклом трассируемой операции, автоматически публикуя события и управляя контекстами хранилищ.

Для корректного освобождения область видимости необходимо использовать с синтаксисом using.

import { boundedChannel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

const context = {};
{
  using scope = wc.withScope(context);
  // Start event is published, stores are entered
  context.result = performOperation();
  // End event is automatically published at end of block
}

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

const wc = boundedChannel('my-operation');

const context = {};
{
  using scope = wc.withScope(context);
  // Start event is published, stores are entered
  context.result = performOperation();
  // End event is automatically published at end of block
}

Каналы BoundedChannel

BoundedChannel состоит из двух каналов диагностики, представляющих жизненный цикл области видимости, созданной с помощью синтаксиса using:

• tracing:${name}:start — публикуется при выполнении инструкции using (создание области видимости)
• tracing:${name}:end — публикуется при выходе из блока (освобождение области видимости)

При использовании синтаксиса using с [boundedChannel.withScope([context])][] событие start публикуется сразу после выполнения инструкции, а событие end автоматически публикуется при освобождении в конце блока. Все события имеют один и тот же объект контекста, который можно расширить дополнительными свойствами, например result, во время выполнения в области видимости.

Каналы TracingChannel

TracingChannel — это набор нескольких каналов диагностики, представляющих определенные точки жизненного цикла выполнения одного трассируемого действия. Работа распределена между пятью каналами диагностики: 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 обозначает момент, когда вызов функции возвращает значение. Для асинхронной функции это происходит при возврате промиса, а не при выполнении оператором 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: одно для синхронной ошибки, другое — для асинхронной.

Встроенные каналы

Консоль

Событие: 'console.log'

• args <any[]>

Генерируется при вызове console.log(). Получает массив аргументов, переданных в console.log().

Событие: 'console.info'

• args <any[]>

Генерируется при вызове console.info(). Получает массив аргументов, переданных в console.info().

Событие: 'console.debug'

• args <any[]>

Генерируется при вызове console.debug(). Получает массив аргументов, переданных в console.debug().

Событие: 'console.warn'

• args <any[]>

Генерируется при вызове console.warn(). Получает массив аргументов, переданных в console.warn().

Событие: 'console.error'

• args <any[]>

Генерируется при вызове console.error(). Получает массив аргументов, переданных в console.error().

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'

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

Генерируется, когда сервер получает запрос.

Событие: 'http.server.response.created'

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

Генерируется, когда сервер создает ответ. Событие генерируется до отправки ответа.

Событие: 'http.server.response.finish'

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

Генерируется, когда сервер отправляет ответ.

HTTP/2

Событие: 'http2.client.stream.created'

• stream <ClientHttp2Stream>
• headers <HTTP/2 Headers Object>

Генерируется, когда на клиенте создается поток.

Событие: 'http2.client.stream.start'

• stream <ClientHttp2Stream>
• headers <HTTP/2 Headers Object>

Генерируется, когда на клиенте запускается поток.

Событие: 'http2.client.stream.error'

• stream <ClientHttp2Stream>
• error <Error>

Генерируется при возникновении ошибки во время обработки потока на клиенте.

Событие: 'http2.client.stream.finish'

• stream <ClientHttp2Stream>
• headers <HTTP/2 Headers Object>
• flags <number>

Генерируется, когда клиент получает поток.

Событие: 'http2.client.stream.bodyChunkSent'

• stream <ClientHttp2Stream>
• writev <boolean>
• data <Buffer> | <string> | <Buffer[]> | <Object[]>
  • chunk <Buffer> | <string>
  • encoding <string>
• encoding <string>

Генерируется при отправке фрагмента тела клиентского потока.

Событие: 'http2.client.stream.bodySent'

• stream <ClientHttp2Stream>

Генерируется после полной отправки тела клиентского потока.

Событие: 'http2.client.stream.close'

• stream <ClientHttp2Stream>

Генерируется, когда поток закрывается на клиенте. Код ошибки HTTP/2, использованный при закрытии потока, можно получить с помощью свойства stream.rstCode.

Событие: 'http2.server.stream.created'

• stream <ServerHttp2Stream>
• headers <HTTP/2 Headers Object>

Генерируется, когда на сервере создается поток.

Событие: 'http2.server.stream.start'

• stream <ServerHttp2Stream>
• headers <HTTP/2 Headers Object>

Генерируется, когда на сервере запускается поток.

Событие: 'http2.server.stream.error'

• stream <ServerHttp2Stream>
• error <Error>

Генерируется при возникновении ошибки во время обработки потока на сервере.

Событие: 'http2.server.stream.finish'

• stream <ServerHttp2Stream>
• headers <HTTP/2 Headers Object>
• flags <number>

Генерируется, когда поток отправляется на сервере.

Событие: 'http2.server.stream.close'

• stream <ServerHttp2Stream>

Генерируется, когда поток закрывается на сервере. Код ошибки HTTP/2, использованный при закрытии потока, можно получить с помощью свойства stream.rstCode.

Модули

Событие: 'tracing:module.require:start'

• event <Object>, содержащий следующие свойства
  • id Аргумент, переданный в require(). Имя модуля.
  • parentFilename Имя модуля, который попытался выполнить require(id).

Генерируется при выполнении require(). См. событие start.

Событие: 'tracing:module.require:end'

• event <Object>, содержащий следующие свойства
  • id Аргумент, переданный в require(). Имя модуля.
  • parentFilename Имя модуля, который попытался выполнить require(id).

Генерируется при возврате из вызова require(). См. событие end.

Событие: 'tracing:module.require:error'

• event <Object>, содержащий следующие свойства
  • id Аргумент, переданный в require(). Имя модуля.
  • parentFilename Имя модуля, который попытался выполнить require(id).
• error <Error>

Генерируется, когда require() выбрасывает ошибку. См. событие error.

Событие: 'tracing:module.import:asyncStart'

• event <Object> со следующими свойствами
  • id Аргумент, переданный в import(). Имя модуля.
  • parentURL Объект URL модуля, который попытался выполнить импорт (id).

Вызывается при вызове import(). См. событие asyncStart.

Событие: 'tracing:module.import:asyncEnd'

• event <Object> со следующими свойствами
  • id Аргумент, переданный в import(). Имя модуля.
  • parentURL Объект URL модуля, который попытался выполнить импорт (id).

Вызывается после завершения import(). См. событие asyncEnd.

Событие: 'tracing:module.import:error'

• event <Object> со следующими свойствами
  • id Аргумент, переданный в import(). Имя модуля.
  • parentURL Объект URL модуля, который попытался выполнить импорт (id).
• error <Error>

Вызывается, когда import() выдает ошибку. См. событие error.

NET

Событие: 'net.client.socket'

• socket <net.Socket> | <tls.TLSSocket>

Вызывается при создании нового клиентского 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-сокета.

Процесс

Событие: 'child_process'

• process <ChildProcess>

Вызывается при создании нового процесса.

tracing:child_process.spawn:start

• process <ChildProcess>
• options <Object>

Вызывается при вызове child_process.spawn(), до фактического запуска процесса.

tracing:child_process.spawn:end

• process <ChildProcess>

Вызывается после успешного завершения child_process.spawn() и создания процесса.

tracing:child_process.spawn:error

• process <ChildProcess>
• error <Error>

Вызывается, если при выполнении child_process.spawn() возникает ошибка.

Событие: 'process.execve'

• execPath <string>
• args <string[]>
• env <string[]>

Вызывается при вызове process.execve().

Web Locks

Эти каналы вызываются при каждом вызове locks.request(). Подробнее о Web Locks см. в разделе worker_threads.locks.

Событие: 'locks.request.start'

• name <string> Имя запрошенного ресурса блокировки.
• mode <string> Режим блокировки: 'exclusive' или 'shared'.

Вызывается при отправке запроса на блокировку, до предоставления блокировки.

Событие: 'locks.request.grant'

• name <string> Имя запрошенного ресурса блокировки.
• mode <string> Режим блокировки: 'exclusive' или 'shared'.

Вызывается, когда блокировка успешно предоставлена и должен быть вызван callback.

Событие: 'locks.request.miss'

• name <string> Имя запрошенного ресурса блокировки.
• mode <string> Режим блокировки: 'exclusive' или 'shared'.

Вызывается, когда ifAvailable имеет значение true и блокировка недоступна немедленно; в этом случае callback запроса вызывается с null вместо объекта Lock.

Событие: 'locks.request.end'

• name <string> Имя запрошенного ресурса блокировки.
• mode <string> Режим блокировки: 'exclusive' или 'shared'.
• steal <boolean> Использует ли запрос семантику steal.
• ifAvailable <boolean> Использует ли запрос семантику ifAvailable.
• error <Error> | <undefined> Ошибка, вызванная callback, если она была.

Вызывается по завершении запроса блокировки: независимо от того, завершился ли callback успешно, вызвал ошибку или блокировка была перехвачена.

Потоки Worker

Событие: 'worker_threads'

• worker <Worker>

Вызывается при создании нового потока.