APIs de medição de desempenho

[Estável: 2 - Estável]

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

Código Fonte: lib/perf_hooks.js

Este módulo fornece uma implementação de um subconjunto das APIs de Desempenho Web do W3C, bem como APIs adicionais para medições de desempenho específicas do Node.js.

O Node.js suporta as seguintes APIs de Desempenho Web:

• Tempo de Alta Resolução
• Linha do Tempo de Desempenho
• Tempo do Usuário
• Tempo de Recursos

ESM

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((items) => {
  console.log(items.getEntries()[0].duration);
  performance.clearMarks();
});
obs.observe({ type: 'measure' });
performance.measure('Start to Now');

performance.mark('A');
doSomeLongRunningProcess(() => {
  performance.measure('A to Now', 'A');

  performance.mark('B');
  performance.measure('A to B', 'A', 'B');
});

CJS

const { PerformanceObserver, performance } = require('node:perf_hooks');

const obs = new PerformanceObserver((items) => {
  console.log(items.getEntries()[0].duration);
});
obs.observe({ type: 'measure' });
performance.measure('Start to Now');

performance.mark('A');
(async function doSomeLongRunningProcess() {
  await new Promise((r) => setTimeout(r, 5000));
  performance.measure('A to Now', 'A');

  performance.mark('B');
  performance.measure('A to B', 'A', 'B');
})();

perf_hooks.performance

Adicionado em: v8.5.0

Um objeto que pode ser usado para coletar métricas de desempenho da instância atual do Node.js. É semelhante a window.performance nos navegadores.

performance.clearMarks([name])

[Histórico]

Versão	Alterações
v19.0.0	Este método deve ser chamado com o objeto performance como receptor.
v8.5.0	Adicionado em: v8.5.0

• name <string>

Se name não for fornecido, remove todos os objetos PerformanceMark da Linha do Tempo de Desempenho. Se name for fornecido, remove apenas a marca nomeada.

performance.clearMeasures([name])

[Histórico]

Versão	Alterações
v19.0.0	Este método deve ser chamado com o objeto performance como receptor.
v16.7.0	Adicionado em: v16.7.0

• name <string>

Se name não for fornecido, remove todos os objetos PerformanceMeasure da Linha do Tempo de Desempenho. Se name for fornecido, remove apenas a medida nomeada.

performance.clearResourceTimings([name])

[Histórico]

Versão	Alterações
v19.0.0	Este método deve ser chamado com o objeto performance como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• name <string>

Se name não for fornecido, remove todos os objetos PerformanceResourceTiming da Linha do Tempo de Recursos. Se name for fornecido, remove apenas o recurso nomeado.

performance.eventLoopUtilization([utilization1[, utilization2]])

Adicionado em: v14.10.0, v12.19.0

• utilization1 <Object> O resultado de uma chamada anterior para eventLoopUtilization().
• utilization2 <Object> O resultado de uma chamada anterior para eventLoopUtilization() anterior a utilization1.
• Retorna: <Object>
  • idle <number>
  • active <number>
  • utilization <number>

O método eventLoopUtilization() retorna um objeto que contém a duração cumulativa do tempo em que o loop de eventos ficou ocioso e ativo como um temporizador de alta resolução em milissegundos. O valor de utilization é a Utilização do Loop de Eventos (ELU) calculada.

Se o bootstrapping ainda não tiver terminado na thread principal, as propriedades terão o valor de 0. O ELU está imediatamente disponível em threads Worker, pois o bootstrap acontece dentro do loop de eventos.

Ambos utilization1 e utilization2 são parâmetros opcionais.

Se utilization1 for passado, então o delta entre os tempos active e idle da chamada atual, bem como o valor utilization correspondente, são calculados e retornados (semelhante a process.hrtime()).

Se utilization1 e utilization2 forem ambos passados, então o delta é calculado entre os dois argumentos. Esta é uma opção de conveniência porque, ao contrário de process.hrtime(), calcular o ELU é mais complexo do que uma única subtração.

O ELU é semelhante à utilização da CPU, exceto que mede apenas as estatísticas do loop de eventos e não o uso da CPU. Representa a percentagem de tempo que o loop de eventos passou fora do fornecedor de eventos do loop de eventos (por exemplo, epoll_wait). Nenhum outro tempo ocioso da CPU é levado em consideração. O seguinte é um exemplo de como um processo maioritariamente ocioso terá um ELU alto.

ESM

import { eventLoopUtilization } from 'node:perf_hooks';
import { spawnSync } from 'node:child_process';

setImmediate(() => {
  const elu = eventLoopUtilization();
  spawnSync('sleep', ['5']);
  console.log(eventLoopUtilization(elu).utilization);
});

CJS

'use strict';
const { eventLoopUtilization } = require('node:perf_hooks').performance;
const { spawnSync } = require('node:child_process';

setImmediate(() => {
  const elu = eventLoopUtilization();
  spawnSync('sleep', ['5']);
  console.log(eventLoopUtilization(elu).utilization);
});

Embora a CPU esteja maioritariamente ociosa ao executar este script, o valor de utilization é 1. Isto porque a chamada para child_process.spawnSync() impede o loop de eventos de prosseguir.

Passar um objeto definido pelo utilizador em vez do resultado de uma chamada anterior para eventLoopUtilization() levará a um comportamento indefinido. Não é garantido que os valores de retorno reflitam qualquer estado correto do loop de eventos.

performance.getEntries()

[Histórico]

Versão	Alterações
v19.0.0	Este método deve ser chamado com o objeto performance como receptor.
v16.7.0	Adicionado em: v16.7.0

• Retorna: <PerformanceEntry[]>

Retorna uma lista de objetos PerformanceEntry em ordem cronológica em relação a performanceEntry.startTime. Se você estiver interessado apenas em entradas de desempenho de certos tipos ou que tenham certos nomes, consulte performance.getEntriesByType() e performance.getEntriesByName().

performance.getEntriesByName(name[, type])

[Histórico]

Versão	Alterações
v19.0.0	Este método deve ser chamado com o objeto performance como receptor.
v16.7.0	Adicionado em: v16.7.0

• name <string>
• type <string>
• Retorna: <PerformanceEntry[]>

Retorna uma lista de objetos PerformanceEntry em ordem cronológica em relação a performanceEntry.startTime cujo performanceEntry.name é igual a name e, opcionalmente, cujo performanceEntry.entryType é igual a type.

performance.getEntriesByType(type)

[Histórico]

Versão	Alterações
v19.0.0	Este método deve ser chamado com o objeto performance como receptor.
v16.7.0	Adicionado em: v16.7.0

• type <string>
• Retorna: <PerformanceEntry[]>

Retorna uma lista de objetos PerformanceEntry em ordem cronológica em relação a performanceEntry.startTime cujo performanceEntry.entryType é igual a type.

performance.mark(name[, options])

[Histórico]

Versão	Alterações
v19.0.0	Este método deve ser chamado com o objeto performance como receptor. O argumento name não é mais opcional.
v16.0.0	Atualizado para estar em conformidade com a especificação User Timing Level 3.
v8.5.0	Adicionado em: v8.5.0

• name <string>
• options <Object>
  • detail <any> Detalhes opcionais adicionais para incluir com a marcação.
  • startTime <number> Um timestamp opcional a ser usado como o tempo da marcação. Padrão: performance.now().

Cria uma nova entrada PerformanceMark na Linha do Tempo de Desempenho. Um PerformanceMark é uma subclasse de PerformanceEntry cujo performanceEntry.entryType é sempre 'mark' e cujo performanceEntry.duration é sempre 0. As marcas de desempenho são usadas para marcar momentos significativos específicos na Linha do Tempo de Desempenho.

A entrada PerformanceMark criada é colocada na Linha do Tempo de Desempenho global e pode ser consultada com performance.getEntries, performance.getEntriesByName e performance.getEntriesByType. Quando a observação é realizada, as entradas devem ser limpas da Linha do Tempo de Desempenho global manualmente com performance.clearMarks.

performance.markResourceTiming(timingInfo, requestedUrl, initiatorType, global, cacheMode, bodyInfo, responseStatus[, deliveryType])

[Histórico]

Versão	Mudanças
v22.2.0	Adicionados os argumentos bodyInfo, responseStatus e deliveryType.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• timingInfo <Object> Informações de Tempo de Busca
• requestedUrl <string> A URL do recurso
• initiatorType <string> O nome do iniciador, por exemplo: 'fetch'
• global <Object>
• cacheMode <string> O modo de cache deve ser uma string vazia ('') ou 'local'
• bodyInfo <Object> Informações do Corpo da Resposta da Busca
• responseStatus <number> O código de status da resposta
• deliveryType <string> O tipo de entrega. Padrão: ''.

Esta propriedade é uma extensão do Node.js. Não está disponível em navegadores Web.

Cria uma nova entrada PerformanceResourceTiming na Linha do Tempo de Recursos. PerformanceResourceTiming é uma subclasse de PerformanceEntry cujo performanceEntry.entryType é sempre 'resource'. Os recursos de desempenho são usados para marcar momentos na Linha do Tempo de Recursos.

A entrada PerformanceMark criada é colocada na Linha do Tempo de Recursos global e pode ser consultada com performance.getEntries, performance.getEntriesByName e performance.getEntriesByType. Quando a observação é realizada, as entradas devem ser removidas manualmente da Linha do Tempo de Desempenho global com performance.clearResourceTimings.

performance.measure(name[, startMarkOrOptions[, endMark]])

[Histórico]

Versão	Mudanças
v19.0.0	Este método deve ser chamado com o objeto performance como receptor.
v16.0.0	Atualizado para estar em conformidade com a especificação User Timing Level 3.
v13.13.0, v12.16.3	Torna os parâmetros startMark e endMark opcionais.
v8.5.0	Adicionado em: v8.5.0

• name <string>

• startMarkOrOptions <string> | <Object> Opcional.

  • detail <any> Detalhe opcional adicional para incluir com a medida.
  • duration <number> Duração entre os horários de início e fim.
  • end <number> | <string> Timestamp a ser usado como o horário de término, ou uma string identificando uma marca previamente registrada.
  • start <number> | <string> Timestamp a ser usado como o horário de início, ou uma string identificando uma marca previamente registrada.

• endMark <string> Opcional. Deve ser omitido se startMarkOrOptions for um <Object>.

Cria uma nova entrada PerformanceMeasure na Linha do Tempo de Desempenho. Um PerformanceMeasure é uma subclasse de PerformanceEntry cujo performanceEntry.entryType é sempre 'measure', e cujo performanceEntry.duration mede o número de milissegundos decorridos desde startMark e endMark.

O argumento startMark pode identificar qualquer PerformanceMark existente na Linha do Tempo de Desempenho, ou pode identificar qualquer uma das propriedades de timestamp fornecidas pela classe PerformanceNodeTiming. Se o startMark nomeado não existir, um erro é lançado.

O argumento opcional endMark deve identificar qualquer PerformanceMark existente na Linha do Tempo de Desempenho ou qualquer uma das propriedades de timestamp fornecidas pela classe PerformanceNodeTiming. endMark será performance.now() se nenhum parâmetro for passado, caso contrário, se o endMark nomeado não existir, um erro será lançado.

A entrada PerformanceMeasure criada é colocada na Linha do Tempo de Desempenho global e pode ser consultada com performance.getEntries, performance.getEntriesByName e performance.getEntriesByType. Quando a observação é realizada, as entradas devem ser limpas da Linha do Tempo de Desempenho global manualmente com performance.clearMeasures.

performance.nodeTiming

Adicionado em: v8.5.0

• <PerformanceNodeTiming>

Esta propriedade é uma extensão do Node.js. Não está disponível em navegadores Web.

Uma instância da classe PerformanceNodeTiming que fornece métricas de desempenho para marcos operacionais específicos do Node.js.

performance.now()

[Histórico]

Versão	Mudanças
v19.0.0	Este método deve ser chamado com o objeto performance como receptor.
v8.5.0	Adicionado em: v8.5.0

• Retorna: <number>

Retorna o timestamp atual de alta resolução em milissegundos, onde 0 representa o início do processo node atual.

performance.setResourceTimingBufferSize(maxSize)

[Histórico]

Versão	Mudanças
v19.0.0	Este método deve ser chamado com o objeto performance como receptor.
v18.8.0	Adicionado em: v18.8.0

Define o tamanho global do buffer de tempo de recurso de desempenho para o número especificado de objetos de entrada de desempenho do tipo "recurso".

Por padrão, o tamanho máximo do buffer é definido como 250.

performance.timeOrigin

Adicionado em: v8.5.0

• <number>

O timeOrigin especifica o timestamp de alta resolução em milissegundos em que o processo node atual começou, medido no tempo Unix.

performance.timerify(fn[, options])

[Histórico]

Versão	Mudanças
v16.0.0	Adicionada a opção de histograma.
v16.0.0	Re-implementado para usar JavaScript puro e a capacidade de cronometrar funções assíncronas.
v8.5.0	Adicionado em: v8.5.0

• fn <Function>
• options <Object>
  • histogram <RecordableHistogram> Um objeto histograma criado usando perf_hooks.createHistogram() que registrará durações de tempo de execução em nanossegundos.

Esta propriedade é uma extensão do Node.js. Não está disponível em navegadores Web.

Envolve uma função dentro de uma nova função que mede o tempo de execução da função envolvida. Um PerformanceObserver deve ser inscrito no tipo de evento 'function' para que os detalhes de tempo possam ser acessados.

ESM

import { performance, PerformanceObserver } from 'node:perf_hooks';

function someFunction() {
  console.log('hello world');
}

const wrapped = performance.timerify(someFunction);

const obs = new PerformanceObserver((list) => {
  console.log(list.getEntries()[0].duration);

  performance.clearMarks();
  performance.clearMeasures();
  obs.disconnect();
});
obs.observe({ entryTypes: ['function'] });

// A performance timeline entry will be created
wrapped();

CJS

const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

function someFunction() {
  console.log('hello world');
}

const wrapped = performance.timerify(someFunction);

const obs = new PerformanceObserver((list) => {
  console.log(list.getEntries()[0].duration);

  performance.clearMarks();
  performance.clearMeasures();
  obs.disconnect();
});
obs.observe({ entryTypes: ['function'] });

// A performance timeline entry will be created
wrapped();

Se a função envolvida retornar uma promise, um manipulador finally será anexado à promise e a duração será relatada assim que o manipulador finally for invocado.

performance.toJSON()

[Histórico]

Versão	Mudanças
v19.0.0	Este método deve ser chamado com o objeto performance como receptor.
v16.1.0	Adicionado em: v16.1.0

Um objeto que é uma representação JSON do objeto performance. É semelhante a window.performance.toJSON nos navegadores.

Evento: 'resourcetimingbufferfull'

Adicionado em: v18.8.0

O evento 'resourcetimingbufferfull' é disparado quando o buffer global de tempo de recursos de desempenho está cheio. Ajuste o tamanho do buffer de tempo de recursos com performance.setResourceTimingBufferSize() ou limpe o buffer com performance.clearResourceTimings() no listener de eventos para permitir que mais entradas sejam adicionadas ao buffer da linha do tempo de desempenho.

Classe: PerformanceEntry

Adicionado em: v8.5.0

O construtor desta classe não é exposto diretamente aos usuários.

performanceEntry.duration

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceEntry como receptor.
v8.5.0	Adicionado em: v8.5.0

• <number>

O número total de milissegundos decorridos para esta entrada. Este valor não será significativo para todos os tipos de Entrada de Desempenho.

performanceEntry.entryType

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceEntry como receptor.
v8.5.0	Adicionado em: v8.5.0

• <string>

O tipo da entrada de desempenho. Pode ser um de:

• 'dns' (apenas Node.js)
• 'function' (apenas Node.js)
• 'gc' (apenas Node.js)
• 'http2' (apenas Node.js)
• 'http' (apenas Node.js)
• 'mark' (disponível na Web)
• 'measure' (disponível na Web)
• 'net' (apenas Node.js)
• 'node' (apenas Node.js)
• 'resource' (disponível na Web)

performanceEntry.name

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceEntry como receptor.
v8.5.0	Adicionado em: v8.5.0

• <string>

O nome da entrada de desempenho.

performanceEntry.startTime

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceEntry como receptor.
v8.5.0	Adicionado em: v8.5.0

• <number>

O timestamp de alta resolução em milissegundos marcando o tempo de início da Entrada de Desempenho.

Classe: PerformanceMark

Adicionado em: v18.2.0, v16.17.0

• Estende: <PerformanceEntry>

Expõe as marcas criadas via o método Performance.mark().

performanceMark.detail

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceMark como receptor.
v16.0.0	Adicionado em: v16.0.0

• <any>

Detalhes adicionais especificados ao criar com o método Performance.mark().

Classe: PerformanceMeasure

Adicionado em: v18.2.0, v16.17.0

• Estende: <PerformanceEntry>

Expõe as medidas criadas via o método Performance.measure().

O construtor desta classe não é exposto diretamente aos usuários.

performanceMeasure.detail

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceMeasure como receptor.
v16.0.0	Adicionado em: v16.0.0

• <any>

Detalhes adicionais especificados ao criar com o método Performance.measure().

Classe: PerformanceNodeEntry

Adicionado em: v19.0.0

• Estende: <PerformanceEntry>

Esta classe é uma extensão do Node.js. Não está disponível em navegadores Web.

Fornece dados de temporização detalhados do Node.js.

O construtor desta classe não é exposto diretamente aos utilizadores.

performanceNodeEntry.detail

[Histórico]

Versão	Alterações
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceNodeEntry como receptor.
v16.0.0	Adicionado em: v16.0.0

• <any>

Detalhes adicionais específicos para o entryType.

performanceNodeEntry.flags

[Histórico]

Versão	Alterações
v16.0.0	Obsoleto em tempo de execução. Agora movido para a propriedade detail quando entryType é 'gc'.
v13.9.0, v12.17.0	Adicionado em: v13.9.0, v12.17.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use performanceNodeEntry.detail em vez disso.

• <number>

Quando performanceEntry.entryType é igual a 'gc', a propriedade performance.flags contém informações adicionais sobre a operação de coleta de lixo. O valor pode ser um dos:

• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_NO
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_FORCED
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY
• perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE

performanceNodeEntry.kind

[Histórico]

Versão	Alterações
v16.0.0	Obsoleto em tempo de execução. Agora movido para a propriedade detail quando entryType é 'gc'.
v8.5.0	Adicionado em: v8.5.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use performanceNodeEntry.detail em vez disso.

• <number>

Quando performanceEntry.entryType é igual a 'gc', a propriedade performance.kind identifica o tipo de operação de coleta de lixo que ocorreu. O valor pode ser um dos:

• perf_hooks.constants.NODE_PERFORMANCE_GC_MAJOR
• perf_hooks.constants.NODE_PERFORMANCE_GC_MINOR
• perf_hooks.constants.NODE_PERFORMANCE_GC_INCREMENTAL
• perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB

Detalhes da Coleta de Lixo ('gc')

Quando performanceEntry.type é igual a 'gc', a propriedade performanceNodeEntry.detail será um <Object> com duas propriedades:

• kind <number> Um de:

  • perf_hooks.constants.NODE_PERFORMANCE_GC_MAJOR
  • perf_hooks.constants.NODE_PERFORMANCE_GC_MINOR
  • perf_hooks.constants.NODE_PERFORMANCE_GC_INCREMENTAL
  • perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB

• flags <number> Um de:

  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_NO
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_FORCED
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY
  • perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE

Detalhes HTTP ('http')

Quando performanceEntry.type é igual a 'http', a propriedade performanceNodeEntry.detail será um <Object> contendo informações adicionais.

Se performanceEntry.name é igual a HttpClient, o detail conterá as seguintes propriedades: req, res. E a propriedade req será um <Object> contendo method, url, headers, a propriedade res será um <Object> contendo statusCode, statusMessage, headers.

Se performanceEntry.name é igual a HttpRequest, o detail conterá as seguintes propriedades: req, res. E a propriedade req será um <Object> contendo method, url, headers, a propriedade res será um <Object> contendo statusCode, statusMessage, headers.

Isso pode adicionar uma sobrecarga de memória adicional e só deve ser usado para fins de diagnóstico, não sendo deixado ligado na produção por padrão.

Detalhes do HTTP/2 ('http2')

Quando performanceEntry.type é igual a 'http2', a propriedade performanceNodeEntry.detail será um <Object> contendo informações adicionais de desempenho.

Se performanceEntry.name for igual a Http2Stream, o detail conterá as seguintes propriedades:

• bytesRead <number> O número de bytes do frame DATA recebidos para este Http2Stream.
• bytesWritten <number> O número de bytes do frame DATA enviados para este Http2Stream.
• id <number> O identificador do Http2Stream associado.
• timeToFirstByte <number> O número de milissegundos decorridos entre o startTime do PerformanceEntry e a recepção do primeiro frame DATA.
• timeToFirstByteSent <number> O número de milissegundos decorridos entre o startTime do PerformanceEntry e o envio do primeiro frame DATA.
• timeToFirstHeader <number> O número de milissegundos decorridos entre o startTime do PerformanceEntry e a recepção do primeiro cabeçalho.

Se performanceEntry.name for igual a Http2Session, o detail conterá as seguintes propriedades:

• bytesRead <number> O número de bytes recebidos para esta Http2Session.
• bytesWritten <number> O número de bytes enviados para esta Http2Session.
• framesReceived <number> O número de frames HTTP/2 recebidos pela Http2Session.
• framesSent <number> O número de frames HTTP/2 enviados pela Http2Session.
• maxConcurrentStreams <number> O número máximo de streams abertos simultaneamente durante o tempo de vida da Http2Session.
• pingRTT <number> O número de milissegundos decorridos desde a transmissão de um frame PING e a recepção de seu reconhecimento. Presente apenas se um frame PING foi enviado na Http2Session.
• streamAverageDuration <number> A duração média (em milissegundos) para todas as instâncias Http2Stream.
• streamCount <number> O número de instâncias Http2Stream processadas pela Http2Session.
• type <string> 'server' ou 'client' para identificar o tipo de Http2Session.

Detalhes do Timerify ('function')

Quando performanceEntry.type é igual a 'function', a propriedade performanceNodeEntry.detail será um <Array> listando os argumentos de entrada para a função cronometrada.

Detalhes do Net ('net')

Quando performanceEntry.type é igual a 'net', a propriedade performanceNodeEntry.detail será um <Object> contendo informações adicionais.

Se performanceEntry.name for igual a connect, o detail conterá as seguintes propriedades: host, port.

Detalhes do DNS ('dns')

Quando performanceEntry.type é igual a 'dns', a propriedade performanceNodeEntry.detail será um <Object> contendo informações adicionais.

Se performanceEntry.name for igual a lookup, o detail conterá as seguintes propriedades: hostname, family, hints, verbatim, addresses.

Se performanceEntry.name for igual a lookupService, o detail conterá as seguintes propriedades: host, port, hostname, service.

Se performanceEntry.name for igual a queryxxx ou getHostByAddr, o detail conterá as seguintes propriedades: host, ttl, result. O valor de result é o mesmo que o resultado de queryxxx ou getHostByAddr.

Classe: PerformanceNodeTiming

Adicionado em: v8.5.0

• Estende: <PerformanceEntry>

Esta propriedade é uma extensão do Node.js. Não está disponível em navegadores da Web.

Fornece detalhes de tempo para o próprio Node.js. O construtor desta classe não é exposto aos usuários.

performanceNodeTiming.bootstrapComplete

Adicionado em: v8.5.0

• <number>

O timestamp de milissegundos de alta resolução em que o processo Node.js concluiu o bootstrapping. Se o bootstrapping ainda não terminou, a propriedade tem o valor de -1.

performanceNodeTiming.environment

Adicionado em: v8.5.0

• <number>

O timestamp de milissegundos de alta resolução em que o ambiente Node.js foi inicializado.

performanceNodeTiming.idleTime

Adicionado em: v14.10.0, v12.19.0

• <number>

O timestamp de milissegundos de alta resolução da quantidade de tempo que o loop de eventos ficou ocioso dentro do provedor de eventos do loop de eventos (por exemplo, epoll_wait). Isso não leva em consideração o uso da CPU. Se o loop de eventos ainda não foi iniciado (por exemplo, no primeiro tick do script principal), a propriedade tem o valor de 0.

performanceNodeTiming.loopExit

Adicionado em: v8.5.0

• <number>

O timestamp de milissegundos de alta resolução em que o loop de eventos do Node.js foi encerrado. Se o loop de eventos ainda não foi encerrado, a propriedade tem o valor de -1. Ele só pode ter um valor diferente de -1 em um manipulador do evento 'exit'.

performanceNodeTiming.loopStart

Adicionado em: v8.5.0

• <number>

O timestamp de milissegundos de alta resolução em que o loop de eventos do Node.js foi iniciado. Se o loop de eventos ainda não foi iniciado (por exemplo, no primeiro tick do script principal), a propriedade tem o valor de -1.

performanceNodeTiming.nodeStart

Adicionado em: v8.5.0

• <number>

O timestamp de milissegundos de alta resolução em que o processo Node.js foi inicializado.

performanceNodeTiming.uvMetricsInfo

Adicionado em: v22.8.0, v20.18.0

• Retorna: <Object>
  • loopCount <number> Número de iterações do loop de eventos.
  • events <number> Número de eventos que foram processados pelo manipulador de eventos.
  • eventsWaiting <number> Número de eventos que estavam esperando para serem processados quando o provedor de eventos foi chamado.

Esta é uma wrapper para a função uv_metrics_info. Ela retorna o conjunto atual de métricas do loop de eventos.

Recomenda-se usar esta propriedade dentro de uma função cuja execução foi agendada usando setImmediate para evitar coletar métricas antes de terminar todas as operações agendadas durante a iteração atual do loop.

CJS

const { performance } = require('node:perf_hooks');

setImmediate(() => {
  console.log(performance.nodeTiming.uvMetricsInfo);
});

ESM

import { performance } from 'node:perf_hooks';

setImmediate(() => {
  console.log(performance.nodeTiming.uvMetricsInfo);
});

performanceNodeTiming.v8Start

Adicionado em: v8.5.0

• <number>

O timestamp de milissegundos de alta resolução no qual a plataforma V8 foi inicializada.

Classe: PerformanceResourceTiming

Adicionado em: v18.2.0, v16.17.0

• Estende: <PerformanceEntry>

Fornece dados de tempo de rede detalhados sobre o carregamento dos recursos de um aplicativo.

O construtor desta classe não é exposto diretamente aos usuários.

performanceResourceTiming.workerStart

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

O timestamp de milissegundos de alta resolução imediatamente antes de despachar a requisição fetch. Se o recurso não for interceptado por um worker, a propriedade sempre retornará 0.

performanceResourceTiming.redirectStart

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

O timestamp de milissegundos de alta resolução que representa a hora de início da busca que inicia o redirecionamento.

performanceResourceTiming.redirectEnd

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

O timestamp de milissegundos de alta resolução que será criado imediatamente após receber o último byte da resposta do último redirecionamento.

performanceResourceTiming.fetchStart

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

O timestamp de milissegundos de alta resolução imediatamente antes do Node.js começar a buscar o recurso.

performanceResourceTiming.domainLookupStart

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

O timestamp de milissegundos de alta resolução imediatamente antes do Node.js iniciar a pesquisa de nome de domínio para o recurso.

performanceResourceTiming.domainLookupEnd

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

O timestamp de milissegundos de alta resolução representando o tempo imediatamente após o Node.js terminar a pesquisa de nome de domínio para o recurso.

performanceResourceTiming.connectStart

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

O timestamp de milissegundos de alta resolução representando o tempo imediatamente antes do Node.js começar a estabelecer a conexão com o servidor para recuperar o recurso.

performanceResourceTiming.connectEnd

[Histórico]

Versão	Alterações
v19.0.0	O getter desta propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

O timestamp de milissegundos de alta resolução que representa o tempo imediatamente após o Node.js terminar de estabelecer a conexão com o servidor para recuperar o recurso.

performanceResourceTiming.secureConnectionStart

[Histórico]

Versão	Alterações
v19.0.0	O getter desta propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

O timestamp de milissegundos de alta resolução que representa o tempo imediatamente antes do Node.js iniciar o processo de handshake para proteger a conexão atual.

performanceResourceTiming.requestStart

[Histórico]

Versão	Alterações
v19.0.0	O getter desta propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

O timestamp de milissegundos de alta resolução que representa o tempo imediatamente antes do Node.js receber o primeiro byte da resposta do servidor.

performanceResourceTiming.responseEnd

[Histórico]

Versão	Alterações
v19.0.0	O getter desta propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

O timestamp de milissegundos de alta resolução que representa o tempo imediatamente após o Node.js receber o último byte do recurso ou imediatamente antes da conexão de transporte ser fechada, o que ocorrer primeiro.

performanceResourceTiming.transferSize

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

Um número representando o tamanho (em octetos) do recurso buscado. O tamanho inclui os campos do cabeçalho de resposta mais o corpo do payload de resposta.

performanceResourceTiming.encodedBodySize

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

Um número representando o tamanho (em octetos) recebido da busca (HTTP ou cache), do corpo do payload, antes de remover qualquer codificação de conteúdo aplicada.

performanceResourceTiming.decodedBodySize

[Histórico]

Versão	Mudanças
v19.0.0	Este getter de propriedade deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• <number>

Um número representando o tamanho (em octetos) recebido da busca (HTTP ou cache), do corpo da mensagem, após remover qualquer codificação de conteúdo aplicada.

performanceResourceTiming.toJSON()

[Histórico]

Versão	Mudanças
v19.0.0	Este método deve ser chamado com o objeto PerformanceResourceTiming como receptor.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

Retorna um objeto que é a representação JSON do objeto PerformanceResourceTiming

Classe: PerformanceObserver

Adicionado em: v8.5.0

PerformanceObserver.supportedEntryTypes

Adicionado em: v16.0.0

• <string[]>

Obtém os tipos suportados.

new PerformanceObserver(callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v8.5.0	Adicionado em: v8.5.0

• callback <Function>
  • list <PerformanceObserverEntryList>
  • observer <PerformanceObserver>

Objetos PerformanceObserver fornecem notificações quando novas instâncias de PerformanceEntry são adicionadas à Linha do Tempo de Desempenho.

ESM

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries());

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark'], buffered: true });

performance.mark('test');

CJS

const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries());

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark'], buffered: true });

performance.mark('test');

Como as instâncias de PerformanceObserver introduzem sua própria sobrecarga de desempenho adicional, as instâncias não devem ser deixadas inscritas para notificações indefinidamente. Os usuários devem desconectar os observadores assim que não forem mais necessários.

O callback é invocado quando um PerformanceObserver é notificado sobre novas instâncias de PerformanceEntry. O callback recebe uma instância de PerformanceObserverEntryList e uma referência ao PerformanceObserver.

performanceObserver.disconnect()

Adicionado em: v8.5.0

Desconecta a instância de PerformanceObserver de todas as notificações.

performanceObserver.observe(options)

[Histórico]

Versão	Mudanças
v16.7.0	Atualizado para estar em conformidade com o Performance Timeline Level 2. A opção buffered foi readicionada.
v16.0.0	Atualizado para estar em conformidade com o User Timing Level 3. A opção buffered foi removida.
v8.5.0	Adicionado em: v8.5.0

• options <Objeto>
  • type <string> Um único tipo de <PerformanceEntry>. Não deve ser fornecido se entryTypes já estiver especificado.
  • entryTypes <string[]> Um array de strings identificando os tipos de instâncias <PerformanceEntry> nas quais o observador está interessado. Se não for fornecido, um erro será lançado.
  • buffered <boolean> Se verdadeiro, o callback do observador é chamado com uma lista global de entradas PerformanceEntry armazenadas em buffer. Se falso, apenas as PerformanceEntrys criadas após o ponto no tempo são enviadas ao callback do observador. Padrão: false.

Assina a instância <PerformanceObserver> para notificações de novas instâncias <PerformanceEntry> identificadas por options.entryTypes ou options.type:

ESM

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((list, observer) => {
  // Chamado uma vez assincronamente. `list` contém três itens.
});
obs.observe({ type: 'mark' });

for (let n = 0; n < 3; n++)
  performance.mark(`test${n}`);

CJS

const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const obs = new PerformanceObserver((list, observer) => {
  // Chamado uma vez assincronamente. `list` contém três itens.
});
obs.observe({ type: 'mark' });

for (let n = 0; n < 3; n++)
  performance.mark(`test${n}`);

performanceObserver.takeRecords()

Adicionado em: v16.0.0

• Retorna: <PerformanceEntry[]> Lista atual de entradas armazenadas no observador de desempenho, esvaziando-o.

Classe: PerformanceObserverEntryList

Adicionado em: v8.5.0

A classe PerformanceObserverEntryList é usada para fornecer acesso às instâncias PerformanceEntry passadas para um PerformanceObserver. O construtor desta classe não é exposto aos usuários.

performanceObserverEntryList.getEntries()

Adicionado em: v8.5.0

• Retorna: <PerformanceEntry[]>

Retorna uma lista de objetos PerformanceEntry em ordem cronológica com relação a performanceEntry.startTime.

ESM

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntries());
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 81.465639,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 81.860064,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');

CJS

const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntries());
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 81.465639,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 81.860064,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');

performanceObserverEntryList.getEntriesByName(name[, type])

Adicionado em: v8.5.0

• name <string>
• type <string>
• Retorna: <PerformanceEntry[]>

Retorna uma lista de objetos PerformanceEntry em ordem cronológica com relação a performanceEntry.startTime cujo performanceEntry.name é igual a name, e opcionalmente, cujo performanceEntry.entryType é igual a type.

ESM

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByName('meow'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 98.545991,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('nope')); // []

  console.log(perfObserverList.getEntriesByName('test', 'mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 63.518931,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('test', 'measure')); // []

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark', 'measure'] });

performance.mark('test');
performance.mark('meow');

CJS

const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByName('meow'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 98.545991,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('nope')); // []

  console.log(perfObserverList.getEntriesByName('test', 'mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 63.518931,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  console.log(perfObserverList.getEntriesByName('test', 'measure')); // []

  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['mark', 'measure'] });

performance.mark('test');
performance.mark('meow');

performanceObserverEntryList.getEntriesByType(type)

Adicionado em: v8.5.0

• type <string>
• Retorna: <PerformanceEntry[]>

Retorna uma lista de objetos PerformanceEntry em ordem cronológica com relação a performanceEntry.startTime cujo performanceEntry.entryType é igual a type.

ESM

import { performance, PerformanceObserver } from 'node:perf_hooks';

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByType('mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 55.897834,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 56.350146,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');

CJS

const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const obs = new PerformanceObserver((perfObserverList, observer) => {
  console.log(perfObserverList.getEntriesByType('mark'));
  /**
   * [
   *   PerformanceEntry {
   *     name: 'test',
   *     entryType: 'mark',
   *     startTime: 55.897834,
   *     duration: 0,
   *     detail: null
   *   },
   *   PerformanceEntry {
   *     name: 'meow',
   *     entryType: 'mark',
   *     startTime: 56.350146,
   *     duration: 0,
   *     detail: null
   *   }
   * ]
   */
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ type: 'mark' });

performance.mark('test');
performance.mark('meow');

perf_hooks.createHistogram([options])

Adicionado em: v15.9.0, v14.18.0

• options <Object>

  • lowest <number> | <bigint> O menor valor discernível. Deve ser um valor inteiro maior que 0. Padrão: 1.
  • highest <number> | <bigint> O valor mais alto registrável. Deve ser um valor inteiro igual ou maior que duas vezes lowest. Padrão: Number.MAX_SAFE_INTEGER.
  • figures <number> O número de dígitos de precisão. Deve ser um número entre 1 e 5. Padrão: 3.

• Retorna: <RecordableHistogram>

Retorna um <RecordableHistogram>.

perf_hooks.monitorEventLoopDelay([options])

Adicionado em: v11.10.0

• options <Object>

  • resolution <number> A taxa de amostragem em milissegundos. Deve ser maior que zero. Padrão: 10.

• Retorna: <IntervalHistogram>

Esta propriedade é uma extensão do Node.js. Não está disponível em navegadores da Web.

Cria um objeto IntervalHistogram que amostra e reporta o atraso do loop de eventos ao longo do tempo. Os atrasos serão reportados em nanossegundos.

Usar um timer para detectar o atraso aproximado do loop de eventos funciona porque a execução dos timers está vinculada especificamente ao ciclo de vida do loop de eventos do libuv. Ou seja, um atraso no loop causará um atraso na execução do timer, e esses atrasos são especificamente o que esta API se destina a detectar.

ESM

import { monitorEventLoopDelay } from 'node:perf_hooks';

const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
// Faça alguma coisa.
h.disable();
console.log(h.min);
console.log(h.max);
console.log(h.mean);
console.log(h.stddev);
console.log(h.percentiles);
console.log(h.percentile(50));
console.log(h.percentile(99));

CJS

const { monitorEventLoopDelay } = require('node:perf_hooks');
const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
// Faça alguma coisa.
h.disable();
console.log(h.min);
console.log(h.max);
console.log(h.mean);
console.log(h.stddev);
console.log(h.percentiles);
console.log(h.percentile(50));
console.log(h.percentile(99));

Classe: Histogram

Adicionado em: v11.10.0

histogram.count

Adicionado em: v17.4.0, v16.14.0

• <number>

O número de amostras registradas pelo histograma.

histogram.countBigInt

Adicionado em: v17.4.0, v16.14.0

• <bigint>

O número de amostras registradas pelo histograma.

histogram.exceeds

Adicionado em: v11.10.0

• <number>

O número de vezes que o atraso do loop de eventos excedeu o limite máximo de 1 hora de atraso do loop de eventos.

histogram.exceedsBigInt

Adicionado em: v17.4.0, v16.14.0

• <bigint>

O número de vezes que o atraso do loop de eventos excedeu o limite máximo de 1 hora de atraso do loop de eventos.

histogram.max

Adicionado em: v11.10.0

• <number>

O atraso máximo gravado no loop de eventos.

histogram.maxBigInt

Adicionado em: v17.4.0, v16.14.0

• <bigint>

O atraso máximo gravado no loop de eventos.

histogram.mean

Adicionado em: v11.10.0

• <number>

A média dos atrasos gravados no loop de eventos.

histogram.min

Adicionado em: v11.10.0

• <number>

O atraso mínimo gravado no loop de eventos.

histogram.minBigInt

Adicionado em: v17.4.0, v16.14.0

• <bigint>

O atraso mínimo gravado no loop de eventos.

histogram.percentile(percentile)

Adicionado em: v11.10.0

• percentile <number> Um valor de percentil no intervalo (0, 100].
• Retorna: <number>

Retorna o valor no percentil fornecido.

histogram.percentileBigInt(percentile)

Adicionado em: v17.4.0, v16.14.0

• percentile <number> Um valor de percentil no intervalo (0, 100].
• Retorna: <bigint>

Retorna o valor no percentil fornecido.

histogram.percentiles

Adicionado em: v11.10.0

• <Map>

Retorna um objeto Map detalhando a distribuição de percentis acumulada.

histogram.percentilesBigInt

Adicionado em: v17.4.0, v16.14.0

• <Map>

Retorna um objeto Map detalhando a distribuição de percentis acumulada.

histogram.reset()

Adicionado em: v11.10.0

Redefine os dados coletados do histograma.

histogram.stddev

Adicionado em: v11.10.0

• <number>

O desvio padrão dos atrasos do loop de eventos registrados.

Classe: IntervalHistogram extends Histogram

Um Histogram que é atualizado periodicamente em um determinado intervalo.

histogram.disable()

Adicionado em: v11.10.0

• Retorna: <boolean>

Desativa o temporizador de intervalo de atualização. Retorna true se o temporizador foi interrompido, false se já estava interrompido.

histogram.enable()

Adicionado em: v11.10.0

• Retorna: <boolean>

Ativa o temporizador de intervalo de atualização. Retorna true se o temporizador foi iniciado, false se já estava iniciado.

Clonando um IntervalHistogram

Instâncias de <IntervalHistogram> podem ser clonadas via <MessagePort>. Na extremidade receptora, o histograma é clonado como um objeto <Histogram> simples que não implementa os métodos enable() e disable().

Classe: RecordableHistogram extends Histogram

Adicionado em: v15.9.0, v14.18.0

histogram.add(other)

Adicionado em: v17.4.0, v16.14.0

• other <RecordableHistogram>

Adiciona os valores de other a este histograma.

histogram.record(val)

Adicionado em: v15.9.0, v14.18.0

• val <number> | <bigint> O valor a ser registrado no histograma.

histogram.recordDelta()

Adicionado em: v15.9.0, v14.18.0

Calcula a quantidade de tempo (em nanossegundos) que se passou desde a chamada anterior para recordDelta() e registra essa quantidade no histograma.

Exemplos

Medindo a duração de operações assíncronas

O exemplo a seguir usa as APIs Hooks Assíncronos e Performance para medir a duração real de uma operação de Timeout (incluindo a quantidade de tempo que levou para executar o callback).

ESM

import { createHook } from 'node:async_hooks';
import { performance, PerformanceObserver } from 'node:perf_hooks';

const set = new Set();
const hook = createHook({
  init(id, type) {
    if (type === 'Timeout') {
      performance.mark(`Timeout-${id}-Init`);
      set.add(id);
    }
  },
  destroy(id) {
    if (set.has(id)) {
      set.delete(id);
      performance.mark(`Timeout-${id}-Destroy`);
      performance.measure(`Timeout-${id}`,
                          `Timeout-${id}-Init`,
                          `Timeout-${id}-Destroy`);
    }
  },
});
hook.enable();

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries()[0]);
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['measure'], buffered: true });

setTimeout(() => {}, 1000);

CJS

'use strict';
const async_hooks = require('node:async_hooks');
const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');

const set = new Set();
const hook = async_hooks.createHook({
  init(id, type) {
    if (type === 'Timeout') {
      performance.mark(`Timeout-${id}-Init`);
      set.add(id);
    }
  },
  destroy(id) {
    if (set.has(id)) {
      set.delete(id);
      performance.mark(`Timeout-${id}-Destroy`);
      performance.measure(`Timeout-${id}`,
                          `Timeout-${id}-Init`,
                          `Timeout-${id}-Destroy`);
    }
  },
});
hook.enable();

const obs = new PerformanceObserver((list, observer) => {
  console.log(list.getEntries()[0]);
  performance.clearMarks();
  performance.clearMeasures();
  observer.disconnect();
});
obs.observe({ entryTypes: ['measure'], buffered: true });

setTimeout(() => {}, 1000);

Medindo quanto tempo leva para carregar dependências

O exemplo a seguir mede a duração das operações require() para carregar dependências:

ESM

import { performance, PerformanceObserver } from 'node:perf_hooks';

// Ativar o observador
const obs = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  entries.forEach((entry) => {
    console.log(`import('${entry[0]}')`, entry.duration);
  });
  performance.clearMarks();
  performance.clearMeasures();
  obs.disconnect();
});
obs.observe({ entryTypes: ['function'], buffered: true });

const timedImport = performance.timerify(async (module) => {
  return await import(module);
});

await timedImport('some-module');

CJS

'use strict';
const {
  performance,
  PerformanceObserver,
} = require('node:perf_hooks');
const mod = require('node:module');

// Monkey patch na função require
mod.Module.prototype.require =
  performance.timerify(mod.Module.prototype.require);
require = performance.timerify(require);

// Ativar o observador
const obs = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  entries.forEach((entry) => {
    console.log(`require('${entry[0]}')`, entry.duration);
  });
  performance.clearMarks();
  performance.clearMeasures();
  obs.disconnect();
});
obs.observe({ entryTypes: ['function'], buffered: true });

require('some-module');

Medindo quanto tempo leva um round-trip HTTP

O exemplo a seguir é usado para rastrear o tempo gasto pelo cliente HTTP (OutgoingMessage) e pela requisição HTTP (IncomingMessage). Para o cliente HTTP, significa o intervalo de tempo entre o início da requisição e o recebimento da resposta, e para a requisição HTTP, significa o intervalo de tempo entre o recebimento da requisição e o envio da resposta:

ESM

import { PerformanceObserver } from 'node:perf_hooks';
import { createServer, get } from 'node:http';

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});

obs.observe({ entryTypes: ['http'] });

const PORT = 8080;

createServer((req, res) => {
  res.end('ok');
}).listen(PORT, () => {
  get(`http://127.0.0.1:${PORT}`);
});

CJS

'use strict';
const { PerformanceObserver } = require('node:perf_hooks');
const http = require('node:http');

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});

obs.observe({ entryTypes: ['http'] });

const PORT = 8080;

http.createServer((req, res) => {
  res.end('ok');
}).listen(PORT, () => {
  http.get(`http://127.0.0.1:${PORT}`);
});

Medindo quanto tempo o net.connect (apenas para TCP) leva quando a conexão é bem-sucedida

ESM

import { PerformanceObserver } from 'node:perf_hooks';
import { connect, createServer } from 'node:net';

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['net'] });
const PORT = 8080;
createServer((socket) => {
  socket.destroy();
}).listen(PORT, () => {
  connect(PORT);
});

CJS

'use strict';
const { PerformanceObserver } = require('node:perf_hooks');
const net = require('node:net');
const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['net'] });
const PORT = 8080;
net.createServer((socket) => {
  socket.destroy();
}).listen(PORT, () => {
  net.connect(PORT);
});

Medindo quanto tempo o DNS leva quando a requisição é bem-sucedida

ESM

import { PerformanceObserver } from 'node:perf_hooks';
import { lookup, promises } from 'node:dns';

const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['dns'] });
lookup('localhost', () => {});
promises.resolve('localhost');

CJS

'use strict';
const { PerformanceObserver } = require('node:perf_hooks');
const dns = require('node:dns');
const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((item) => {
    console.log(item);
  });
});
obs.observe({ entryTypes: ['dns'] });
dns.lookup('localhost', () => {});
dns.promises.resolve('localhost');