Usando o agente Node.js em um aplicativo de módulo ES

Se você usar módulos ES para gerenciar código em seu aplicativo Node.js, agora poderá monitor esses aplicativos 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, os módulos ES usam instruções import e export como esta:

'use strict'

import bar from './bar.js'

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

Os módulos ES são o padrão ECMAScript oficial para gerenciamento de código e são 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 em módulos ES, 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 sucesso uma aplicação de módulos ES, você precisará primeiro instalar o agente Node.js, conforme descrito na Documentação de instalação. Depois que seu agente estiver instalado, 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 ES module /path/to/your/application/newrelic.js from /path/to/your/application/node_modules/newrelic/lib/config/index.js not supported.

Adicione o carregador de módulo ES

Para que o agente aplique adequadamente a instrumentação no ecossistema do módulo ES, você deve incluir o carregador do módulo ES do agente junto com o agente na invocação do seu aplicativo. Você pode adicionar o carregador ao seu aplicativo usando o argumento da CLI --experimental-loader do Node.js.

$
node --experimental-loader 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 aplicativo do módulo ES. Você pode criar instrumentação no aplicativo do módulo ES usando a maioria dos métodos de registro de instrumentação na API. Devido à natureza das importações de módulos ES, não podemos oferecer suporte a newrelic.instrumentLoadedModule. As ligações do módulo ES não são atribuíveis, o que impede que o agente substitua os membros exportados de um módulo por instrumentação após o módulo ter sido carregado.

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

Saber mais

• Documentação do módulo Node.js ES
• Documentação de empacotamento do Node.js
• Documentação dos padrões ECMAScript
• Aplicativo de demonstração do módulo ES