Utilisation de l'agent Node.js dans une application ESM

Si vous utilisez ESM pour gérer le code dans vos applications Node.js, 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, ESM utilise les instructions import et export comme ceci :

'use strict'

import bar from './bar.js'

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

ESM est la norme officielle ECMAScript pour la gestion du code et constitue le moyen standard utilisé par les navigateurs et autres environnements d'exécution JS pour gérer les package. 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é écrites à l'aide d'ESM, à partir de la version 9.1.0 de l'agent. L'agent APM Node.js continue également de prendre en charge les applications CommonJS.

Configuration de l'agent

Pour que l'agent puisse avec succès instrument une application ESM, vous devrez d'abord installer l'agent Node.js, comme décrit dans la documentation d'installation. Une fois votre agent installé, continuez avec 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 ESM /path/to/your/application/newrelic.js from /path/to/your/application/node_modules/newrelic/lib/config/index.js not supported.

Ajoutez le chargeur ESM

Pour que l’agent puisse appliquer correctement l’instrumentation au sein de l’écosystème ESM, vous devez inclure le chargeur ESM de l’agent avec l’agent lors de l’invocation de votre application. Vous pouvez ajouter le chargeur à votre application en utilisant l’ argument CLI de Node.js --import.

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

instrumentation personnalisée

L'agent APM Node.js prend en charge l'ajout d'une instrumentation personnalisée à vos applications ESM. Vous pouvez créer une instrumentation dans les applications ESM en utilisant la plupart des méthodes d'enregistrement d'instrumentation sur l'API. En raison de la nature des importations ESM, l'agent ne prend pas en charge newrelic.instrumentLoadedModule. Les liaisons ESM 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 ESM, consultez notre exemple sur GitHub.

Apprendre encore plus

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