본문으로 건너뛰기

Node.js 에이전트 설치

Node.js 모니터링 서비스를 사용하려면 모니터링 대상 애플리케이션에 모니터링 에이전트를 설치해야 합니다. 설치는 npm(Node Package Manager)을 이용하세요.

  • 서비스 중인 Node.js 애플리케이션 디렉터리 경로에 와탭 에이전트 모듈을 설치하세요.

  • 와탭 에이전트의 환경 설정(whatap.conf)을 작성하세요.

  • Node.js 서비스를 다시 실행합니다.

에이전트 다운로드​

  1. 서비스 중인 Node.js 애플리케이션의 디렉터리 경로로 이동해 에이전트를 설치하세요.

    $ npm install --save whatap

  2. node_modules/whatap 경로의 whatap.conf 파일을 복사해 프로젝트의 루트(root) 경로(package.json 파일과 같은 위치)에 붙여 넣으세요.

  3. 와탭 모니터링 서비스 화면으로 이동하세요.

  4. 생성한 프로젝트를 선택한 다음 설치 안내 섹션의 에이전트 다운로드 내용 중 다음 내용을 복사하세요.

    Example
    license={액세스 키}
    whatap.server.host={수집 서버 IP}

  5. whatap.conf 파일에 붙여넣기 하세요.

호스트(whatap.server.host) 주소는 와탭 proxy를 설치한 서버의 주소입니다. 슬래시('/')를 구분자로 이용해 와탭 서버 중 proxy 서버가 실행 중인 서버의 모든 주소를 입력할 수 있습니다.

에이전트 구성 파일은 다음을 참조하세요.

팁

Next.js 또는 Nuxt.js와 같은 서버 사이드 렌더링(Server-side Rendering, SSR) 프레임워크에서 애플리케이션 모니터링을 위해 Custom Server 설정이 필요합니다. 일반적인 Node.js 프레임워크(예, Express.js, Nest.js)와는 다른 접근 방식을 요구합니다. 자세한 내용은 다음 문서를 참조하세요.

활용하기​

WHATAP_HOME 환경 변수 설정하기​

애플리케이션 디렉토리 경로를 WHATAP_HOME 환경변수에 설정하세요. 지정하지 않으면 기본적으로 현재 실행 디렉토리(process.cwd())가 사용됩니다.

export WHATAP_HOME={app_root_path}

WHATAP_HOME 경로에 whatap.conf 파일을 생성 후 아래의 값을 설정해주세요.

# whatap.conf
app_name=MyNodeApp              # 애플리케이션 이름, 기본값: NODE
app_process_name=node           # 프로세스 명 (예: node)

에이전트 설정하기​

애플리케이션의 진입점(메인 모듈) 파일의 최상단에 다음 코드를 추가하세요. 예를 들어 Express.js 애플리케이션에서는 app.js 또는 server.js 파일이 진입점(메인 모듈)입니다. Nest.js와 같은 프레임워크를 사용하는 경우 main.ts 파일이 될 수 있습니다.

CommonJS
var whatap = require('whatap').NodeAgent;

환경별 에이전트 옵션 설정하기​

애플리케이션의 각 환경에 맞춘 설정을 적용해야 할 때는 whatap.conf 파일 대신 애플리케이션의 진입점 파일에서 설정을 수정할 수 있습니다. 아래 코드를 참고하여 환경에 맞는 설정을 적용하세요.

process.env.WHATAP_CONF = 'whatap_dev.conf'; // Setting for development environment
var WhatapAgent = require('whatap').NodeAgent;

  • 환경별로 다른 프로젝트를 실행하는 경우:

    동일한 애플리케이션이라도 개발(dev), 테스트(test), 운영(prod) 등 각 환경에 맞는 설정이 필요합니다. 위 예시와 같이 WHATAP_CONF 환경 변수를 사용하여 개발 환경에 맞는 설정을 적용할 수 있습니다. 이를 통해 각 환경별로 다른 설정을 쉽게 관리할 수 있습니다.

  • 에이전트 옵션을 환경에 따라 다르게 설정해야 하는 경우:

    개발 환경에서는 로깅 수준을 높이고, 운영 환경에서는 성능 최적화를 위해 옵션을 다르게 설정할 수 있습니다. 이 경우 애플리케이션의 진입점 파일에서 각 환경에 맞게 에이전트 옵션을 수정하세요.

  • PM2의 클러스터 모드에서 애플리케이션을 실행하는 경우:

    클러스터 모드에서 여러 개의 애플리케이션 인스턴스를 실행할 때, 하나의 app_name(WHATAP_HOME)으로 통합하여 표현됩니다.

에이전트 그룹 단위 기능 활용하기​

에이전트 그룹 단위 기능에는 그룹 토폴로지, 통합 토폴로지 등이 있으며, 다음 코드에서 {그룹 식별자} 부분을 에이전트 그룹명으로 대체하여 사용하세요.

process.env.WHATAP_OKIND = '{그룹 식별자}';
var WhatapAgent = require('whatap').NodeAgent;

// 또는 whatap.conf에 아래와 같이 작성
whatap.okind = {그룹 식별자}

환경 변수로 설정 가능한 옵션​

whatap.conf 파일을 사용할 수 없기 때문에 소스 파일에 환경 변수로 와탭 에이전트 옵션을 설정해야 합니다.

app.js
process.env.profile_http_header_enabled=false;
process.env.profile_http_parameter_enabled=false;

process.env.profile_basetime=500;

process.env.auto_oname_enabled=false;
process.env.auto_oname_prefix='nodejs';

process.env.mtrace_rate=0;
process.env.mtrace_spec='v1';
process.env.stat_mtrace_enabled=false;
process.env.stat_domain_enabled=false;
노트

Node.js에서 설정할 수 있는 옵션에 대한 자세한 내용은 다음 문서를 참조하세요.

다음 단계​

  • 설치 점검하기

    프로젝트 생성 및 에이전트 설치까지 모두 적용했다면 다음 문서에서 점검 사항을 확인하세요.

  • 에이전트 설정

    에이전트 설정(whatap.conf) 파일에 옵션을 적용해 모니터링을 위한 다양한 기능을 제공합니다. 기본 설정부터 서버 연결 및 데이터 전송 설정, 여러 애플리케이션 서버의 설정 파일 관리 방법, 트랜잭션 추적 등을 포함합니다. 자세한 내용은 다음 문서를 참조하세요.

  • 모니터링 시작하기

    모든 설정을 완료한 다음 애플리케이션 서버를 다시 시작하세요. 에이전트가 정보를 수집하기 시작합니다. 먼저 애플리케이션 대시보드 메뉴에서 모니터링 데이터가 수집되는지 확인하세요. 애플리케이션 대시보드에 대한 자세한 내용은 다음 문서를 참조하세요.

최종 수정: 에