Node.js Agent Guide

제목 : Node.js Agent Guide
작성자 : WhaTap Support
이메일 : support@whatap.io
날짜 : 2019-10-22
버전 : 1.0.0

설명 : 본 문서는 WhaTap node.js 에이전트에 대해 설명합니다.

1. Install

에이전트 설치에 대해서 설명합니다.

1.1. 표준 설치

1.1.1. 에이전트 설치 방식 개요

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

  • 서비스 중인 Node.js 파일의 폴더에 와탭 에이전트 모듈을 설치 합니다.

  • 탭 라이센스 환경설정 ( whatap.conf ) 을 합니다.

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

1.1.2. Npm install

npm ( Node Package Manager )을 통해서 와탭 에이전트를 설치 합니다.

$ npm install whatap --save

1.1.3. 라이센스 및 수집 서버 등록

브라우저를 열고 와탭 서비스 화면에 접속하여 프로젝트 관리화면에서 라이선스를 발급 받습니다. 라이센스 키는 프로젝트별로 귀속되기 때문에, 유출되거나 배포되어서는 안됩니다.

와탭은 라이센스 키에 숨겨진 키를 가지고 에이전트와 서버사이에서 데이터를 암호화 합니다.

node_modules/whatap에 있는 whatap.conf 파일을 루트 디렉토리로 복사 후 라이센스 키를 발급 받은 후 추가해 주세요

whatap.conf
license=x46n3a26be1ah-z2rswcfcvlq2ph-z114c81gfhqpgg
whatap.server.host=52.78.209.94/52.78.224.235

host 주소는 와탭 proxy가 설치된 서버의 주소입니다. '/'를 이용하여 와탭서버중 proxy서버가 실행중인 서버의 모든 주소를 지정합니다.

1.1.4. 코드 작성

루트 디렉토리의 Node.js 애플리케이션에 위와 같이 에이전트 코드를 삽입합니다. ( 예를 들어 express 의 경우 app.js )

var whatap=require('whatap').NodeAgent;
와탭에이전트 코드는 node.js가 기동되고 가장 먼저 실행되어야 합니다.

1.1.5. 실행

애플리케이션을 실행합니다.

$ node app.js

1.1.6. 업데이트

애플리케이션을 중단하고, npm 을 사용하여 업데이트합니다.

$ npm update whatap

애플리케이션을 재시작 합니다.

1.1.7. 중지 (삭제)

소스(ex app.js)에 삽입했던 Agent 코드를 제거합니다. [source,js]

var whatap=require('whatap').NodeAgent; <-- 제거

애플리케이션을 중단하고, npm 을 사용하여 모듈을 삭제 합니다.

$ npm uninstall whatap

1.1.8. 로그 파일

어플리케이션 서버가 실행되면 애플리케이션의 모니터링 정보를 수집하기 시작합니다.

에이전트 로그는 logs/whatap-yyyymmdd.log 형태로 출력됩니다.

1.2. 에이전트 네이밍

와탭은 모니터링 정보 수집 대상인 애플리케이션 서버 식별을 위한 정보로 기본적으로 애플리케이션 서버로부터 수집한 정보를 활용합니다. 기본적으로 활용하는 정보는 애플리케이션 서버 종류, 애플리케이션 서버의 IP, 서비스 포트를 조합하여 애플리케이션 서버를 고유 식별자로 사용하게 되며 필요에 따라 사용자가 지정한 명칭을 사용하거나 패턴을 변경하여 사용하는 것도 가능합니다. 이때에는 꼭 고유한 값이어야 합니다.

1.2.1. 와탭 이름 패턴

애플리케이션 서버로부터 추출한 정보를 활용하는 이유는 애플리케이션 서버 정지, 네트워크 단절 또는 에이전트 문제로 인한 수집 서버와 에이전트의 통신 단절 상태가 복구되었을 경우, 재 접속된 에이전트로부터 송신되는 정보가 기존 에이전트로부터 송신된 정보와의 연속성을 유지하기 위해서 입니다. 와탭이 애플리케이션 서버를 식별하기 위해 사용하는 기본 패턴은 다음과 같습니다.

default환경
NODE-{ip2}-{ip3}
cluster환경
NODE{clusterId}-{ip2}-{ip3}
설정 설명

type

애플리케이션 유형 명(NODE)

ip#

Ip를 '.' 으로 나누었을 때 #번째 자리(0부터)

pid

Application Process Id

hostname

호스트 명

cluster

한 서버에 다중 node.js 기동시 클러스터 Id

1.2.2. 와탭 이름 패턴 변경

환경변수를 통해서 와탭 이름을 변경할 수있습니다.

whatap.conf
process.env.WHATAP_NAME = "NODE-{ip2}-{ip3}";

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

1.2.3. 서버에서 에이전트 네이밍

에이전트 환경을 기반으로 이름을 결정하는 것이 아니라 서버에서 이름을 자동으로 부여하는 방식입니다. node.js 서버가 컨테이너나 PaaS환경에서 동작하는 경우에 활용합니다.

Heroku 환경에서는 재기동시 IP가 계속 변경되기 때문에 새로운 이름이 계속 만들어집니다.
whatap.conf
auto_oname_enabled=true
auto_oname_prefix=nodejs
Env에 설정(app.js)
process.env.WHATAP_LICENSE='x46n3226be1ah-z2rsecfcvlq2ph-z11bc81gfhqpgg';
process.env.WHATAP_SERVER_HOST='52.78.209.94/52.78.224.235';

process.env.auto_oname_enabled=true;
process.env.auto_oname_prefix='mynode';


var whatap=require('whatap').NodeAgent;
env에 설정할때는 require('whatap')보다 먼저 선언되어야 합니다.

auto_oname_prefix는 에이전트 이름의 prefix이다 와탭서버는 auto_oname_prefix에 지정한 이름에 일련번호를 붙이는 방식으로 에이전트이름을 부여한다.

부여된 에이전트 이름
mynode1

1.3. PaaS 애플리케이션

1.3.1. PaaS환경의 제약

PaaS 애플리케이션에서 에이전트를 설치하기 위해서는 제약사항을 고려해야한다.

whatap.conf를 사용할 수 없습니다.

따라서 모든 설정을 소스(app.js)에서 설정해야 합니다.

1.3.2. 라이센스 및 수집 서버 등록

WHATAP_LICENSE와 WHATAP_SERVER_HOST 환경변수에 라이선스와 서버 주소를 설정합니다.

app.js
process.env.WHATAP_LICENSE='x46n3226be1ah-z2rsecfcvlq2ph-z11bc81gfhqpgg';
process.env.WHATAP_SERVER_HOST='52.78.209.94/52.78.224.235';
var whatap=require('whatap').NodeAgent;
...

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

whatap.conf를 사용할 수 없기 때문에 소스에 환경변수로 whatap agent 옵션을 설정해야 합니다.

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;
옵션에 대한 자세한 설명을 Configuration(설정) 부분을 참고 바랍니다.

2. Architecture(구조와 메커니즘)

node.js를 위한 WhaTap 에이전트 구조와 메커니즘에 대해서 설명합니다.

2.1. 에이전트 구성

whatap node에이전트는 소스가 오픈 된 상태로 배포됩니다. npm install을 통해서 소스를 확인할 수있습니다.

모니터링 정보를 수집하기 위한 트레이서, 수집된 정보를 서버에 전송하기 위한 에이전트, npm 설치를 지원하는 파일들로 구성됩니다.

node.js 모니터링 서비스를 구성하는 각 파일의 역할은 다음과 같습니다.

$ROOT/node_modules/whatap

파일명 파일명

whatap.conf

에이전트 설정 파일 샘플 ( 복사해서 라이선스를 입력 )

lib

에이전트, 트레이서 프로그램

README.md

에이전트 설치 매뉴얼

package.json

npm 모듈 환경구성

index.js

main export 선언

2.2. Network & security

와탭은 에이전트에 서버 방향을 TCP 연결 후 모니터링 데이터를 전송합니다.

WhaTap agent to server
Figure 1. 와탭 에이전트 네트웍

에이전트는 하나의 TCP세션을 통해서 데이터 전송과 서버의 제어 요청을 처리합니다. node agent는 UDP를 사용하지 않습니다. node agent에서 와탭 수집서버 방향으로 방화벽을 개방합니다.

2.2.1. 수집서버 주소와 포트

와탭서버는 데이터 리전서버와 프론트서버로 유레카 등등으로 구분하며 데이터 리전에는 다시 Proxy, Yard, Gateway, Keeper등이 있습니다. 에이전트는 그중에 Proxy서버와 통신을 합니다.

node agent에 와탭 서버의 proxy서버의 주소를 지정합니다.(ex whatap.server.host=10.0.3.1/10.0.3.2) 서버 주소를 설정할때는 proxy서버 숫자 만큼 지정합니다. 와탭서버는 설치 방식에 따라서 proxy서버를 1개 혹은 N개를 사용할 수 있습니다.

와탭 Proxy서버는 6600포트에서 리스닝 합니다. 에이전트에서 특별한 설정을 하지 않으면 에이전트는 6600포트로 접속을 시도합니다.

두개의 Proxy서버가 서로 상이한 포트를 사용할 수 없습니다. 여러대의 Proxy서버를 사용하는 경우 리스닝 포트는 동일 해야합니다.
whatap.conf
whatap.server.port=6600

2.2.2. 통신 연결 및 보안

와탭은 퍼블릭 네트웍에서 모니터링 데이터를 수집하는 것을 전제로 설계 되었다. 따라서 모든 모니터링 데이터를 암호화하여 서버로 전송한다.

하지만 많은 데이터를 암호화 전송하는 하는 것은 오버헤드가 유발될 수있고 그래서 와탭은 데이터를 선별적으로 암호화 합니다. 에이전트와 서버 사이의 통신 과정은 다음과 같습니다.

에이전트와 서버간 통신 과정
1. 프로젝트 설치 메뉴에서 라이선스키슬 생성하고 이것을 복사합니다.
2. 라이센스 키에는 비밀키가 포함되어있습니다. 따라서 라이선스키가 외부에 알려지지 안도록 합니다.
3. node.js를 재기동합니다.
4. 와탭에이전트는 서버로 TCP세션을 연결합니다.
5. 라이선스키에 포함된 통신용 비밀키를 가지고 데이터를 암호화하여 새로운 세션용 보안키를 요청합니다.
6. 서버는 에이전트가 요청한 세션용 보안키를 새로 만들어 에이전트에 내려 보냅니다.
7. 세션용 보안키에는 ASC알고리즘용 암호키와 단순암호를 위한 암호키 즉 2개의 암호키를 포함하고 있습니다.
8. 이후에 에이전트는 텍스트와 제어등 중요한 데이터는 ASC암호키를 사용하고 숫자데이터등 상대적으로 안전한 데이터는 단순암호화를
   거쳐 데이터를 서버에 전송합니다.

2.2.3. 에이전트 통신 버퍼

에이전트는 서버 사이의 TCP연결이 지연되는 경우 에이전트 장애가 유발될 수 있기 때문에 수집된 성능데이터를 네트웍에 바로 전송하지 않습니다.

에이전트는 내부에 2개의 통신 버퍼를 가지고 통신합니다.

net_send_queue1_size=512
net_send_queue2_size=1024

Queue1에는 대부분의 성능데이터 특히 정기적으로 전송되는 성능데이터를 버퍼링하고 Queue2는 트랜잭션 프로파일(ProfilePack)과 액티브스택(ActiveStackPack)만 별도로 처리합니다.

에이전트가 큐를 기반으로 서버와 통신함으로 서버가 다운되더라도 일정부분은 에이전트가 메모리를 소비하지만 그이상의 문제를 유발하지 않습니다.

2.2.4. 에이전트 재접속

에이전트는 서버와 연결이 끊어질 경우 매 5~10초 마다 3번의 재연결을 시도합니다. 그후에는 재연결을 포기합니다.

3. Data

와탭의 node 에이전트는 트랜잭션 성능, 주요 성능 통계 그리고 서비스와 자원에 대한 카운터를 수집합니다.

3.1. 트랜잭션 성능 추적

3.1.1. 트랜잭션 시작과 종료

트랜잭션이란 사용자 브라우저의 요청을 처리하기 위한 서버 사이드의 LUW(Logical Unit of Work)를 말합니다. 개별 웹서비스(URL) 요청에 대한 처리과정이 바로 트랜잭션인 것입니다. 웹 어플리케이션에서 트랜잭션은 웹서비스(URL)에 대한 HTTP Request를 받아 Response를 반환하는 과정입니다.

애플리케이션의 성능은 이 트랜잭션들의 성능으로 요약할 수 있습니다.

트랜잭션 성능은 트랜잭션 시작에서 부터 종료시점, 그리고 응답시간및 자원 사용량 혹은 트랜잭션 호출자의 속성등의 정보들을 포함합니다.

기본적으로 트랜잭션 응답 분포와 트랜잭션 통계를 통해서 트랜잭션 성능을 분석할 수있습니다.

트랜잭션의 이름

트랜잭션의 이름은 URL입니다. 단 Get 파라미터(Query String)는 제외 됩니다.

브라우저 요청
http://www.whatap.io/hr/apply.do?name='kim'
트랜잭션 이름
/hr/apply.do
와탭에서는 "웹서비스 이름" 과 "트랜잭션 이름"을 혼용해서 사용합니다. 서비스 특정 URL과 그에 대한 요청을 처리하기 위한 모듈로 볼수있고 트랜잭션 그 요청에 대한 처리 하나를 의미하기 때문에 둘의 이름은 동일하게 URL이라고 할 수있습니다.
트랜잭션 이름 정규화

MSA 기반의 시스템이 발전하면서 URL?파라미터 형식보다는 URL 패스에 파라미터를 넣는 방식을 많이 사용하게 된다.

http://www.whatap.io/hr/kim/apply.do

이렇게 패스파라미터를 그대로 트랜잭션 이름으로 사용하게 되면 통계적 관점의 성능 분석이 어렵게 됩니다. 따라서 정규화할 필요가 있습니다. 와탭은 이때 정규화를 위한 옵션과 기능을 제공하고 있습니다.

whatap.conf
 trace_normalize_urls=/hr/:name/apply.do

위와 같이 설정하면 트랜잭션 이름이 /hello/kim → /hello/:name 이렇게 치환되어 수집됩니다. 만약 대상 url설정은 그대로 두고 기능만off하고자 한다면 다음과 같이 옵션을 지정할 수있습니다. 기본값은 true입니다.

whatap.conf
 trace_normalize_enabled=false
트랜잭션 추적
node는 single 쓰레드를 사용하여 트랜잭션을 처리한다. 각 모듈사이에서 트랜잭션 추적을 위한 컨텍스트 정보를 넘기는데 위치를 놓치는 현상이 발생할 수있다. 처리량이 많은 서비스에서 부분적으로 나타날 수있다.
그런 이유로 해서 트랜잭션별 CPU와 Memory사용량을 추적하는데 정확하지 않다. 즉 전체 프로세스의 CPU와 메모리 사용량을 추적하여 표시하고 있다. 특히 Memory부분은 heap사용량의 변화를 트랜잭션 성능 정보에 포함여 수집하고 있는데 참고용으로만 사용해야한다. 트랜잭션의 시작 시점의 heap사용량과 트랜잭션 종료 시점의 heap사용량의 delta를 수집하고 있기 때문에 개별 트랜잭션과는 무관할 수있다. 다만 heavy트랜잭션에서 heap을 과도하게 사용하는 트랜잭션을 인지하기 위한 용도로 추가되어있다.

3.1.2. 트랜잭션 프로파일

트랜잭션 성능이 트랜잭션 시작과 종료사이의 요약 지표들이나 속성들을 의미한다면 트랜잭션 프로파일은 트랜잭션이 수행되는 과정중이 스텝들을 추적하는 것입니다.

트랜잭션이 느리거나 오류가 있다면 그 원인을 추적하기 위해서 수행 이력을스텝별로 추적할 필요가 있는데 이것을 트랜잭션 프로파일링이라고 합니다.

와탭이 수집하는 스텝의 종류에는 크게 SQL 스텝, HTTP CALL스탭, 메세지 스텝, SOCKET오픈 스텝, DB연결 스텝, 메소드 스텝등이 있습니다.

DBC 스텝

mmemcached, mssql, mysql, pgsql,redis, thrift에 대한 연결에 대한 성능을 포함합니다.

스텝 정보에는 이름,응답시간,에러를 포함합니다.

SQL 스텝

memcached, mogodb, mssql, mysql, pgsql, redis에 대한 성능을 포함합니다.

스탭정보에는 연결정보,SQL문, 에러가 포함되어있습니다.

node.js 에이전트에서는 SQL바인드변수를 추적하지 않습니다.
HTTP Call 스텝

외부 http서비스 호출에 대한 성능을 포함합니다.

스텝 정보에는 url, host, port, 응답시간, 에러가 포함됩니다.

Message 스텝

메세지 스텝을 프로파일을 수집하는 과정에서 비정형적인 모든 구간에 대한 이력을 수집할때 사용도빈디ㅏ. express, file오픈 등등 혹은 사용자도 임의의 위치를 지정하는데 사용 할 수있습니다.

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

var express = require('express');
var app = express();

app.get('/', function (req, res) {
    whatap.profile('user step 1'); // <-- 사용자 지정 메세지 스텝
    res.send('Hello World!');
    whatap.profile('user step 2'); // <-- 사용자 지정 메세지 스텝
 });
NodeAgent.profile 함수를 활용하여 주요지점을 설정함으로 지연 구간을 좀더 정교하게 추적해 갈 수있습니다.
기타 스텝

Socket 스템을 통해서 소켓 오픈 정보를 로깅하거나 사용자 정의 옵션을 통해서 메소드의 응답을 추적할 수 있다. 현실적으로 node.js 에서는 메소드 스텝보다는 message 스템을 통해 지연구간을 break down하는 것이 유리하다.

3.1.3. 사용자 정의 트랜잭션 추적

애플리케이션내에서 비정형적으로 동작하는 내부 로직의 흐름을 추적하기 위해서는 와탭에이전트에는 별도의 수단이 제공됩니다.

var Tracer=require('whatap').Tracer;

var ctx=Tracer.startTrace("트랜잭션 이름");
try{

   //original logic

   Tracer.addStep("profile", "pos1");

   //original logic

}finally{
   Tracer.endTrace(ctx);
}

트랜잭션 시직과 종료 그리고 주요 구간들에 대한 프로파일을 추적할 수 있습니다.

3.2. 통계(리스트 데이터)

와탭 에이전트는 트랜잭션이나 SQL처럼 중요한 서비스 수행이력 통계를 수집합니다. 매 5분마다 목록을 만들고 서버로 전송합니다.

0분,5분,15분 등 매 5분마다 통계를 수집하고 서버로 전송합니다.

3.2.1. 트랜잭션 통계

트랜잭션 통계를 수집합니다. 매 5분마다 최대 5000개의 URL별 수행 통계를 수집하여 서버에 전송합니다. 만약 서로다른 URL의 수가 5분동안 5000개가 넘으면 무시됩니다.

칼럼 설명 타입

hash

URL 해쉬

u4

count

건수

u4

error

에러건수

u4

time_sum

응답시간의 합

u8

time_max

최대 응답시간

u4

sql_count

SQL 수행 건수

u4

sql_time

SQL수행시간의 합

u8

httpc_count

HTTP Call건수

u4

httpc_time

HTTP Call 시간의 합

u8

트랜잭션에 대한 메모리 사용량및 CPU 사용량은 기술적 한계로 수집되지 않고 있으며 SQL fetch건수와 fetch 시간도 수집되지 않습니다.

3.2.2. SQL 수행 통계

5분동안의 SQL 수행 통계를 수집합니다. 5분동안 서로다른 SQL문장이 최대 5000까지만 허용이 됩니다. 만약 하나의 node.js 프로세스에서 한계를 넘는 SQL이발생하면 통계데이터에서는 버려집니다.

칼럼 설명 타입

dbc

DB연결 정보의 Hash

u4

sql

SQL문 Hash

u4

count_total

수행 건수

u4

count_error

에러건수

u4

time_sum

응답시간의 합

u8

time_max

최대 응답시간

u4

service

SQL을 수행한 service중에 하나

u4

service(URL) hash는 5분동안 해당 SQL을 호출한 URL중 하나(마지막 호출 URL)를 분석 활용을 위해 수집합니다.

3.2.3. HTTPCall 수행 통계

5분동안의 Http Call 수행 통계를 수집합니다. 5분동안 서로다른 Http Call문장이 최대 5000까지만 허용이 됩니다. 만약 하나의 node.js 프로세스에서 한계를 넘는 외부 Http Call이 발생하면 통계데이터에서는 버려집니다.

칼럼 설명 타입

url

타겟 URL hash

u4

host

Host or ip

u4

port

Tcp Port

u4

count_total

수행 건수

u4

count_error

에러건수

u4

time_sum

응답시간의 합

u8

time_max

최대 응답시간

u4

service

Http Call을 수행한 service중에 하나

u4

3.2.4. 에러 통계

5분동안 발생한 서비스 에러에 대한 통계입니다. 서로다른 에러+트랜잭션이름을 키로 발생 건수를 수집합니다. 5분당 최대 1000가지 서로다른 에러를 통계화합니다.

칼럼 설명 타입

errorHash

Error hash

u4

service

URL hash

u4

msg

메세지 hash

u4

count

발생 건수

u4

다른 언어에서는 에러 발생 당시의 스택을 첨부하지만 node.js는 기술상의 이유로 수집하지 못합니다.

3.2.5. IP별 호출 건수

IP별로 호출한 트랜잭션 건수을 통계적으로 수집합니다. 5분당 수집가능한 서로다른 IP수는 인스턴스당 최대 70000개 입니다.

칼럼 설명 타입

ip

ip주소

u4

count

건수

u4

3.2.6. UserAgent별 호출 건수

User Agnet 문자열의 Hash별로 호출 건수를 수집합니다. 5분당 수집가능한 서로다른 UserAgent Hash는 인스턴스당 최대 1000개 입니다.

칼럼 설명 타입

hash

hash

u4

count

건수

u4

3.2.7. 트랜잭션 Caller 통계

멀티 서버가 rest 호출로 연결된 경우 Caller와 Callee간의 연관 통계를 수집할수있다. 이 데이터를 수집하기 위해서는 다음의 옵션을 먼저 설정해야 한다.

whatap.conf
mtrace_rate=100
mtrace_spec=v1
stat_mtrace_enabled=true
msa
Figure 2. MSA 시스템

위와 같은 아키텍처에서 caller&callee통계는 api1와 api2에서만 조회할 수있습니다. 사용자 브라우저에서 호출되는 시스템에서는 Caller통계를 조회할 수 없습니다.

하지만 Caller쪽 서버에서 데이터를 전송해야하기 때문에 모든 서버에 적절한설정이 들어가야 합니다.

whatap.conf of [front]
mtrace_rate=100
mtrace_spec=v1
stat_mtrace_enabled=true
whatap.conf of [api1] & [api2]
mtrace_spec=v1
stat_mtrace_enabled=true
언어가 다르더라도 동일하게 동작합니다. 에를들어 api서버들이 java되어도 동일하게 추적됩니다.

수집되는 통계 데이터는 다음과 같습니다. Callee쪽에서 조회되어야합니다.

칼럼 설명 타입

caller_pcode

Caller의 프로젝트(와탭) 코드

u8

caller_spec

Caller의 버전 문자열 hash

u4

caller_url

Caller의 URL hash

u4

spec

Callee의 버전 문자열 hash

u4

url

Callee URL hash

u4

count

수행 건수

u4

error

에러건수

u4

time

응답시간의 합

u8

3.2.8. 트랜잭션 도메인 통계

와탭에이전트는 도메일별 트랜잭션 통계를 수집할 수 있습니다. 하나의 서버에 비즈니스적인 이유등으로 여러개의 도메인을 분리하여 서비스 하는 시스템에서는 도메인 별 분석이 필요할 수있다. 그래서 front서버에서 유효하다

whatap.conf
stat_domain_enabled=true

수집되는 데이터는 도메인별 URL의 처리 현황을 파악할 수있습니다

칼럼 설명 타입

domain

서비스 도메인 hash

u4

url

트랜잭션 URL hash

u4

count

수행 건수

u4

error

에러건수

u4

time

응답시간의 합

u8

3.3. 성능 카운터

와탭 에이전트가 수집하는 성능카운터는 크게 3가지로 분류할 수있습니다.

Counters
  • User : 실시간 사용자 혹은 방문사용자

  • Service : 트랜잭션,SQL,외부호출 건수및 응답, 에러율등

  • Resource : 시스템,프로세스 자원 사용량

3.3.1. User Counter

사용자는 모니터링 대상 시스템을 사용하는 클라이언트를 말한다. 클라이언트에는 다른시스테 또한 포함될 수있지만 일반적으로는 브라우저를 기준으로 사용자를 카운팅한다.

웹시스템 성능에서 사용자는 부하를 발생시키는 시작이기때문에 중요하다 사용자 추적을 위해서는 사용자는 어떤 기준으로 구분할 것이며 어떻게 카운팅 할 것인가에 대한 고려가 필요하다

사용자 구분

와탭 에이전트 사용자를 구분하기 위해 다양한 옵션을 제공합니다.

RemoteIP

가장 기본은 remote ip를 사용하여 사용자를 구분하는 것입니다. 하지만 remote ip 실제 사용자를 구분하는데 한계가 있습니다

Cookie(WHATAP)

쿠키를 사용하여 사용자를 구분할 수있습니다. 모든접속 클라이언트에 대한 UUID가 "WHATAP"이라는 쿠키에 셋팅합니다.

whatap.conf
trace_user_using_ip=false
Header Key

http header에 전달되는 값으로 사용자를 구분할 수있습니다. .whatap.conf

user_header_ticket=USER
사용자 카운팅

사용자를 카운팅하는 방법에 따라서 다른 목적으로 사용될 수있다. 동시 사용자는 현재 시스템을 사용하는 사용자의 수를 알기 위해서 측정하고 일일 액티브 사용자는 하룻동안 해당 서비스에 관심을 갖는 사용자가 몇명인지에 대한 비즈니스적인 관리를 위해 측정합니다.

실시간 사용자

최근 5분 동안 사용자 수를 카운팅합니다. 매5초마다 shifting하면 사용자를 카운팅합니다. 각 서버에서 카운팅된 숫자는 HyperLogLog알고리즘을 통해서 머지됩니다.

일일 방문(액티브) 사용자(DAU)

하룻동안 시스템에 접속한 사용자를 카운팅합니다. 24시간 동안 발생한 사용자를 hyperloglog를 통해서 계산합니다.

와탭에서는 장기간 사용자를 카운팅 하기 위해 사용자데이터에 대한 byte block을 서버로 수집합니다. 이 데이터를 hyperloglog로 머지하면 이론적으로 한달 이상의 맥티브 사용자를 계산 할 수 있습니다.

3.3.2. Service Counter

서비스 카운터에는 트랜잭션과 트랜잭션이 사용하는 SQL혹은 외부호출등에 대한 건수 응답시간 에러건수 등에 대한 성능지표가 표함된다.

Transaction Counter

트랜잭션을 수행하면 측정하는 카운터입니다.

  • 건수

  • 응답시간

  • 에러건수

Active Transaction Counter

진행중인 트랜잭션의 수를 카운팅합니다.

  • 건수

  • Active Status
    진행 상태는 METHOD,SQL,HTTPC,DBC,SOCKET 5가지 상태로 고정되어있습니다.

    1. METHOD - 일반 함수를 호출하는 상태

    2. SQL - db sql을 수행중인 상태

    3. HTTPC - 외부 Http Api(서비스)를 호출중인 상태

    4. DBC - DB연결을 요청한 상태, 일반적으로 Pool에서 가져옴

    5. SOCKET - TCP세션을 Connecting 중인 상태

SQL

SQL 수행 현황을 카운팅합니다.

  • 건수

  • 응답시간

  • 에러 건수

  • 패치 건수

HTTP Call

외부 Http 호출에 대한 현황을 카운팅 합니다.

  • 건수

  • 응답시간

  • 에러 건수

3.3.3. Resource Counter

서버자원 혹은 node 프로세스 내부의 자원 사용량을 카운팅합니다.

서버 자원 사용량
  • CPU

  • Memory

  • Disk

  • Process Cpu

  • Heap Total

  • Heap Used

4. 에이전트 제어와 상태 조회

각 node.js 프로세스 별로 에이전트 동작을 제어하거나 상태를 조회할 수 있습니다.

4.1. 부트 환경

에이전트는 시작하면 주요환경 정보를 모아 서버로 전송합니다. 이정보는 기동시의 에이전트 환경 상태를 확인할때 사용될 수있습니다. Yard서버에 저장해 두기 때문에 에이전트가 종료되어도 조회할 수있습니다.

와탭의 버전,OS이름 node버전, uptime등의 정보들을 조회할 수 있습니다.

4.2. 환경 변수

에이전트에서는 현재의 환경 변수를 조회할 수있습니다. 화면의 요청을 받았을때 조회됩니다. 따라서 프로세스가 정지된 상태에서는 조회할 수 없습니다.

4.3. 모듈 의존성

현재 로딩되어 사용되고 있는 모듈과 버전을 조회할 수있습니다.

4.4. 설정

에이전트 실행옵션을 설정할 수있습니다. whatap.conf에 값을 운영중에 변경할 수 있습니다.

4.5. 에이전트 로그

현재 에이전트 HOME에서 ./logs/에 기록된 로그를 조회합니다.

5. Configuration

5.1. 에이전트 기능제어

whatap.enabled

default: true
전체 기능을 활성화한다. 단 false가 되어도 서버와 최소한의 통신을 유지하기 위한 정보는 전송됩니다.

transaction_enabled

default: true
whatap.enabled==false이면 무시됨(false)
트랜잭션 추적 기능을 활성화합니다.

counter_enabled

default: true
whatap.enabled==false이면 무시됨(false)
성능 카운터(트랜잭션, 리소스 등) 추적을 활성화합니다.

stat_enabled

default: true
whatap.enabled==false이면 무시됨(false)
통계 정보 추적을 활성화한다. 5분마다 트랜잭션, SQL, HTTPCALL, UserAgent, Client IP등의 통계 데이터가 수집되는데 이들 정보의 수집이 중단됩니다.

license

default:
에이전트가 속한 프로젝트의 PCODE 서버와 보안 통신을 위한 암호키를 포함하고 있는 보안 문자열을 설정합니다.

encrypt_level

default: 2
값의 범위는 1,2,3중에 하나를 지정할 수 있습니다. 와탭은 데이터에 따라 다른 암호화 알고리즘을 적용합니다. 주로 Text는 보안레벨을 높게 적용하고 단순 숫자 데이터는 보안레벨을 낮게 적용합니다. 이러한 보안레벨을 적용할 때 일괄적으로 전체적인 보안 레벨을 보다 높게 혹은 보다 낮게 적용할 수 있는데 그것을 지정하는 옵션입니다.

5.2. 에이전트 네트워크 설정

whatap_server_host

default: 127.0.0.1, 127.0.0.1
수집서버 아이피를 지정한다. 콤마(,)로 분리하여 하나 혹은 2개를 지정할 수 있습니다. 단 여기서 지정하는 서버에는proxy서버가 리스닝하고 있어야 합니다.

whatap_server_port

default: 6600
수집서버 PORT를 지정한다. 포트는 하나만 지정할 수 있습니다. 따라서 whatap_server_host에 지정된 수집서버들은 동일 PORT를 사용해야 합니다.

tcp_so_timeout

default: 60000
수집서버와 통신할 때 TCP 세션의 idle 타임아웃 값을 지정합니다.

tcp_connection_timeout

default: 3000
수집서버와 통신 세션을 연결할 때 연결 지연 가능 시간을 지정합니다.

net_send_max_bytes

default: 5242880 (5*1024*1024=5M)
에이전트가 데이터를 수집하고 네트워크로 한번에 전송할 수 있는 최대 byte 크기입니다.

net_send_queue1_size

default: 512
에이전트는 두개의 네트워크 큐를 사용한다. 1번큐에는 프로파일을 제외한 모든 데이터 전송 시 사용됩니다.

net_send_queue2_size

default: 1024
에이전트는 두개의 네트워크 큐를 사용한다. 2번큐에는 프로파일을 전송하는데 사용됩니다.

5.3. 프로파일링 옵션

profile_http_header_enabled

default: false
http헤더 정보를 프로파일에 출력하고자 할 때

profile_http_header_url_prefix

default: /
http헤더를 프로파일에 출력할 때 대상 URL에 대한 prefix

profile_http_parameter_enabled

default: false
http 파라미터를 프로파일링을 활성화한다. 단 파라미터는 별도 보안키를 입력해야 조회할 수 있습니다.  

profile_http_parameter_url_prefix

default: /
http파라미터를 프로파일링 활성화할 때 적용될 URL prefix를 설정한다.

profile_basetime

default: 1000
트랜잭션의 처리 시간이 이 값에 미치지 못하는 경우 프로파일 정보는 수집되지 않습니다. 단 5분당 최초 호출된 URL, 에러 트랜잭션은 수집됩니다.

5.4. 사용자 추적 옵션

trace_user_enabled

default: true
실시간 사용자를 추적할지를 결정합니다.

trace_user_using_ip

default: true
실시간 사용자를 추적할 때 사용자 구분을 IP로 합니다.

trace_user_cookie_limit

default: 2048
사용자 구분을 쿠키로 하는 경우 새로운 사용자가 접속하면 UUID를 쿠키로 지정하여 사용자를 구분합니다. 그런데 기존의 쿠키가 너무 많은 경우 쿠키 오버플로어가 날 수 있습니다. 이것을 피하기 위해 limit를 지정합니다.

user_header_ticket_enabled

default: false
사용자 아이디를 http 헤더의 특정 값으로 구분하고 싶을 때 사용합니다. 모바일에서 접속할 때 전달되는 경우가 많습니다.

user_header_ticket

default:
사용자 아이디를 http 헤더의 특정 값으로 구분하고 싶을 때 사용하는 키 명칭을 지정합니다.

trace_http_client_ip_header_key

default:
사용자의 실제 접속 아이피가 header에 별도로 전달되는 경우 해당 header key를 지정합니다.

5.5. 트랜잭션 추적 옵션

trace_background_socket_enabled

default: true
소켓(TCP) 연결이 오픈될 때 트랜잭션이 시작된 상황에서만 오픈을 추적하는데 트랜잭션이 아닌 백그라운드 쓰레드에 의한 소켓이 오픈될 때도 추적합니다.

trace_transaction_name_header_key

default: null
트랜잭션의 이름을 header에서 전달되는 값을 URL에 추가합니다

trace_service_port_enabled

default: false
트랜잭션의 이름에 port 번호를 추가한다.

trace_active_transaction_yellow_time

default: 3000
액티브 트랜잭션의 아크이퀄라이저에서 노란색 구간의 응답기준

trace_active_transaction_red_time

default: 8000
액티브 트랜잭션의 아크이퀄라이저에서 빨간색 구간의 응답기준

trace_normalize_urls

default:
트랜잭션 URL을 파싱하여 정규화한다. 호출URL 패턴을 파싱하여 패스파라미터를 제거한다. ex) /a/:v/b 라고 선언하면 a/123/b ⇒ a/:v/b로 치환합니다 여러 개를 등록할 때는 콤마(,)를 사용합니다.

trace_normalize_enabled

default: true
트랜잭션 URL을 파싱하여 정규화하는 기능을 활성화합니다

trace_auto_normalize_enabled

default: true
트랜잭션 URL 정규화할때 패턴값을 어노테이션에서 추출하여 자동으로 파싱하는 기능을 활성화합니다.

web_static_content_extensions

default: js, htm, html, gif, png, jpg, css, swf, ico
스태틱 컨텐츠를 판단하는 확장자를 설정합니다. 여기에 설정된 확장자를 가진 트랜잭션들은 프로파일 추적과 카운팅이 제외됩니다.

profile_error_sql_time_max

default: 30000
SQL수행후 수행시간이 여기서 지정한 값을 초과하면 TOO SLOW 에러로 처리됩니다.

5.6. 로그 옵션

log_rotation_enabled

default: true
에이전트 로그파일을 매일 변경합니다.

log_keep_days

default: 7
로그파일 보관기간을 설정합니다.

5.7. 운영 설정

realtime_user_thinktime_max

default: 300000
실시간 사용자를 측정할 때 사용자로 인정되는 호출간격을 지정합니다.

time_sync_interval_ms

default: 300000
에이전트는 이 옵션에서 지정한 시간에 한번씩 서버와 통신하면서 시간을 맞춥니다.

5.8. 트랜잭션 추적 고급 옵션

mtrace_rate

default: 0
최초 트랜잭션이 발생할 때 발급받는 MTID(Multi Transaction ID)의 발급 비율을 설정하는 옵션입니다. 0에서 100까지 지정할 수 있습니다. MTID를 추적하면 등록된 모든 애플리케이션 간의 호출을 확인 할 수 있습니다. 같은 프로젝트에 속한 애플리케이션은 Caller & Callee기능을 통해 트랜잭션의 프로파일을 바로 확인 가능합니다.

mtrace_spec

default: v1
현 인스턴스의 애플리케이션 버전을 지정합니다. 임의의 문자열을 지정할 수 있습니다. 이 데이터는 호출통계를 위해 사용됩니다.

stat_mtrace_enabled

default: false
MSA아키텍처에서 서비스간의 호출 통계를 활성화합니다. 이 값이 true가 되면 외부 호출을 할때 자신의 정보를 전송합니다.

stat_domain_enabled

default: false
클라이언트의 접속 도메인별 트랜잭션 통계를 수집하는 기능을 활성화 합니다.