Публичный 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'),
});

Класс: 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' })
});

Класс: 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> Функция, возвращающая 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
}

Каналы 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: одно для синхронной ошибки, другое — для асинхронной.

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

Хотя API diagnostics_channel теперь считается стабильным, доступные в данный момент встроенные каналы таковыми не являются. Стабильность каждого канала должна быть объявлена отдельно.

HTTP

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

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

Отправляется, когда сервер отправляет ответ.

СЕТЬ

net.client.socket

• socket <net.Socket>

Отправляется при создании нового клиентского сокета TCP или канала.

net.server.socket

• socket <net.Socket>

Отправляется при получении нового подключения TCP или через канал.

tracing:net.server.listen:asyncStart

• server <net.Server>
• options <Object>

Отправляется при вызове net.Server.listen() до фактической настройки порта или канала.

tracing:net.server.listen:asyncEnd

• server <net.Server>

Отправляется после завершения net.Server.listen(), когда сервер готов принимать подключения.

tracing:net.server.listen:error

• server <net.Server>
• error <Error>

Отправляется, когда вызов net.Server.listen() завершается ошибкой.

UDP

udp.socket

• socket <dgram.Socket>

Отправляется при создании нового сокета UDP.

Процесс

child_process

• process <ChildProcess>

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

Рабочий поток

worker_threads

• worker Worker

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