Usando o agente Node.js em um aplicativo ESM

Caso utilize o ESM para gerenciar o código em seu aplicativo Node.js, agora é possível monitorar esse aplicativo usando o agente Node.js.

Visão geral

Antes da v12.0.0, O Node.js oferece suporte oficial apenas ao gerenciamento de código usando módulos CommonJS. Os módulos CommonJS usam instruções module.exports e require() para gerenciar código como neste exemplo:

'use strict'

const bar = require('./bar')

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

module.exports = {
  echoBar
}

Desde o Node.js v12.0.0, foi adicionado suporte para módulos ECMAScript (módulos ES/"ESM").

Em vez de require() e module.exports, o ESM usa instruções import e export como estas:

'use strict'

import bar from './bar.js'

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

O ESM é o padrão ECMAScript oficial para gerenciamento de código e é a maneira padrão pela qual o browser e outros tempos de execução JS gerenciam pacotes. Para dar suporte ao ecossistema Node.js em evolução, tanto agora quanto no futuro, o agente oferece suporte a aplicativos instrumentados escritos usando ESM, a partir da versão 9.1.0 do agente. O agente APM Node.js também continua a oferecer suporte ao aplicativo CommonJS.

Configuração do agente

Para que o agente possa instrumentar com êxito um aplicativo ESM, será necessário primeiro instalar o agente Node.js, conforme descrito na documentação de instalação. Após a instalação do agente, continue com a configuração nas seções abaixo.

Configuração

Se seu aplicativo usar um arquivo de configuração para configurar o agente, você precisará atualizar a extensão do arquivo de configuração para .cjs em vez de .js.

O agente é escrito como um módulo CommonJS; ele usa require() para ler o arquivo de configuração na inicialização. Ao alterar a extensão do arquivo, rotulamos explicitamente o arquivo de configuração do agente como um módulo CommonJS, permitindo que o agente o carregue com sucesso.

Se você não atualizar a extensão do arquivo, poderá ver o seguinte erro durante a inicialização do 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.

Adicionar o carregador ESM

Para que o agente aplique adequadamente a instrumentação dentro do ecossistema ESM, é necessário incluir o carregador ESM do agente junto com o agente na invocação do seu aplicativo. É possível adicionar o carregador ao seu aplicativo usando o argumento da CLI --import do Node.js.

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

Instrumentação personalizada

O agente APM Node.js oferece suporte à adição de instrumentação personalizada ao seu aplicativo ESM. É possível criar instrumentação no aplicativo ESM usando a maioria dos métodos de registro de instrumentação na API. Devido à natureza das importações do ESM, o agente não oferece suporte a newrelic.instrumentLoadedModule. As vinculações do ESM não podem ser atribuídas, o que impede o agente de substituir os membros exportados de um módulo por instrumentação após o carregamento do módulo.

Para ver uma demonstração de como usar a API de instrumentação personalizada em um aplicativo ESM, confira nosso exemplo no GitHub.

Saber mais

• Documentação do ESM do Node.js
• Documentação de empacotamento do Node.js
• Documentação dos padrões ECMAScript
• Aplicativo ESM de demonstração