ESM 애플리케이션에서 Node.js 에이전트 사용하기

Node.js 애플리케이션에서 코드를 관리하기 위해 ESM을 사용하는 경우, 이제 Node.js 에이전트를 사용하여 해당 애플리케이션을 모니터할 수 있습니다.

개요

v12.0.0 이전에는 Node.js는 공식적으로 CommonJS 모듈을 사용한 코드 관리만 지원했습니다. CommonJS 모듈은 module.exports 및 require() 문을 사용하여 다음 예와 같이 코드를 관리합니다.

'use strict'

const bar = require('./bar')

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

module.exports = {
  echoBar
}

Node.js v12.0.0부터 ECMAScript 모듈(ES 모듈/"ESM")에 대한 지원이 추가되었습니다.

require() 및 module.exports 대신, ESM은 다음과 같이 import 및 export 문을 사용합니다:

'use strict'

import bar from './bar.js'

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

ESM은 코드 관리를 위한 공식 ECMAScript 표준이며 브라우저 및 기타 JS 런타임이 패키지를 관리하는 표준 방법입니다. 현재와 미래에 진화하는 Node.js 생태계를 지원하기 위해, 에이전트는 에이전트 버전 9.1.0부터 ESM을 사용하여 작성된 애플리케이션을 계측하는 것을 지원합니다. Node.js APM 에이전트는 CommonJS 애플리케이션도 계속해서 지원합니다.

에이전트 설정

에이전트가 ESM 애플리케이션을 성공적으로 계측하려면, 설치 문서에 설명된 대로 먼저 Node.js 에이전트를 설치해야 합니다. 에이전트가 설치되면, 아래 섹션의 설정을 계속 진행해 주십시오.

구성

애플리케이션이 구성 파일을 사용하여 에이전트를 구성하는 경우 구성 파일의 확장자를 .js .cjs 으로 업데이트해야 합니다.

에이전트는 CommonJS 모듈로 작성됩니다. 시작 시 구성 파일을 읽기 위해 require() 을 사용합니다. 파일 확장자를 변경하여 에이전트의 구성 파일에 CommonJS 모듈로 명시적으로 레이블을 지정하여 에이전트가 성공적으로 로드할 수 있도록 합니다.

파일 확장자를 업데이트하지 않으면 에이전트 시작 시 다음 오류가 표시될 수 있습니다.

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.

ESM 로더 추가

에이전트가 ESM 생태계 내에서 계측을 제대로 적용하려면, 애플리케이션 호출 시 에이전트와 함께 에이전트의 ESM 로더를 포함해야 합니다. Node.js --import CLI 인수를 사용하여 애플리케이션에 로더를 추가할 수 있습니다.

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

맞춤형 계측

Node.js APM 에이전트는 ESM 애플리케이션에 커스텀 측정을 추가하는 것을 지원합니다. API의 계측 등록 메서드 대부분을 사용하여 ESM 애플리케이션에서 계측을 생성할 수 있습니다. ESM 가져오기의 특성상, 에이전트는 newrelic.instrumentLoadedModule을(를) 지원하지 않습니다. ESM 바인딩은 할당할 수 없으므로, 모듈이 로드된 후 에이전트가 모듈의 내보낸 멤버를 계측으로 교체할 수 없습니다.

ESM 애플리케이션에서 커스텀 측정 API를 사용하는 방법에 대한 데모를 보려면, GitHub의 예제를 확인해 주십시오.

더 알아보기

• Node.js ESM 문서
• Node.js 패키징 문서
• ECMAScript 표준 문서
• 데모 ESM 애플리케이션