Événements de trace

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Code source : lib/trace_events.js

Le module node:trace_events fournit un mécanisme pour centraliser les informations de trace générées par V8, le cœur de Node.js et le code espace utilisateur.

La trace peut être activée avec l’indicateur de ligne de commande --trace-event-categories ou en utilisant le module node:trace_events. L’indicateur --trace-event-categories accepte une liste de noms de catégories séparés par des virgules.

Les catégories disponibles sont :

• node : Un espace réservé vide.

• node.async_hooks : Active la capture de données de trace détaillées async_hooks. Les événements async_hooks ont un asyncId unique et une propriété spéciale triggerId triggerAsyncId.

• node.bootstrap : Active la capture des jalons d’amorçage de Node.js.

• node.console : Active la capture de la sortie console.time() et console.count().

• node.threadpoolwork.sync : Active la capture des données de trace pour les opérations synchrones du pool de threads, telles que blob, zlib, crypto et node_api.

• node.threadpoolwork.async : Active la capture des données de trace pour les opérations asynchrones du pool de threads, telles que blob, zlib, crypto et node_api.

• node.dns.native : Active la capture des données de trace pour les requêtes DNS.

• node.net.native : Active la capture des données de trace pour le réseau.

• node.environment : Active la capture des jalons de l’environnement Node.js.

• node.fs.sync : Active la capture des données de trace pour les méthodes synchrones du système de fichiers.

• node.fs_dir.sync : Active la capture des données de trace pour les méthodes synchrones du répertoire du système de fichiers.

• node.fs.async : Active la capture des données de trace pour les méthodes asynchrones du système de fichiers.

• node.fs_dir.async : Active la capture des données de trace pour les méthodes asynchrones du répertoire du système de fichiers.

• node.perf : Active la capture des mesures de l’API Performance.

  • node.perf.usertiming : Active la capture uniquement des mesures et des marques de l’API Performance User Timing.
  • node.perf.timerify : Active la capture uniquement des mesures timerify de l’API Performance.

• node.promises.rejections : Active la capture des données de trace suivant le nombre de rejets de promesse non gérés et les rejets gérés après coup.

• node.vm.script : Active la capture des données de trace pour les méthodes runInNewContext(), runInContext() et runInThisContext() du module node:vm.

• v8 : Les événements V8 sont liés à la GC, à la compilation et à l’exécution.

• node.http : Active la capture des données de trace pour les requêtes/réponses HTTP.

• node.module_timer : Active la capture des données de trace pour le chargement des modules CJS.

Par défaut, les catégories node, node.async_hooks et v8 sont activées.

node --trace-event-categories v8,node,node.async_hooks server.js

Les versions précédentes de Node.js nécessitaient l’utilisation de l’indicateur --trace-events-enabled pour activer les événements de trace. Cette exigence a été supprimée. Cependant, l’indicateur --trace-events-enabled peut toujours être utilisé et activera par défaut les catégories d’événements de trace node, node.async_hooks et v8.

node --trace-events-enabled

# est équivalent à {#is-equivalent-to}

node --trace-event-categories v8,node,node.async_hooks

Alternativement, les événements de trace peuvent être activés à l’aide du module node:trace_events :

const trace_events = require('node:trace_events')
const tracing = trace_events.createTracing({ categories: ['node.perf'] })
tracing.enable() // Activer la capture d’événements de trace pour la catégorie 'node.perf'

// effectuer le travail

tracing.disable() // Désactiver la capture d’événements de trace pour la catégorie 'node.perf'

L’exécution de Node.js avec la trace activée produira des fichiers journaux qui peuvent être ouverts dans l’onglet chrome://tracing de Chrome.

Le fichier de journalisation s’appelle par défaut node_trace.${rotation}.log, où ${rotation} est un ID de rotation de journal incrémental. Le modèle de chemin de fichier peut être spécifié avec --trace-event-file-pattern qui accepte une chaîne de modèle prenant en charge ${rotation} et ${pid} :

node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js

Pour garantir que le fichier journal est correctement généré après les événements de signal tels que SIGINT, SIGTERM ou SIGBREAK, assurez-vous d’avoir les gestionnaires appropriés dans votre code, tels que :

process.on('SIGINT', function onSigint() {
  console.info('Received SIGINT.')
  process.exit(130) // Ou code de sortie applicable selon le système d’exploitation et le signal
})

Le système de trace utilise la même source de temps que celle utilisée par process.hrtime(). Cependant, les horodatages des événements de trace sont exprimés en microsecondes, contrairement à process.hrtime() qui renvoie des nanosecondes.

Les fonctionnalités de ce module ne sont pas disponibles dans les threads Worker.

Le module node:trace_events

Ajouté dans : v10.0.0

Objet Tracing

Ajouté dans : v10.0.0

L'objet Tracing est utilisé pour activer ou désactiver le traçage pour des ensembles de catégories. Les instances sont créées à l'aide de la méthode trace_events.createTracing().

Lors de sa création, l'objet Tracing est désactivé. L'appel de la méthode tracing.enable() ajoute les catégories à l'ensemble des catégories d'événements de traçage activées. L'appel de tracing.disable() supprimera les catégories de l'ensemble des catégories d'événements de traçage activées.

tracing.categories

Ajouté dans : v10.0.0

• <string>

Une liste séparée par des virgules des catégories d'événements de traçage couvertes par cet objet Tracing.

tracing.disable()

Ajouté dans : v10.0.0

Désactive cet objet Tracing.

Seules les catégories d'événements de traçage non couvertes par d'autres objets Tracing activés et non spécifiées par l'indicateur --trace-event-categories seront désactivées.

const trace_events = require('node:trace_events')
const t1 = trace_events.createTracing({ categories: ['node', 'v8'] })
const t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] })
t1.enable()
t2.enable()

// Affiche 'node,node.perf,v8'
console.log(trace_events.getEnabledCategories())

t2.disable() // Ne désactivera que l'émission de la catégorie 'node.perf'

// Affiche 'node,v8'
console.log(trace_events.getEnabledCategories())

tracing.enable()

Ajouté dans : v10.0.0

Active cet objet Tracing pour l'ensemble des catégories couvertes par l'objet Tracing.

tracing.enabled

Ajouté dans : v10.0.0

• <boolean> true uniquement si l'objet Tracing a été activé.

trace_events.createTracing(options)

Ajouté dans : v10.0.0

• options <Object>

  • categories <string[]> Un tableau de noms de catégories de traçage. Les valeurs incluses dans le tableau sont converties en chaîne de caractères lorsque cela est possible. Une erreur sera levée si la valeur ne peut pas être convertie.

• Retourne : <Tracing>.

Crée et retourne un objet Tracing pour l'ensemble donné de categories.

const trace_events = require('node:trace_events')
const categories = ['node.perf', 'node.async_hooks']
const tracing = trace_events.createTracing({ categories })
tracing.enable()
// faire quelque chose
tracing.disable()

trace_events.getEnabledCategories()

Ajouté dans : v10.0.0

• Retourne : <string>

Retourne une liste séparée par des virgules de toutes les catégories d'événements de trace actuellement activées. L'ensemble actuel des catégories d'événements de trace activées est déterminé par l'union de tous les objets Tracing actuellement activés et de toutes les catégories activées à l'aide de l'indicateur --trace-event-categories.

Étant donné le fichier test.js ci-dessous, la commande node --trace-event-categories node.perf test.js affichera 'node.async_hooks,node.perf' sur la console.

const trace_events = require('node:trace_events')
const t1 = trace_events.createTracing({ categories: ['node.async_hooks'] })
const t2 = trace_events.createTracing({ categories: ['node.perf'] })
const t3 = trace_events.createTracing({ categories: ['v8'] })

t1.enable()
t2.enable()

console.log(trace_events.getEnabledCategories())

Exemples

Collecter les données des événements de trace par l'inspecteur

'use strict'

const { Session } = require('node:inspector')
const session = new Session()
session.connect()

function post(message, data) {
  return new Promise((resolve, reject) => {
    session.post(message, data, (err, result) => {
      if (err) reject(new Error(JSON.stringify(err)))
      else resolve(result)
    })
  })
}

async function collect() {
  const data = []
  session.on('NodeTracing.dataCollected', chunk => data.push(chunk))
  session.on('NodeTracing.tracingComplete', () => {
    // terminé
  })
  const traceConfig = { includedCategories: ['v8'] }
  await post('NodeTracing.start', { traceConfig })
  // faire quelque chose
  setTimeout(() => {
    post('NodeTracing.stop').then(() => {
      session.disconnect()
      console.log(data)
    })
  }, 1000)
}

collect()