Canal de Diagnósticos

[Histórico]

Versão	Mudanças
v19.2.0, v18.13.0	diagnostics_channel agora é Estável.
v15.1.0, v14.17.0	Adicionado em: v15.1.0, v14.17.0

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

Código Fonte: lib/diagnostics_channel.js

O módulo node:diagnostics_channel fornece uma API para criar canais nomeados para relatar dados de mensagens arbitrárias para fins de diagnóstico.

Ele pode ser acessado usando:

ESM

import diagnostics_channel from 'node:diagnostics_channel';

CJS

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

É pretendido que um escritor de módulo que deseja relatar mensagens de diagnóstico crie um ou vários canais de nível superior para relatar mensagens. Canais também podem ser adquiridos em tempo de execução, mas não é encorajado devido à sobrecarga adicional de fazê-lo. Canais podem ser exportados por conveniência, mas desde que o nome seja conhecido, ele pode ser adquirido em qualquer lugar.

Se você pretende que seu módulo produza dados de diagnóstico para outros consumirem, é recomendável que você inclua documentação de quais canais nomeados são usados, juntamente com o formato dos dados da mensagem. Nomes de canal geralmente devem incluir o nome do módulo para evitar colisões com dados de outros módulos.

API Pública

Visão Geral

A seguir, uma visão geral simples da API pública.

ESM

import diagnostics_channel from 'node:diagnostics_channel';

// Obtenha um objeto de canal reutilizável
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Dados recebidos
}

// Inscreva-se no canal
diagnostics_channel.subscribe('my-channel', onMessage);

// Verifique se o canal tem um assinante ativo
if (channel.hasSubscribers) {
  // Publique dados no canal
  channel.publish({
    some: 'data',
  });
}

// Cancele a inscrição no canal
diagnostics_channel.unsubscribe('my-channel', onMessage);

CJS

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

// Obtenha um objeto de canal reutilizável
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Dados recebidos
}

// Inscreva-se no canal
diagnostics_channel.subscribe('my-channel', onMessage);

// Verifique se o canal tem um assinante ativo
if (channel.hasSubscribers) {
  // Publique dados no canal
  channel.publish({
    some: 'data',
  });
}

// Cancele a inscrição no canal
diagnostics_channel.unsubscribe('my-channel', onMessage);

diagnostics_channel.hasSubscribers(name)

Adicionado em: v15.1.0, v14.17.0

• name <string> | <symbol> O nome do canal
• Retorna: <boolean> Se houver assinantes ativos

Verifica se há assinantes ativos no canal nomeado. Isso é útil se a mensagem que você deseja enviar pode ser cara para preparar.

Esta API é opcional, mas útil ao tentar publicar mensagens de código com desempenho muito sensível.

ESM

import diagnostics_channel from 'node:diagnostics_channel';

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Há assinantes, preparar e publicar mensagem
}

CJS

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

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // Há assinantes, preparar e publicar mensagem
}

diagnostics_channel.channel(name)

Adicionado em: v15.1.0, v14.17.0

• name <string> | <symbol> O nome do canal
• Retorna: <Channel> O objeto de canal nomeado

Este é o ponto de entrada principal para quem deseja publicar em um canal nomeado. Ele produz um objeto de canal que é otimizado para reduzir a sobrecarga no momento da publicação o máximo possível.

ESM

import diagnostics_channel from 'node:diagnostics_channel';

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

CJS

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

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

diagnostics_channel.subscribe(name, onMessage)

Adicionado em: v18.7.0, v16.17.0

• name <string> | <symbol> O nome do canal
• onMessage <Function> O manipulador para receber mensagens do canal
  • message <any> Os dados da mensagem
  • name <string> | <symbol> O nome do canal

Registre um manipulador de mensagens para se inscrever neste canal. Este manipulador de mensagens será executado de forma síncrona sempre que uma mensagem for publicada no canal. Quaisquer erros lançados no manipulador de mensagens acionarão um 'uncaughtException'.

ESM

import diagnostics_channel from 'node:diagnostics_channel';

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

CJS

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

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

diagnostics_channel.unsubscribe(name, onMessage)

Adicionado em: v18.7.0, v16.17.0

• name <string> | <symbol> O nome do canal
• onMessage <Function> O manipulador inscrito anteriormente a ser removido
• Retorna: <boolean> true se o manipulador foi encontrado, false caso contrário.

Remove um manipulador de mensagens previamente registrado neste canal com diagnostics_channel.subscribe(name, onMessage).

ESM

import diagnostics_channel from 'node:diagnostics_channel';

function onMessage(message, name) {
  // Dados recebidos
}

diagnostics_channel.subscribe('my-channel', onMessage);

diagnostics_channel.unsubscribe('my-channel', onMessage);

CJS

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

function onMessage(message, name) {
  // Dados recebidos
}

diagnostics_channel.subscribe('my-channel', onMessage);

diagnostics_channel.unsubscribe('my-channel', onMessage);

diagnostics_channel.tracingChannel(nameOrChannels)

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• nameOrChannels <string> | <TracingChannel> Nome do canal ou objeto contendo todos os Canais TracingChannel
• Retorna: <TracingChannel> Coleção de canais para rastrear com

Cria um wrapper TracingChannel para os Canais TracingChannel fornecidos. Se um nome for fornecido, os canais de rastreamento correspondentes serão criados no formato tracing:${name}:${eventType}, onde eventType corresponde aos tipos de Canais TracingChannel.

ESM

import diagnostics_channel from 'node:diagnostics_channel';

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

// ou...

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

CJS

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

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

// ou...

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

Classe: Channel

Adicionado em: v15.1.0, v14.17.0

A classe Channel representa um canal nomeado individual dentro do pipeline de dados. Ela é usada para rastrear assinantes e para publicar mensagens quando há assinantes presentes. Ela existe como um objeto separado para evitar pesquisas de canal no momento da publicação, permitindo velocidades de publicação muito rápidas e permitindo uso intenso, incorrendo em um custo mínimo. Canais são criados com diagnostics_channel.channel(name), construir um canal diretamente com new Channel(name) não é suportado.

channel.hasSubscribers

Adicionado em: v15.1.0, v14.17.0

• Retorna: <boolean> Se existem assinantes ativos

Verifique se existem assinantes ativos neste canal. Isso é útil se a mensagem que você deseja enviar pode ser cara para preparar.

Esta API é opcional, mas útil ao tentar publicar mensagens de código com sensibilidade de desempenho muito alta.

ESM

import diagnostics_channel from 'node:diagnostics_channel';

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

if (channel.hasSubscribers) {
  // Existem assinantes, prepare e publique a mensagem
}

CJS

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

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

if (channel.hasSubscribers) {
  // Existem assinantes, prepare e publique a mensagem
}

channel.publish(message)

Adicionado em: v15.1.0, v14.17.0

• message <any> A mensagem a ser enviada aos assinantes do canal

Publique uma mensagem para qualquer assinante do canal. Isso acionará manipuladores de mensagens de forma síncrona, para que eles sejam executados dentro do mesmo contexto.

ESM

import diagnostics_channel from 'node:diagnostics_channel';

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

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

CJS

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

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

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

channel.subscribe(onMessage)

Adicionado em: v15.1.0, v14.17.0

Obsoleto desde: v18.7.0, v16.17.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use diagnostics_channel.subscribe(name, onMessage)

• onMessage <Function> O manipulador para receber mensagens do canal
  • message <any> Os dados da mensagem
  • name <string> | <symbol> O nome do canal

Registra um manipulador de mensagens para se inscrever neste canal. Este manipulador de mensagens será executado de forma síncrona sempre que uma mensagem for publicada no canal. Quaisquer erros lançados no manipulador de mensagens acionarão um 'uncaughtException'.

ESM

import diagnostics_channel from 'node:diagnostics_channel';

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

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

CJS

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

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

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

channel.unsubscribe(onMessage)

[Histórico]

Versão	Mudanças
v18.7.0, v16.17.0	Obsoleto desde: v18.7.0, v16.17.0
v17.1.0, v16.14.0, v14.19.0	Valor de retorno adicionado. Adicionado a canais sem inscritos.
v15.1.0, v14.17.0	Adicionado em: v15.1.0, v14.17.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use diagnostics_channel.unsubscribe(name, onMessage)

• onMessage <Function> O manipulador inscrito anterior para remover
• Retorna: <boolean> true se o manipulador foi encontrado, false caso contrário.

Remove um manipulador de mensagens previamente registrado neste canal com channel.subscribe(onMessage).

ESM

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

CJS

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

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• store <AsyncLocalStorage> O armazenamento ao qual vincular os dados de contexto
• transform <Function> Transforma dados de contexto antes de definir o contexto de armazenamento

Quando channel.runStores(context, ...) é chamado, os dados de contexto fornecidos serão aplicados a qualquer armazenamento vinculado ao canal. Se o armazenamento já tiver sido vinculado, a função transform anterior será substituída pela nova. A função transform pode ser omitida para definir os dados de contexto fornecidos como o contexto diretamente.

ESM

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

CJS

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)

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• store <AsyncLocalStorage> O armazenamento a ser desvinculado do canal.
• Retorna: <boolean> true se o armazenamento foi encontrado, false caso contrário.

Remove um manipulador de mensagens previamente registrado neste canal com channel.bindStore(store).

ESM

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

CJS

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

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• context <any> Mensagem para enviar aos assinantes e vincular aos armazenamentos
• fn <Function> Manipulador para executar dentro do contexto de armazenamento inserido
• thisArg <any> O receptor a ser usado para a chamada de função.
• ...args <any> Argumentos opcionais para passar para a função.

Aplica os dados fornecidos a quaisquer instâncias AsyncLocalStorage vinculadas ao canal durante a duração da função fornecida e, em seguida, publica no canal dentro do escopo em que esses dados são aplicados aos armazenamentos.

Se uma função de transformação foi dada para channel.bindStore(store), ela será aplicada para transformar os dados da mensagem antes que se torne o valor de contexto para o armazenamento. O contexto de armazenamento anterior é acessível de dentro da função de transformação nos casos em que a vinculação de contexto é necessária.

O contexto aplicado ao armazenamento deve estar acessível em qualquer código assíncrono que continue a partir da execução que começou durante a função fornecida, no entanto, existem algumas situações em que perda de contexto pode ocorrer.

ESM

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

CJS

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

Classe: TracingChannel

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

A classe TracingChannel é uma coleção de Canais TracingChannel que, juntos, expressam uma única ação rastreável. É usada para formalizar e simplificar o processo de produção de eventos para rastrear o fluxo do aplicativo. diagnostics_channel.tracingChannel() é usado para construir um TracingChannel. Assim como com Channel, é recomendado criar e reutilizar um único TracingChannel no nível superior do arquivo, em vez de criá-los dinamicamente.

tracingChannel.subscribe(subscribers)

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• subscribers <Objeto> Conjunto de assinantes de Canais TracingChannel
  • start <Função> O assinante do start event
  • end <Função> O assinante do end event
  • asyncStart <Função> O assinante do asyncStart event
  • asyncEnd <Função> O assinante do asyncEnd event
  • error <Função> O assinante do error event

Auxiliar para inscrever uma coleção de funções nos canais correspondentes. Isso é o mesmo que chamar channel.subscribe(onMessage) em cada canal individualmente.

ESM

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

CJS

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)

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• subscribers <Object> Conjunto de assinantes de Canais TracingChannel

  • start <Function> O assinante do evento start
  • end <Function> O assinante do evento end
  • asyncStart <Function> O assinante do evento asyncStart
  • asyncEnd <Function> O assinante do evento asyncEnd
  • error <Function> O assinante do evento error

• Retorna: <boolean> true se todos os manipuladores foram desinscritos com sucesso e false caso contrário.

Auxiliar para cancelar a inscrição de uma coleção de funções dos canais correspondentes. Isso é o mesmo que chamar channel.unsubscribe(onMessage) em cada canal individualmente.

ESM

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

CJS

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

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• fn <Function> Função para envolver um rastreamento
• context <Object> Objeto compartilhado para correlacionar eventos
• thisArg <any> O receptor a ser usado para a chamada de função
• ...args <any> Argumentos opcionais para passar para a função
• Retorna: <any> O valor de retorno da função fornecida

Rastreie uma chamada de função síncrona. Isso sempre produzirá um evento start event e end event em torno da execução e pode produzir um error event se a função fornecida lançar um erro. Isso executará a função fornecida usando channel.runStores(context, ...) no canal start, o que garante que todos os eventos devem ter quaisquer armazenamentos vinculados definidos para corresponder a este contexto de rastreamento.

Para garantir que apenas gráficos de rastreamento corretos sejam formados, os eventos só serão publicados se houver assinantes presentes antes de iniciar o rastreamento. Assinaturas que são adicionadas após o início do rastreamento não receberão eventos futuros desse rastreamento, apenas rastreamentos futuros serão vistos.

ESM

import diagnostics_channel from 'node:diagnostics_channel';

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

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

CJS

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

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• fn <Function> Função que retorna uma Promise para envolver um rastreamento
• context <Object> Objeto compartilhado para correlacionar eventos de rastreamento
• thisArg <any> O receptor a ser usado para a chamada da função
• ...args <any> Argumentos opcionais para passar para a função
• Retorna: <Promise> Encadeada da promise retornada pela função fornecida

Rastreia uma chamada de função que retorna uma promise. Isso sempre produzirá um evento start event e um evento end event em torno da porção síncrona da execução da função e produzirá um evento asyncStart event e um evento asyncEnd event quando uma continuação da promise for alcançada. Também pode produzir um evento error event se a função fornecida lançar um erro ou se a promise retornada for rejeitada. Isso executará a função fornecida usando channel.runStores(context, ...) no canal start, o que garante que todos os eventos tenham todos os armazenamentos vinculados definidos para corresponder a este contexto de rastreamento.

Para garantir que apenas gráficos de rastreamento corretos sejam formados, os eventos só serão publicados se os assinantes estiverem presentes antes de iniciar o rastreamento. As assinaturas que são adicionadas depois que o rastreamento começa não receberão eventos futuros desse rastreamento, apenas rastreamentos futuros serão vistos.

ESM

import diagnostics_channel from 'node:diagnostics_channel';

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

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

CJS

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

Adicionado em: v19.9.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• fn <Function> callback usando função para envolver um trace
• position <number> Posição do argumento indexado em zero do callback esperado (o padrão é o último argumento se undefined for passado)
• context <Object> Objeto compartilhado para correlacionar eventos de trace (o padrão é {} se undefined for passado)
• thisArg <any> O receptor a ser usado para a chamada de função
• ...args <any> argumentos para passar para a função (deve incluir o callback)
• Retorna: <any> O valor de retorno da função fornecida

Trace uma chamada de função que recebe callback. Espera-se que o callback siga a convenção de erro como o primeiro argumento normalmente usado. Isso sempre produzirá um evento start event e end event em torno da porção síncrona da execução da função e produzirá um evento asyncStart event e asyncEnd event em torno da execução do callback. Também pode produzir um evento error event se a função fornecida lançar ou o primeiro argumento passado para o callback for definido. Isso executará a função fornecida usando channel.runStores(context, ...) no canal start, o que garante que todos os eventos devem ter todos os stores vinculados definidos para corresponder a este contexto de trace.

Para garantir que apenas gráficos de trace corretos sejam formados, os eventos só serão publicados se os assinantes estiverem presentes antes de iniciar o trace. As assinaturas adicionadas após o início do trace não receberão eventos futuros desse trace, apenas traces futuros serão vistos.

ESM

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

CJS

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

O callback também será executado com channel.runStores(context, ...), o que permite a recuperação da perda de contexto em alguns casos.

ESM

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

CJS

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

Adicionado em: v22.0.0, v20.13.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• Retorna: <boolean> true se algum dos canais individuais tiver um subscritor, false caso contrário.

Este é um método auxiliar disponível em uma instância de TracingChannel para verificar se algum dos Canais TracingChannel possui subscritores. Um valor true é retornado se algum deles tiver pelo menos um subscritor, um valor false é retornado caso contrário.

ESM

import diagnostics_channel from 'node:diagnostics_channel';

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

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

CJS

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

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

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

Canais TracingChannel

Um TracingChannel é uma coleção de vários diagnostics_channels representando pontos específicos no ciclo de vida de execução de uma única ação rastreável. O comportamento é dividido em cinco diagnostics_channels consistindo em start, end, asyncStart, asyncEnd e error. Uma única ação rastreável compartilhará o mesmo objeto de evento entre todos os eventos, o que pode ser útil para gerenciar a correlação por meio de um weakmap.

Esses objetos de evento serão estendidos com valores result ou error quando a tarefa "concluir". No caso de uma tarefa síncrona, o result será o valor de retorno e o error será qualquer coisa lançada da função. Com funções assíncronas baseadas em callback, o result será o segundo argumento do callback, enquanto o error será um erro lançado visível no evento end ou o primeiro argumento do callback em qualquer um dos eventos asyncStart ou asyncEnd.

Para garantir que apenas gráficos de rastreamento corretos sejam formados, os eventos devem ser publicados apenas se os subscritores estiverem presentes antes de iniciar o rastreamento. Assinaturas que são adicionadas após o início do rastreamento não devem receber eventos futuros desse rastreamento, apenas rastreamentos futuros serão vistos.

Os canais de rastreamento devem seguir um padrão de nomenclatura de:

• tracing:module.class.method:start ou tracing:module.function:start
• tracing:module.class.method:end ou tracing:module.function:end
• tracing:module.class.method:asyncStart ou tracing:module.function:asyncStart
• tracing:module.class.method:asyncEnd ou tracing:module.function:asyncEnd
• tracing:module.class.method:error ou tracing:module.function:error

start(event)

• Nome: tracing:${name}:start

O evento start representa o ponto em que uma função é chamada. Neste ponto, os dados do evento podem conter argumentos de função ou qualquer outra coisa disponível no início da execução da função.

end(event)

• Nome: tracing:${name}:end

O evento end representa o ponto em que uma chamada de função retorna um valor. No caso de uma função assíncrona, isso ocorre quando a promessa é retornada, não quando a própria função faz uma declaração de retorno internamente. Neste ponto, se a função rastreada for síncrona, o campo result será definido com o valor de retorno da função. Alternativamente, o campo error pode estar presente para representar quaisquer erros lançados.

É recomendável ouvir especificamente o evento error para rastrear erros, pois pode ser possível que uma ação rastreável produza vários erros. Por exemplo, uma tarefa assíncrona que falha pode ser iniciada internamente antes da parte síncrona da tarefa e, em seguida, lança um erro.

asyncStart(event)

• Nome: tracing:${name}:asyncStart

O evento asyncStart representa o retorno de chamada ou a continuação de uma função rastreável sendo alcançada. Neste ponto, coisas como argumentos de retorno de chamada podem estar disponíveis, ou qualquer outra coisa que expresse o "resultado" da ação.

Para funções baseadas em retornos de chamada, o primeiro argumento do retorno de chamada será atribuído ao campo error, se não for undefined ou null, e o segundo argumento será atribuído ao campo result.

Para promessas, o argumento para o caminho resolve será atribuído a result ou o argumento para o caminho reject será atribuído a error.

É recomendável ouvir especificamente o evento error para rastrear erros, pois pode ser possível que uma ação rastreável produza vários erros. Por exemplo, uma tarefa assíncrona que falha pode ser iniciada internamente antes da parte síncrona da tarefa e, em seguida, lança um erro.

asyncEnd(event)

• Nome: tracing:${name}:asyncEnd

O evento asyncEnd representa o retorno de chamada de uma função assíncrona retornando. Não é provável que os dados do evento mudem após o evento asyncStart, no entanto, pode ser útil ver o ponto em que o retorno de chamada é concluído.

error(event)

• Nome: tracing:${name}:error

O evento error representa qualquer erro produzido pela função rastreável, seja síncrona ou assincronamente. Se um erro for lançado na porção síncrona da função rastreada, o erro será atribuído ao campo error do evento e o evento error será acionado. Se um erro for recebido assincronamente através de um callback ou rejeição de promessa, ele também será atribuído ao campo error do evento e acionará o evento error.

É possível que uma única chamada de função rastreável produza erros várias vezes, portanto, isso deve ser considerado ao consumir este evento. Por exemplo, se outra tarefa assíncrona for acionada internamente, falhar e, em seguida, a parte síncrona da função lançar um erro, dois eventos error serão emitidos, um para o erro síncrono e outro para o erro assíncrono.

Canais Integrados

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Embora a API diagnostics_channel seja agora considerada estável, os canais integrados atualmente disponíveis não são. Cada canal deve ser declarado estável independentemente.

HTTP

http.client.request.created

• request <http.ClientRequest>

Emitido quando o cliente cria um objeto de requisição. Ao contrário de http.client.request.start, este evento é emitido antes que a requisição seja enviada.

http.client.request.start

• request <http.ClientRequest>

Emitido quando o cliente inicia uma requisição.

http.client.request.error

• request <http.ClientRequest>
• error <Error>

Emitido quando ocorre um erro durante uma requisição do cliente.

http.client.response.finish

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

Emitido quando o cliente recebe uma resposta.

http.server.request.start

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

Emitido quando o servidor recebe uma requisição.

http.server.response.created

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

Emitido quando o servidor cria uma resposta. O evento é emitido antes que a resposta seja enviada.

http.server.response.finish

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

Emitido quando o servidor envia uma resposta.

Módulos

module.require.start

• event <Object> contendo as seguintes propriedades
  • id - Argumento passado para require(). Nome do módulo.
  • parentFilename - Nome do módulo que tentou require(id).

Emitido quando require() é executado. Veja o evento start.

module.require.end

• event <Object> contendo as seguintes propriedades
  • id - Argumento passado para require(). Nome do módulo.
  • parentFilename - Nome do módulo que tentou require(id).

Emitido quando uma chamada a require() retorna. Veja o evento end.

module.require.error

• event <Object> contendo as seguintes propriedades

  • id - Argumento passado para require(). Nome do módulo.
  • parentFilename - Nome do módulo que tentou require(id).

• error <Error>

Emitido quando um require() lança um erro. Veja o evento error.

module.import.asyncStart

• event <Object> contendo as seguintes propriedades
  • id - Argumento passado para import(). Nome do módulo.
  • parentURL - Objeto URL do módulo que tentou import(id).

Emitido quando import() é invocado. Veja o evento asyncStart.

module.import.asyncEnd

• event <Object> contendo as seguintes propriedades
  • id - Argumento passado para import(). Nome do módulo.
  • parentURL - Objeto URL do módulo que tentou import(id).

Emitido quando import() é concluído. Veja o evento asyncEnd.

module.import.error

• event <Object> contendo as seguintes propriedades

  • id - Argumento passado para import(). Nome do módulo.
  • parentURL - Objeto URL do módulo que tentou import(id).

• error <Error>

Emitido quando um import() lança um erro. Veja o evento error.

NET

net.client.socket

• socket <net.Socket>

Emitido quando um novo socket de cliente TCP ou pipe é criado.

net.server.socket

• socket <net.Socket>

Emitido quando uma nova conexão TCP ou pipe é recebida.

tracing:net.server.listen:asyncStart

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

Emitido quando net.Server.listen() é invocado, antes da porta ou pipe ser realmente configurado.

tracing:net.server.listen:asyncEnd

• server <net.Server>

Emitido quando net.Server.listen() é concluído e, portanto, o servidor está pronto para aceitar conexões.

tracing:net.server.listen:error

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

Emitido quando net.Server.listen() está retornando um erro.

UDP

udp.socket

• socket <dgram.Socket>

Emitido quando um novo socket UDP é criado.

Process

Adicionado em: v16.18.0

child_process

• process <ChildProcess>

Emitido quando um novo processo é criado.

Worker Thread

Adicionado em: v16.18.0

worker_threads

• worker Worker

Emitido quando uma nova thread é criada.