Utilisation de l'agent Node.js dans une application de module ES

Si vous utilisez des modules ES pour gérer le code de votre Node.js application, vous pouvez désormais monitorer ces applications à l'aide de l'agent Node.js.

Présentation

Avant la version 12.0.0, Node.js prend officiellement en charge la gestion du code uniquement à l'aide de modules CommonJS. Les modules CommonJS utilisent les instructions module.exports et require() pour gérer le code comme dans cet exemple :

'use strict'

const bar = require('./bar')

function echoBar() {
  console.log('this is bar:', bar)
}

module.exports = {
  echoBar
}

Depuis Node.js v12.0.0, la prise en charge des modules ECMAScript (modules ES/"ESM") a été ajoutée.

Au lieu de require() et module.exports, les modules ES utilisent des instructions import et export comme ceci :

'use strict'

import bar from './bar.js'

export function echoBar() {
  console.log('this is bar:', bar)
}

Les modules ES sont la norme officielle ECMAScript pour la gestion de code et constituent le moyen standard utilisé par le navigateur et les autres environnements d'exécution JS pour gérer les packages. Afin de prendre en charge l'évolution de l'écosystème Node.js, aujourd'hui et à l'avenir, l' agent prend en charge les applications instrumentées écrites à l'aide de modules ES, à partir de la version 9.1.0 de l' agent. L'agent Node.js APM continue également de prendre en charge les applications CommonJS.

Configuration de l'agent

Pour que l'agent puisse avec succès instrumenter une de modules ES,application vous devez d'abord installer l'agent Node.js, comme décrit dans la documentation d'installation. Une fois votre agent installé, continuez la configuration dans les sections ci-dessous.

Configuration

Si votre application utilise un fichier de configuration pour configurer l'agent, vous devrez mettre à jour l'extension du fichier de configuration pour qu'elle soit .cjs au lieu de .js.

L'agent est écrit comme un module CommonJS ; il utilise require() pour lire le fichier de configuration au démarrage. En modifiant l'extension du fichier, nous étiquetons explicitement le fichier de configuration de l'agent comme un module CommonJS, permettant à l'agent de le charger avec succès.

Si vous ne mettez pas à jour l’extension du fichier, vous pouvez voir l’erreur suivante lors du démarrage de l’agent :

New Relic for Node.js is disabled due to an error:
Error [ERR_REQUIRE_ESM]: require() of ES module /path/to/your/application/newrelic.js from /path/to/your/application/node_modules/newrelic/lib/config/index.js not supported.

Ajouter le chargeur de module ES

Pour que l'agent applique correctement l'instrumentation au sein de l'écosystème du module ES, vous devez inclure le chargeur de module ES de l'agent avec l'agent dans l'appel de votre application. Vous pouvez ajouter le chargeur à votre application en utilisant l' argument CLI --experimental-loader de Node.js.

$
node --experimental-loader newrelic/esm-loader.mjs -r newrelic your-program.js

instrumentation personnalisée

L'agent Node.js APM prend instrumentation en charge l'ajout d' personnalisée à votre application de module ES. Vous pouvez créer instrumentation dans l'application du module ES en utilisant la plupart des méthodes d'enregistrement d' instrumentation sur l' API. En raison de la nature des importations de modules ES, nous ne sommes pas en mesure de prendre en charge newrelic.instrumentLoadedModule. Les liaisons de module ES ne sont pas assignables, ce qui empêche l'agent de remplacer les membres exportés d'un module par une instrumentation une fois le module chargé.

Pour voir une démonstration de la façon d’utiliser l’API d’instrumentation personnalisée dans une application de module ES, consultez notre exemple sur GitHub.

Apprendre encore plus

• Documentation du module ES de Node.js
• Documentation sur le packaging de Node.js
• Documentation sur les normes ECMAScript
• Application du module ES de démonstration