diagnostics_channel

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

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

import diagnostics_channel from 'node:diagnostics_channel';

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

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

Использование в Deno

import * as mod from "node:diagnostics_channel";

класс Channel

Использование в Deno

import { Channel } from "node:diagnostics_channel";

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

Конструкторы

Channel(name: string | symbol)

новый

Параметры типа

StoreType = unknown

ContextType = StoreType

Свойства

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
}

name: string | symbol

только для чтения

Методы

bindStore(

store: AsyncLocalStorage<StoreType>,

transform?: (context: ContextType) => StoreType,
): void

При вызове 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 };
});

publish(message: unknown): void

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

import diagnostics_channel from 'node:diagnostics_channel';

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

channel.publish({
  some: 'message',
});

runStores(): void

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

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

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

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

subscribe(onMessage: ChannelListener): void

устарело

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

import diagnostics_channel from 'node:diagnostics_channel';

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

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

unbindStore(store: any): void

Удаляет обработчик сообщений, ранее зарегистрированный для этого канала с помощью 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);

unsubscribe(onMessage: ChannelListener): void

устарело

Удаляет обработчик сообщений, ранее зарегистрированный для этого канала с помощью 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);

класс TracingChannel

реализует TracingChannelCollection

нестабильный

Использование в Deno

import { TracingChannel } from "node:diagnostics_channel";

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

Параметры типа

StoreType = unknown

ContextType extends object = { }

Свойства

asyncEnd: Channel<StoreType, ContextType>

asyncStart: Channel<StoreType, ContextType>

end: Channel<StoreType, ContextType>

error: Channel<StoreType, ContextType>

start: Channel<StoreType, ContextType>

Методы

subscribe(subscribers: TracingChannelSubscribers<ContextType>): void

Вспомогательный метод для подписки набора функций на соответствующие каналы. Он эквивалентен отдельному вызову 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
  },
});

traceCallback<Fn extends (

this: any,

...args: any[],
) => any>(

fn: Fn,

position?: number,

context?: ContextType,

thisArg?: any,

...args: Parameters<Fn>,
): void

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

По умолчанию значение position равно -1, что указывает на использование последнего аргумента в качестве обратного вызова.

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

Обратный вызов также будет выполняться с помощью 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;
});

tracePromise<

ThisArg = any,

Args extends any[] = any[],
>(

fn: (

this: ThisArg,

...args: Args,
) => Promise<any>,

context?: ContextType,

thisArg?: ThisArg,

...args: Args,
): void

Отслеживает вызов функции, возвращающей промис. Вокруг синхронной части выполнения функции всегда создаются start event и end event, а когда доходит очередь до продолжения промиса — asyncStart event и asyncEnd event. Также может создаваться error event, если указанная функция выбрасывает ошибку или возвращённый промис отклоняется. Указанная функция выполняется с помощью 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',
});

traceSync<

ThisArg = any,

Args extends any[] = any[],
>(

fn: (

this: ThisArg,

...args: Args,
) => any,

context?: ContextType,

thisArg?: ThisArg,

...args: Args,
): void

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

import diagnostics_channel from 'node:diagnostics_channel';

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

channels.traceSync(() => {
  // Do something
}, {
  some: 'thing',
});

unsubscribe(subscribers: TracingChannelSubscribers<ContextType>): void

Вспомогательный метод для отмены подписки набора функций на соответствующие каналы. Он эквивалентен отдельному вызову 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
  },
});

функция channel

Использование в Deno

import { channel } from "node:diagnostics_channel";

channel(name: string | symbol): Channel

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

import diagnostics_channel from 'node:diagnostics_channel';

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

Параметры

name: string | symbol

Имя канала

Возвращаемый тип

Channel

Объект именованного канала

функция hasSubscribers

Использование в Deno

import { hasSubscribers } from "node:diagnostics_channel";

hasSubscribers(name: string | symbol): boolean

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

import diagnostics_channel from 'node:diagnostics_channel';

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

Параметры

name: string | symbol

Имя канала

Возвращаемый тип

boolean

Наличие активных подписчиков

функция subscribe

Использование в Deno

import { subscribe } from "node:diagnostics_channel";

subscribe(

name: string | symbol,

onMessage: ChannelListener,
): void

import diagnostics_channel from 'node:diagnostics_channel';

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

функция tracingChannel

нестабильный

Использование в Deno

import { tracingChannel } from "node:diagnostics_channel";

tracingChannel<

StoreType = unknown,

ContextType extends object = StoreType extends object ? StoreType : object,
>(nameOrChannels: string | TracingChannelCollection<StoreType, ContextType>): TracingChannel<StoreType, ContextType>

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

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

Параметры типа

StoreType = unknown

ContextType extends object = StoreType extends object ? StoreType : object

Параметры

nameOrChannels: string | TracingChannelCollection<StoreType, ContextType>

Имя канала или объект, содержащий все TracingChannel Channels

Возвращаемый тип

TracingChannel<StoreType, ContextType>

Набор каналов для трассировки

функция unsubscribe

Использование в Deno

import { unsubscribe } from "node:diagnostics_channel";

unsubscribe(

name: string | symbol,

onMessage: ChannelListener,
): boolean

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

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

Параметры

name: string | symbol

Имя канала

onMessage: ChannelListener

Предыдущий обработчик подписки, который нужно удалить

Возвращаемый тип

boolean

true, если обработчик найден, иначе false.

интерфейс TracingChannelCollection

Использование в Deno

import { type TracingChannelCollection } from "node:diagnostics_channel";

Параметры типа

StoreType = unknown

ContextType = StoreType

Свойства

start: Channel<StoreType, ContextType>

end: Channel<StoreType, ContextType>

asyncStart: Channel<StoreType, ContextType>

asyncEnd: Channel<StoreType, ContextType>

error: Channel<StoreType, ContextType>

интерфейс TracingChannelSubscribers

Использование в Deno

import { type TracingChannelSubscribers } from "node:diagnostics_channel";

Параметры типа

ContextType extends object

Свойства

start: (message: ContextType) => void

end: (message: ContextType & { error?: unknown; result?: unknown; }) => void

asyncStart: (message: ContextType & { error?: unknown; result?: unknown; }) => void

asyncEnd: (message: ContextType & { error?: unknown; result?: unknown; }) => void

error: (message: ContextType & { error: unknown; }) => void

псевдоним типа ChannelListener

Использование в Deno

import { type ChannelListener } from "node:diagnostics_channel";

Определение

(

message: unknown,

name: string | symbol,
) => void