Uso del agente de Node.js en una aplicación ESM

Si utiliza ESM para administrar el código en la aplicación de Node.js, ahora puede monitorear esa aplicación mediante el agente de Node.js.

Descripción general

Antes de v12.0.0, Node.js solo admite oficialmente la gestión de código mediante módulos CommonJS. Los módulos CommonJS utilizan declaraciones module.exports y require() para administrar el código como en este ejemplo:

'use strict'

const bar = require('./bar')

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

module.exports = {
  echoBar
}

Desde Node.js v12.0.0, se agregó soporte para módulos ECMAScript (módulos ES/"ESM").

En lugar de require() y module.exports, ESM utiliza declaraciones import y export como esta:

'use strict'

import bar from './bar.js'

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

ESM es el estándar oficial ECMAScript para la administración de código y es la forma estándar en que los navegadores y otros tiempos de ejecución JS administran paquetes. Para respaldar la evolución del ecosistema Node.js, tanto ahora como en el futuro, el agente admite la aplicación instrumentada escrita utilizando ESM, a partir de la versión 9.1.0 del agente. El agente APM de Node.js también sigue siendo compatible con la aplicación CommonJS.

Configuración del agente

Para que el agente pueda instrumentar con éxito una aplicación ESM, primero deberá instalar el agente de Node.js, tal como se describe en la documentación de instalación. Una vez instalado el agente, continúe con la configuración en las secciones a continuación.

Configuración

Si su aplicación utiliza un archivo de configuración para configurar el agente, deberá actualizar la extensión del archivo de configuración para que sea .cjs en lugar de .js.

El agente está escrito como un módulo CommonJS; utiliza require() para leer el archivo de configuración al inicio. Al cambiar la extensión del archivo, etiquetamos explícitamente el archivo de configuración del agente como un módulo CommonJS, lo que permite que el agente lo cargue correctamente.

Si no actualiza la extensión del archivo, es posible que vea el siguiente error durante el inicio del agente:

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.

Agregar el cargador ESM

Para que el agente aplique correctamente la instrumentación dentro del ecosistema ESM, debe incluir el cargador ESM del agente junto con el agente en la invocación de la aplicación. Puede agregar el cargador a la aplicación mediante el argumento de la CLI --import de Node.js.

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

Instrumentación personalizada

El agente APM de Node.js permite agregar instrumentación personalizada a la aplicación ESM. Puede crear instrumentación en la aplicación ESM usando la mayoría de los métodos de registro de instrumentación en la API. Debido a la naturaleza de las importaciones ESM, el agente no admite newrelic.instrumentLoadedModule. Los enlaces ESM no son asignables, lo que impide que el agente reemplace los miembros exportados de un módulo con instrumentación después de que el módulo se haya cargado.

Para ver una demostración de cómo usar la API de instrumentación personalizada en una aplicación ESM, consulte nuestro ejemplo en GitHub.

Aprende más

• Documentación de ESM de Node.js
• Documentación de empaquetado de Node.js
• Documentación de estándares ECMAScript
• Aplicación ESM de demostración