WhaTap Docs | Python Agent Guide Whatap Support support@whatap.io 2019-03-11 1.0.0

본 문서는 WhaTap Python Monitoring 에이전트에 대해 설명합니다.

Python 에이전트 가이드

1. Install

에이전트 설치부터 실행, 업데이트 및 종료에 대해 설명하며, 나아가 설치 중 발생할 수 있는 오류에 대한 사례들을 설명합니다.

1.1. 에이전트 실행 및 모니터링 개요

와탭 Python 애플리케이션 모니터링은 Python 기반 웹 애플리케이션 서버 모니터링 서비스를 제공합니다.

1.1.1. 에이전트 구성

에이전트의 구성은 수집 서버, 에이전트, 그리고 수집서버로 이루어집니다.

  • 수집서버

    • 에이전트가 수집한 애플리케이션의 성능 데이터를 수집, 저장 및 통계 정보 추출하고 이를 사용자에 효율적인 방법으로 제공합니다. 수집서버는 지역(Region)별로 설정이 가능합니다. 지역(Region)별로 수집서버의 주소가 다르게 할당 되므로 사용자가 선택한 지역(Region)에 따라 수집서버 주소는 다를 수 있습니다. 지역(Region) 선택은 프로젝트 생성시에 함께 설정합니다.

  • 에이전트

    • 애플리케이션 서버에 설치되어, 애플리케이션 성능 데이터를 수집하여 서버로 전송합니다.

  • 트레이서

    • 애플리케이션 코드에서 프로파일링 데이터를 추적합니다.

  • 네트워크

    • 와탭 모니터링 에이전트는 모니터링 정보를 수집하여 서버에 데이터 전송하기 위하여 외부통신(TCP)을 위한 6600 포트와 내부통신(UDP)을 위한 6600 포트를 사용합니다. 내부 포트가 충돌이 나는 경우, net_udp_port 옵션을 통해 포트 변경이 가능합니다.

530

1.1.2. 에이전트 구성 파일

Table 1. 에이전트 구성 파일의 종류

파일명

설명

whatap.conf

에이전트 설정 파일

paramkey.txt

보안키를 필요로 하는 옵션에서 참조하는 파일

설정 파일
  • 파일명: whatap.conf

    • 에이전트 설정 기본 필수 파일입니다. 에이전트와 관련된 옵션은 모두 whatap.conf에서 설정이 가능합니다.

보안키 파일
  • 파일명: paramkey.txt

    • 추적한 트랜잭션의 프로파일정보로 수집한 HTTP와 SQL데이터의 파라미터 정보를 확인 하는데 사용합니다. 보안키를 파일에 저장하고 실제 수집된 데이터를 브라우저에서 확인 하고자 할 때 파일에 저장해 둔 보안키를 입력해야 조회 할 수 있습니다. 파일의 내용을 직접 변경하여 보안키 수정이 가능합니다.

  • 관련 옵션:

    • profile_http_parameter_enabled (default: false)

    • profile_sql_param_enabled (default: false)

1.2. 표준 설치

와탭 APM 모니터링 서비스를 사용하기 위해서는 모니터링 대상 애플리케이션 서버에 와탭 APM 모니터링 에이전트를 설치해야 합니다.

와탭 APM 모니터링 에이전트 설치 방법은 whatap.io 사이트에서 압축된 에이전트 파일을 다운로드 받아 서버 임의의 위치에 압축을 풀어 실행하는 것만으로 설치가 완료됩니다.

1.2.1. 설치 절차

프로젝트 생성
project main
Figure 1. 프로젝트 생성 페이지

서버를 등록하기 위해 우선 프로젝트를 생성합니다. 추가 버튼을 선택하면 아래와 같이 프로젝트 생성 창이 나타납니다. 설치하려는 Python 아이콘을 선택한 뒤, 희망하는 프로젝트명과 데이터 서버 지역(Region), 소속하게 될 그룹을 선택한 뒤 프로젝트를 생성합니다.

project widget
Figure 2. 프로젝트 이름 지정 및 수집 서버 지역 선택
라이센스 발급
560

프로젝트 관리화면에서는 우선적으로 라이선스를 발급 받습니다. 라이센스 키는 프로젝트별로 귀속되기 때문에, 유출되거나 배포되어서는 안됩니다. 반드시 본인 프로젝트에 서버를 등록할 때에만 이용하시기 바랍니다.

WHATAP_HOME 기본 경로 설정

로그와 설정파일 경로를 위한 $WHATAP_HOME 경로를 지정해 주세요. whatap 디렉토리를 새로 생성하는 것을 권장합니다.

$ export WHATAP_HOME=[PATH]
라이센스 키 및 수집서버 설정

다음 명령어를 실행하면 $WHATAP_HOME에 지정한 경로에 바로 whatap.conf 파일이 생성 및 설정 됩니다.

$ whatap-setting-config
 --host [HOST_ADDR]
 --license [LICENSE_KEY]
 --app_name [APPLICATION_NAME]
 --app_process_name [APP_PROCESS_NAME ex]uwsgi, gunicorn..]
설정 확인

다음과 같이 설정파일이 잘 생성되어 있는지 확인 해 주세요.

$ cat $WHATAP_HOME/whatap.conf
명령어 실행

WHATAP_AGENT시작 커맨드와 함께 애플리케이션 서버를 재시작해주세요.

$ whatap-start-agent [YOUR_APPLICATION_START_COMMAND]
애플리케이션 재 시작

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

에이전트 프로세스 확인

다음과 같은 명령어를 통하여 동작중인 와탭 Python 에이전트 프로세스를 확인 할 수 있습니다.

$ ps –ef | grep whatap_python
로그 확인

서비스 재시작시 정상적으로 로그가 뜨는 화면을 통해 정상 구동 여부를 확인합니다. whatap-python 패키지를 설치한 후 에이전트 사용안내에 따라 애플리케이션 서버를 재시작 하면 다음과 같은 로그를 확인할 수 있습니다. 에이전트 등록 후 수집과 관련된 로그는 $WHATAP_HOME/logs 디렉토리에서 확인 할 수 있습니다. (whatap-hook.log / whatap-boot-[DATE].log)

_      ____       ______Python-AGENT
| | /| / / /  ___ /_  __/__ ____
| |/ |/ / _ \/ _ `// / / _ `/ _ \
|__/|__/_//_/\_,_//_/  \_,_/ .__/
                          /_/
Just Tap, Always Monitoring
WhaTap Python Agent version 0.1.33, 20181017

WHATAP_HOME: /Users/kimjihye/workspace/whatap/python-sample/whatap
Config: /Users/kimjihye/workspace/whatap/python-sample/whatap/whatap.conf
Logs: /Users/kimjihye/workspace/whatap/python-sample/whatap/logs
모니터링 확인

서버에서 정상적으로 로그가 올라온 것을 확인한 뒤, 콘솔에 정상적으로 등록되어 있는 여부를 확인하기 위해 해당 프로젝트의 ‘서버’ 메뉴에 올라온 해당 애플리케이션 서버의 명칭을 확인합니다.

260
  • 애플리케이션명은 {type}-{ip2}-{ip3}-{process} 의 형태의 식별ID가 부여됩니다.

애플리케이션 재 시작

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

에이전트 프로세스 확인

다음과 같은 명령어를 통하여 동작중인 와탭 Python 에이전트 프로세스를 확인 할 수 있습니다.

$ ps –ef | grep whatap_python
에이전트 삭제

에이전트 삭제를 원하는 경우, 다음 절차를 진행 해 주세요..

  1. 애플리케이션 서버 재시작 시 함께 추가한 WHATAP_AGENT시작 커맨드를 삭제 합니다.

  2. whatap-stop-agent 명령어로 와탭 Python 에이전트 프로세스를 종료합니다.

    $ whatap-stop-agent
  3. 프로세스가 죽지 않는 경우 다음 명령어를 통해 프로세스를 종료시켜 주세요.

    $ killall whatap-python
  4. 프로세스가 정삭적으로 죽었는지에 대한 확인은 다음 명령어로 확인 가능합니다.

    $ ps -ef|grep whatap_python
패키지 설치 확인/업데이트/제거
패키지 설치 확인

다음과 같은 명령어를 통하여 설치된 와탭 Python 에이전트 패키지를 확인 할 수 있습니다.

$ pip list | grep whatap-python
패키지 업데이트

다음과 같은 명령어를 통하여 설치된 와탭 Python 에이전트 패키지를 업데이트 할 수 있습니다.

$ pip install –U whatap-python

또는

$ pip install –U whatap-python==[특정 버전]
패키지 제거

다음과 같은 명령어를 통하여 설치된 와탭 Python 에이전트 패키지를 제거 할 수 있습니다.

$ pip uninstall whatap-python

1.3. 에이전트 네이밍

와탭 모니터링 서비스에서 모니터링 대상을 포괄적인 의미로 오브젝트라는 명칭을 사용하며 에이전트와 혼용해서 사용하기도 합니다. 모니터링 대상 즉 오브젝트를 구분하기 위해서는 이름을 구분해야 합니다. 와탭은 오브젝트 이름과 오브젝트 아이디를 통해서 대상을 구분합니다.

오브젝트(에이전트)이름은 프로젝트 단위로 유일해야 합니다.
오브젝트 아이디 = CRC32(오브젝트 이름) 입니다.
오브젝트 아이디/이름이 바뀌면 이전 데이터와 연결되지 않습니다.

1.3.1. 이름 결정 방식

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

에이전트 이름 식별

와탭은 모니터링 정보 수집 대상인 애플리케이션 서버 식별을 위한 정보로 기본적으로 애플리케이션 서버로부터 수집한 정보를 활용합니다. 기본적으로 활용하는 정보는 애플리케이션 서버 종류, 애플리케이션 서버의 IP, 서비스 포트를 조합하여 애플리케이션 서버를 고유 식별자로 사용하게 되며 필요에 따라 사용자가 지정한 명칭을 사용하거나 패턴을 변경하여 사용하는 것도 가능합니다. 이때에는 꼭 고유한 값이어야만 합니다. 애플리케이션 서버로부터 추출한 정보를 활용하는 이유는 애플리케이션 서버 정지, 네트워크 단절 또는 에이전트 문제로 인한 수집 서버와 에이전트의 통신 단절 상태가 복구되었을 경우, 재접속된 에이전트로부터 송신되는 정보가 기존 에이전트로부터 송신된 정보와의 연속성을 유지하기 위해서 입니다. 와탭이 애플리케이션 서버를 식별하기 위해 사용하는 기본 패턴은 다음과 같습니다.

  • default: {type}-{ip2}-{ip3}-{process}

기본 패턴에 대한 변경은 whatap.conf에서 설정에서 가능합니다.

  • object_name default: {type}-{ip2}-{ip3}-{process}

Table 2. 패턴 옵션

설정

설명

type

app_name

ip#

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

process

app_process_name

hostname

호스트 명

1.4. 애플리케이션 서버 별 적용절차

1.4.1. 사용 예

기본
예제
$ whatap-start-agent python manage.py runserver
uWSGI
예제 1
$ whatap-start-agent uwsgi --ini myapp.ini
예제 2
description "uWSGI application server handling myapp"

start on runlevel [2345]
stop on runlevel [!2345]

exec whatap-start-agent [YOUR_APPLICATION_START_COMMAND]
또는
exec env WHATAP_HOME=[PATH] [절대 경로]/whatap-start-agent [YOUR_APPLICATION_START_COMMAND]
예제 3
$ whatap-start-agent gunicorn myapp.wsgi
Gunicorn
예제 1
NAME="uwsgi"
PATH=/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
DAEMON=/usr/local/bin/uwsgi

########## WHATAP_AGENT_CONF ##########
WHATAP_HOME=[PATH]
WHATAP_AGENT=[절대 경로]/whatap-start-agent
...
do_start(){
    env WHATAP_HOME=$WHATAP_HOME $WHATAP_AGENT [YOUR_APPLICATION_START_COMMAND]
}
예제 2
description "Gunicorn application server handling myapp"

start on runlevel [2345]
stop on runlevel [!2345]

exec whatap-start-agent [YOUR_APPLICATION_START_COMMAND]
또는
exec env WHATAP_HOME=[PATH] [절대 경로]/whatap-start-agent [YOUR_APPLICATION_START_COMMAND]
예제 3
NAME="gunicorn"
PATH=/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
DAEMON=/usr/local/bin/gunicorn

########## WHATAP_AGENT_CONF ##########
WHATAP_HOME=[PATH]
WHATAP_AGENT=[절대 경로]/whatap-start-agent
...
do_start(){
    env WHATAP_HOME=$WHATAP_HOME $WHATAP_AGENT [YOUR_APPLICATION_START_COMMAND]
}
Supervisor
예제
[program:app-uwsgi]
environment = WHATAP_HOME=[PATH]
command = [절대 경로]/whatap-start-agent /usr/local/bin/uwsgi --ini /home/blog/backend/config/uwsgi.ini

[program:nginx-app]
command = /usr/sbin/nginx
WSGI 애플리케이션 직접 구현
예제
import whatap

@whatap.register_app
def simple_app(environ, start_response):
    """Simplest possible application object"""
    status = '200 OK'
    response_headers = [('Content-type', 'text/plain')]
    start_response(status, response_headers)
    return ['Hello world!\n']

1.5. 에이전트 로그

애플리케이션 서버가 실행되면 애플리케이션의 모니터링 정보를 수집하기 시작합니다. 로그의 위치는 $WHATAP_HOME의 logs디렉토리에 다음과 같은 파일로 생성됩니다.

1.5.1. 로그파일 종류

로그 파일은 2가지로 종류는 다음과 같습니다.

  • whatap-boot-[DATE].log : 데이터 수집 로그

  • whatap-hook.log : 데이터 수집 로그

정상 동작 확인

다음은 정상 동작하는 경우의 로그 예 입니다.

_      ____       ______Python-AGENT
| | /| / / /  ___ /_  __/__ ____
| |/ |/ / _ \/ _ `// / / _ `/ _ \
|__/|__/_//_/\_,_//_/  \_,_/ .__/
                          /_/
Just Tap, Always Monitoring
WhaTap Python Agent version 0.1.33, 20171017

WHATAP_HOME: /Users/kimjihye/workspace/whatap/python-sample/whatap
Config: /Users/kimjihye/workspace/whatap/python-sample/whatap/whatap.conf
Logs: /Users/kimjihye/workspace/whatap/python-sample/whatap/logs

1.6. 설치 에러 대응

1.6.1. 방화벽 설정 확인

와탭 서버에 대한 TCP 아웃바운드 방화벽이 설정되어 있으면 모니터링 정보를 서버로 전송 할 수 없으므로 방화벽 차단을 해제해야 합니다.

방화벽 확인 방법 (telnet 서버IP 서버포트)

telnet 명령 수행 시 하기와 같은 접속 관련 정보가 표시되어야 정상입니다.

$ telnet 52.193.60.176 6600
Trying 52.193.60.176...
Connected to 52.193.60.176.
Escape character is '^]'.
  • 수집 서버 정보는 에이전트 설치 메뉴에서 확인할 수 있습니다.

1.6.2. Permission denied 에러 발생 시

와탭 파이썬 모니터링을 사용하기 위해서는 다음과 같은 권한 필요 합니다.

  • 와탭 설정을 위한 $WHATPA_HOME/whatap.conf 파일의 읽기 및 쓰기 권한

  • 와탭 로그를 위한 $WHATPA_HOME/logs 디렉토리와 하위 파일의 읽기 및 쓰기 권한

권한 문제가 발생하는 경우(Permission denied error), 다음과 같이 $WHATPA_HOME에 권한을 부여합니다.

$ echo `sudo chmod -R 777 $WHATAP_HOME`

1.6.3. 프로젝트에 에이전트가 등록되지 않는 경우 모니터링 데이터 수집이 이루어지지 않는 경우

로그 파일($WHATAP_HOME/logs/)을 확인 한 후 각각의 문제에 대하여 다음과 같이 문제를 해결 할 수 있습니다.

  • whatap-hook.log

    • CONF FILE ERROR: 설정파일 생성 권한이 없습니다. 파일을 만들어 주세요.

    • CONF READ ERROR: 설정파일은 있으나 리드권한이 없습니다. 권한을 주어야 합니다.

    • LOG FILE ERROR: 로그 디렉토리 생성 권한이 없이 없습니다. 디렉토리를 만들어 주세요.

    • LOGGING ERROR: 로그 디렉토리는 있으나, 쓰기 권한 없습니다. 권한을 주어야 합니다.

  • whatap-boot-[DATE].log

    • license or whatp.server.host error: 라이선스키 또는 수집서버 주소가 잘못되었습니다

포트 충돌이 발생하는 경우

내부 통신을 하는 에이전트는 기본으로 UDP 6600포트를 사용합니다. 내부 포트가 충돌이 나는 경우, net_udp_port=xxx 옵션으로 포트를 변경 할 수 있습니다

$WHATAP_HOME 환경 변수가 설정되지 않는 경우
Apache HTTPD

아파치로 웹 서버 구동하는 경우 환경변수 설정을 다음과 같이 해 주어야 합니다.

<VirtualHost *:80>
    #ServerName
    #DocumentRoot

        SetEnv WHATAP_HOME "application path"
    # Directory
</VirtualHost>
수동으로 환경변수 설정 하는 경우

필요에 따라서는, 다음과 같이 수동으로 환경 변수를 설정 해 주어야 합니다.

---
import os
os.environ.setdefault("WHATAP_HOME", [application path]")
import whatap
---

1.6.4. FAQ

1.6.5. 제약 사항

1.7. Advanced Feature

1.7.1. 서버명을 임의로 부여하여 관리하고 싶은 경우

에이전트는 애플리케이션 서버 종류와 애플리케이션 서버의 IP, 서비스 포트를 사용하여 자동으로 서버명을 부여합니다.

애플리케이션명 지정 옵션

기본 패턴에 대한 변경은 whatap.conf에서 설정에서 가능합니다.

  • object_name default: {type}-{ip2}-{ip3}-{process}

애플리케이션명 패턴

프로젝트에 등록된 애플리케이션 서버별로 동일한 이름이 사용되면 안되므로 서버명을 고정으로 사용해서는 안됩니다. Internal ip address로 인해 서버 ip가 중복되는 경우는 애플리케이션 서버명을 그룹 단위로 패턴화하여 적용할 수 있습니다.

Table 3. 패턴 옵션

설정

설명

type

app_name

ip#

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

process

app_process_name

hostname

호스트 명

1.7.2. AES 256 암호화 적용

와탭 APM 에이전트는 수집된 데이터를 암호화하여 서버로 전송합니다. 데이터의 중요도나 설정에 따라 이를 변경할 수 있습니다. 기본적으로 XOR 연산과 AES 알고리즘을 통한 암호화를 사용하며 평문을 128비트 단위로 나누어 암호화, 복호화를 수행하며, 사용자의 설정에 따라 256비트까지 확장할 수 있습니다.

설정

와탭 APM 에이전트가 설치된 디렉토리에서 whatap.conf 파일에 아래와 같은 설정을 추가합니다.

cypher_level=256 설정을 추가합니다.
license=[라이센스 키]
whatap.server.host=52.78.209.94/52.78.224.235
cypher_level=256
재실행

설정을 추가한 후 WAS를 재기동합니다.

1.7.3. 제약 사항

복수 리전을 단일 프로젝트로 선택 불가

whatap.io 사이트에서 프로젝트 생성 시, 지역(Region)은 중복 선택이 불가하며 복수의 지역(Region)을 활용하는 경우 별도의 프로젝트를 생성해야 합니다.

Cloud 환경과 같이 복수의 지역(Region)에 서버가 존재하는 경우, 네트워크 latency 등 성능 정보 수집 상의 제약 사항을 회피하기 위하여 지역(Region)단위로 수집 서버를 위치시켜야 합니다. 와탭은 고객 요구 사항에 부응하기 위하여 지역(Region)별로 수집 서버를 구축합니다.

에이전트 이름(ONAME)중복 사용 불가

와탭 APM 모니터링은 에이전트의 식별을 위한 용도로 에이전트의 IP 주소와 Port 정보를 활용하기 때문에 사용자 환경의 모니터링 대상 애플리케이션 서버가 동일 IP, 동일 Port를 사용하는 경우 와탭 서버에서 해당 서버 인스턴스를 구분 할 수 없게 됩니다.

  • 서버 인스턴스가 동적으로 확장되는 환경이 아니라면’서버명을 임의로 부여하여 관리하고 싶은 경우’를 참조하여 애플리케이션 식별을 위한 명칭을 직접 지정하는 방식을 통해 우회 할 수 있습니다.

  • 와탭에서는 현재 모니터링 대상 애플리케이션이 internal address 또는 네트워크 가상화로 인해 중복된 IP를 사용할 경우,’서버명을 임의로 부여하여 관리하고 싶은 경우’를 참고하여 별도의 애플리케이션명 패턴을 활용합니다.

1.8. 설치 환경

1.8.1. 운영체제

다음 운영체제 환경에서 에이전트를 실행 할 수 있습니다.

  • CentOs 6 이상(64bit)

  • Ubuntu 14 이상(64bit)

1.8.2. 지원 버전

  • Python2.7이상 & Python3.3이상

  • WSGIApplication

2. Data

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

2.1. 트랜잭션 성능 추적

2.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

2.1.2. 트랜잭션 프로파일

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

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

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

DB연결 스텝

수집방식: START-END
RDB에 대한 연결에 대한 성능을 포함합니다. 스텝 정보에는 이름,응답시간,에러를 포함합니다.

SQL 스텝

수집방식: START-END
JDBC SQL에 대한 성능을 포함합니다. 스탭정보에는 연결정보,SQL문, 에러가 포함되어있습니다.

HTTP Call 스텝

수집방식: START-END
외부 http서비스 호출에 대한 성능을 포함합니다. 스텝 정보에는 url, host, port, 응답시간, 에러가 포함됩니다.

Message 스텝

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

SOCKET 스탭

수집방식: ADD
Socket 오픈을 표현하는 스텝입니다.

METHOD 스탭

수집방식: START-END
메소드 응답시간을 추적합니다.

ACTIVE STATCK 스탭

수집방식: ADD
액티브 스탭에 대한 정보를 포함합니다. 별도 쓰레드가 생성하여 프로파일에 추가하는 방식으로 수집합니다

2.1.3. 트랜잭션 스탭 수집 방식

자바에이전트는 선형 수집 방식과 환형 수집방식을 제공합니다.

선형 수집

개별 트랜잭션 프로파일은 무한정 스텝을 수집할 수 없습니다. 트랜잭션 별로 길이가 제한된 버퍼에 프로파일 스텝을 저장합니다. 각 트랜잭션은 최대로 수집할 수있는 스텝의 수가 옵션으로 지정되어 있습니다.

profile_step_max_count

default: 1024
최대로 수집가능한 스텝수

profile_step_normal_count

default: 800
일반적으로 아무런 제약없이 수집되는 스텝수

profile_step_heavy_count

default : 1000
normal count를 초과한 경우에 스텝은 응답시간이 느린 스텝과 액티브 스택 스텝만 수집합니다.

profile_step_heavy_time

default:100
heavy count이내에서의 수집되는 스텝의 기준 시간은 profile_step_heavy_time입니다.

step buffer
Figure 3. Profile Step Buffer

수집되는 프로파일의 스텝 수가 heavy count를 초과하는 경우에는 액티브 스택만이 수집됩니. 단 이경우에도 최대 스텝 수는 profile_step_max_count를 넘을 수 없습니다.

환형 수집

선형 수집은 프로파일에서 앞부분을 수집하고 버퍼사이즈를 넘으면 나중 내용을 버리지만 반대로 환형 수집은 앞부분의 스텝을 버리는 방식입니다.

circular_profile_enabled=true
circular profile
Figure 4. Profile Step Circular Buffer

버퍼 사이즈는 profile_step_max_count에 설정합니다.

profile_step_max_count=1024

2.1.4. NON HTTP 트랜잭션 추적을 위한 END-POINT 설정 방법

트랜잭션 end-point

트랜잭션 end-point는 트랜잭션의 시작 메소드입니다 HTTP 트랜잭션의 경우에는 HttpServlet.service() 혹은 Filter.doFilter()가 트랜잰션의 시작점이고 이곳을 트랜잭션 엔드포인트라고 부릅니다.

NON HTTP 추적

트랜잭션 end-point 로 지정된 메소드가 시작해서 종료될때까지의 성능을 트랜잭션 성능이라고 합니다. non http 트랜잭션을 추적하기 위해서는 end point 를 지정해야 합니다.

여기서는 알수 없는 end-point를 찾는 과정은 다음과 같습니다.

  1. 트랜잭션이 호출될것으로 추정되는 모든 메소드에 대해 프로파일 추적을 설정합니다.

  2. 재기동후 트랜잭션을 일으켜서 모니터링 합니다.

  3. back stack 옵션을 켜서 진입 메소드를 정확히 파악 합니다.

STEP1, 먼저 메소드 프로파일 설정

일단 메소드 프로파일을 설정합니다. 하지만 해당 클래스들이 잠재적인 트랜잭션 end point보다는 확실하게 트랜잭션에서 호출되는 클래스를 지정합니다. 그래서 DB를 사용한는 프로그램에서는 JDBC드라이버가 일반적으로 유용합니다.

jdbc드라이버에 프로파일을 설정합니다.(whatap.conf)
hook_method_patterns=jdbc.*.*
hook_method_access_public_enabled=true
hook_method_access_protected_enabled=true
hook_method_access_none_enabled=true
어느 메소드이건 호출되면 트랜잭션을 시작시킨다옵션과 트랜잭션 시작시 스택을 덤프하는 옵션을 켭니다.(whatap.conf)
trace_auto_transaction_enabled=true
trace_auto_transaction_backstack_enabled=true
STEP2, 재기동후 프로파일 분석

재기동하고 서비스를 호출하면 트랜잭션이 추적되는 것을 볼 수 있습니다. 트랜잭션들을 조회해 보면 모든 jdbc.*로 시작하는 클래스의 메소드를 이 트랜잭션으로 나타남을 알 수 있습니다. 트랜잭션 프로파일을 조회하면 <TRANSACTION BACKSTACK>라는 메세지 스탭을 확인할 수 있습니다.

TRANSACTION BACKSTACK
jdbc.FakePreparedStatement.executeQuery(FakePreparedStatement.java),
com.virtual.dao.SelectDAO.execute2(SelectDAO.java:29),
com.virtual.web.SimulaNonHttp.execute(SimulaNonHttp.java:147),
com.virtual.web.SimulaNonHttp.process(SimulaNonHttp.java:76),
com.virtual.web.SimulaNonHttp.run(SimulaNonHttp.java:100)

스택내용을 보면 어떤 메소드로 부터 출발하고 있는지 얼추 추정할 수 있다.

예제
com.virtual.web.SimulaNonHttp.execute(SimulaNonHttp.java:147),
com.virtual.web.SimulaNonHttp.process(SimulaNonHttp.java:76),
com.virtual.web.SimulaNonHttp.run(SimulaNonHttp.java:100)

위 3개의 메소드 중에 하나를 트랜잭션 시작점으로 판단하면 된다. 이정도 상황에서는 역컴파일을 수행해서 적절한 트랜잭션 end point를 결정해야한다.

로직을 간단히 보면 SimulaNonHttp.run내에서 while()가 돌면서 SimulaNonHttp.process()을 호출하고 SimulaNonHttp.execute()가 수행된다. process()가 적당하다는 것을 알 수있다. (이 부분은 어쩔 수없이 소스를 보고 판단해야 한다.)
end point의 가장 중요한 기준은 종료되어야 한다는 것이다. 정상적인 상황에서 지연되지 않고 곧바로 종료되어야 성능적인 판단을 할 수 있다.
STEP3, 트랜잭션 END POINT 지정하기

트랜재션 시작 지점을 아래와 같이 설정한다.

hook_service_patterns=com.virtual.web.SimulaNonHttp.process

그리고 재기동하면 process() 메소드가 새로운 트랜잭션의 end point가 된다.

STEP4, 트랜잭션 이름 추적하기

보통의 경우에는 메소드 명칭으로 충분히 트랜잭션을 구분할 수 있습니다.

whatap.conf
 service_name_mode=[full,class,method,string,arg]
 service_name_index=0
service_name_mode

full,class,method,string,arg 5가지 옵션을 지정할 수있습니다.

  • full : Full Class이름 사용

  • class : Class 이름 서비스 명으로 사용

  • method : Method이름을 서비스명으로 사용

  • string : 문자열중에서 첫번째 파라미터를 서비스 명으로 사용

  • arg : 파라미터중에서 service_name_index옵션에 지정한 인덱스이 파라미터를 서비스 명으로

플러그인 사용은 전문가영역이기 때문에 충분히 이해한 경우에만 사용하길 권장합니다.
STEP5, 에이전트 플러그인 사용하기

WHATAP_HOME 디렉토리 아래에 plugin디렉토리를 만듭니다. 그리고 vi를 통해 AppServiceStart.x 파일을 만듭니다.

app start plug

그리고는 println(“test”);라고 타이핑하고 저장하면 화면에 “test”라는 문자열이 출력되는 것을 확인할 수있습니다. 그러면 파라미터에서 정보를 추출해 봅니다.

본예제에는 파라미터에 HashMap에 전달되고 거기에는 url파라미터가 전달되고 있습니다.
Object url =((java.util.HashMap)$point.getArgs()[0]).get("url");
$ctx.service((String)url);
//println(“url=“+url);

이렇게 플러그인을 만들면 트랜잭션 이름이 변경됩니다.

2.1.5. Active Stack 수집

진행중인 트랜잭션을 액티브 트랜잭션이라고 합니다. 액티브 트랜잭션에서 정기적으로 덤프한 스택을 액티브 스택이라 합니다.

와탭 에이전트는 매 10초(옵션 가능)마다 액티브 트랜잭션에 대해서 액티브스택을 덤프하고 이것을 서버에 전송합니다. (active_stack_second=10)
컴팩트한 액티브 스택 수집

액티브 스택은 스레드 덤프를 정기적으로 수행하기 때문에 잘못구현되면 에이전트에 오버헤드가 커질 수있습니다. 따라서 와탭은 에이전트 부하를 최소화하면서 액티브 스택을 수집하기 위해 다양한 옵션들을 가지고 있습니다.

서버 > 더보기 > 쓰레드 목록/덤프 메뉴에서 스레드 목록중에 "WhaTap-ActiveStackDump"쓰레드의 CPU Time을 확인하면 오버헤드를 판단할 수있습니다.
액티브스택의 예
java.lang.StringBuffer.append(StringBuffer.java:309)
java.util.regex.Matcher.appendReplacement(Matcher.java:839)
java.util.regex.Matcher.replaceAll(Matcher.java:906)
java.lang.String.replaceAll(String.java:2162)
core.log.triggers.TriggerRegister.changeNotify(TriggerRegister.java:114)
core.log.aop.handler.DaoInfo.log(DaoInfo.java:141)
core.log.aop.handler.DaoInfo.doAround(DaoInfo.java:102)
core.log.aop.reflection.profiler.AroundProfiler.invoke(AroundProfiler.java:19)
com.sun.proxy.$Proxy39.getUpdateCount(Unknown Source)
org.apache.ibatis.executor.resultset.DefaultResultSetHandler.getNextResultSet(DefaultResultSetHandler.java:256)
org.apache.ibatis.executor.resultset.DefaultResultSetHandler.handleResultSets(DefaultResultSetHandler.java:193)
org.apache.ibatis.executor.statement.PreparedStatementHandler.query(PreparedStatementHandler.java:64)

* * *

sun.reflect.GeneratedMethodAccessor140.invoke(Unknown Source)
sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
java.lang.reflect.Method.invoke(Method.java:606)
org.springframework.web.method.support.InvocableHandlerMethod.doInvoke(InvocableHandlerMethod.java:221)
org.springframework.web.method.support.InvocableHandlerMethod.invokeForRequest(InvocableHandlerMethod.java:136)
org.springframework.web.servlet.mvc.method.annotation.ServletInvocableHandlerMethod.invokeAndHandle(ServletInvocableHandlerMethod.java:114)
org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.invokeHandlerMethod(RequestMappingHandlerAdapter.java:827)
최적화된 데이터 수집
  • 트랜잭션을 수행중인 쓰레드에 대해서만 스택을 덤프합니다.

  • 액티브 스택 덤프 시간 간격을 조정 할 수 있습니다. (active_stack_second=10)

  • 액태브 스택의 최대 라인에 제한되어 있습니다,top라인에서 부터 기본 50라인을 수집합니다. (trace_active_callstack_depth=50)

  • 액티브 스택의 각 라인은 해쉬처리되어 수집됩니다.(text는 한번만)

  • 한 타임에 수집되는 최대 액티브스택 갯수도 제한 되어있습니다.(active_stack_count=100)

Background Thread에 대한 액티브 스택

@since v1.6.2
기본적으로 액티브 스택은 트랜잭션이 수행되고 있는 쓰레드의 스택을 말합니다. 하지만 일부 백그라운드 쓰레드에 대해서도 스택을 분석할 필요가 있을 수있습니다. 이때 옵션을 통해서 백그라운드 쓰레드에 대한 액티브 스택을 확보할 수있습니다.

async_stack_enabled=false

async_stack_enabled를 true로 설정하면 활성화됩니다.

active_stack_second=10

스택 덤프 간격은 포그라운드 액티브 스택 설정에 따가랍니다.

async_thread_match=http*,abc*

대상 쓰레드 이름을 지정할때는 '*' 사용하여 문자열 패턴을 지정합니다.

쓰레드 이름으로 스택 덤프 대상을 식별합니다. ","를 사용하여 match를 여러개를 지정할 수 있습니다.
async_thread_parking_class=sun.misc.Unsafe
async_thread_parking_method=park

스택의 Top메소드가 async_thread_parking에 등록된 클래스/메소드일때 쓰레드가 파킹상태에 있다고 판단하고 덤프를 생성하지 않습니다.

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

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

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

2.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

sql_fetch

SQL 패치 건수

u4

sql_fetch_time

SQL 패치 시간의 합

u8

httpc_count

HTTP Call건수

u4

httpc_time

HTTP Call 시간의 합

u8

malloc_sum

메모리 사용량 SUM

u8

cpu_sum

CPU사용량 SUM

u8

malloc_sum은 trace_malloc_enabled=true로 변경해야 수집됩니다.(default: false)

2.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

fetch_count

패치 건수

u4

fetch_time

패치 시간의 합

u8

service

SQL을 수행한 service중에 하나

u4

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

2.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

2.2.4. 에러 통계

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

칼럼 설명 타입

classHash

에러클래스

u4

service

트랜잭션 HASH

u4

snapSeq

스택 정보

u8

msg

메세지 hash

u4

count

발생 건수

u4

2.2.5. IP별 호출 건수

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

칼럼 설명 타입

ip

ip주소

u4

count

건수

u4

2.2.6. UserAgent별 호출 건수

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

칼럼 설명 타입

hash

hash

u4

count

건수

u4

2.2.7. 트랜잭션 Caller 통계

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

whatap.conf
mtrace_rate=100
mtrace_spec=v1
stat_mtrace_enabled=true
msa
Figure 5. 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

수집되는 통계 데이터는 다음과 같습니다. 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

2.2.8. 트랜잭션 도메인 통계

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

whatap.conf
stat_domain_enabled=true

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

칼럼 설명 타입

domain

서비스 도메인 hash

u4

url

트랜잭션 URL hash

u4

count

수행 건수

u4

error

에러건수

u4

time

응답시간의 합

u8

2.2.9. 트랜잭션 REFERER 통계

와탭에이전트는 Referer별 트랜잭션 통계를 수집할 수 있습니다. 업무에 딸서는 Referer별 분석이 필요할 수있습니다.

whatap.conf
stat_domain_enabled=true

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

칼럼 설명 타입

referer

Referer hash

u4

url

트랜잭션 URL hash

u4

count

수행 건수

u4

error

에러건수

u4

time

응답시간의 합

u8

2.3. 성능 카운터

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

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

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

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

2.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로 머지하면 이론적으로 한달 이상의 맥티브 사용자를 계산 할 수 있습니다.

2.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 호출에 대한 현황을 카운팅 합니다.

  • 건수

  • 응답시간

  • 에러 건수

2.3.3. Resource Counter

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

CPU(sys,usr,wait,steal,irq, cores)

CPU사용량 % 입니다. 각 종류별로 수집됩니다. 가상환경에서만 Steal이 의미가 있습니다. Cput Core 갯수를 같이 수집하고 있습니다.

Process CPU

자바 프로세스가 사용하는 CPU %입니다.

Memory

시스템 메모리 사용율(%) 입니다.

Swap

Swap메모리 사용율(%) 입니다.

Disk

Disk는 Java Process의 Current 디렉토리의 사용율(%) 입니다.

Unresolved directive in index.adoc - include::4_control&status.adoc[leveloffset=+1]

2.4. Python 애플리케이션 모니터링 설정

해당 가이드는 Python 애플리케이션 모니터링을 할 때에 설정할 수 있는 옵션에 대해 설명합니다. (*) 표시가 있는 옵션은 애플리케이션을 재시작 하여야만 적용되는 옵션입니다.

2.4.1. 에이전트 네트워크 통신에 관한 설정

license

Default : NONE
Type : String
에이전트 설치시 서버로부터 부여받은 라이센스를 지정합니다. 라이센스에는 에이전트가 속한 프로젝트와 보안 통신을 위한 암호키를 포함하고 있습니다.

whatap.server.host

Default : 127.0.0.1,127.0.0.1
Type : String
에이전트가 수집한 데이터를 전송할 서버를 지정합니다. 수집서버 이중화로 2개 이상의 IP를 가진 경우 콤마(,)로 분리하여 지정할 수 있습니다. 지정된 IP 에는 수집서버 proxy 데몬이 리스닝 상태로 서비스 되어야 합니다.

whatap.server.port

Default : 6600
Type : String
수집서버 PORT 를 지정합니다. 포트는 하나만 지정할 수 있으므로 whatap_server_host 에 지정된 수집서버들은 동일 PORT 를 사용해야 합니다.

2.4.2. 에이전트 네트워크 내부 통신에 관한 설정

net_udp_port

Default : 6600
Type : String
와탭 에이전트는 수집한 데이터를 UDP를 거쳐 TCP를 통해 서버로 전송을 하는데, 처음 UDP서버의 포트를 지정할 수 있습니다. 기본값으로 제공되는 6600포트가 사용 중일 때 이 옵션을 사용합니다.

2.4.3. 에이전트 네트워크 외부 통신에 관한 설정

tcp_so_timeout

Default : 60000
Type : MiliSecond
수집서버와 통신하는 TCP세션의 Socket Timeout 값을 지정합니다.

tcp_connection_timeout

Default : 5000
Type : MiliSecond
수집서버와 통신하는 TCP세션의 Connection Timeout 값을 지정합니다.

net_send_max_bytes

Default : 5242880
Type : Byte
에이전트가 데이터를 수집하고 네트워크로 한번에 전송할 수 있는 최대 바이트 크기입니다.

net_send_buffer_size

Default: 1024
Type: byte
데이터 전송을 하기 위해 가지고 있는 최대 바이트 크기입니다.

2.4.4. 애플리케이션 등록에 관한 설정

object_name

Default : {type}-{ip2}-{ip3}-{process}
Type : String
애플리케이션을 식별하는 에이전트 이름(ONAME)체계입니다. ONAME을 토대로 OID가 생성됩니다.

명칭

설명

{type}

whatap.app_name 에 설정된 값을 사용합니다.

{ip#}

IP를 나누었을 때 #번째 자리를 사용합니다.

{process}

whatap.app_process_name 에 설정된 값을 사용합니다.

{hostname}

서버 호스트명을 사용합니다.

app_name

Default : NONE
Type : String
애플리케이션을 식별하는 에이전트 이름(ONAME)체계에 사용되는 애플리케이션 명. object_name의 {type}에 해당하는 값이다.

app_process_name

Default : NONE
Type : String
애플리케이션을 식별하는 에이전트 이름(ONAME)체계에 사용되는 애플리케이션 프로세스 명. 애플리케이션 서버의 CPU, Heap Memory등을 수집할 대상 프로셋를 설정합니다. object_name의 {process}에 해당하는 값이다.

2.4.5. 에이전트 기능 제어에 관한 설정

enabled

Default : true
Type : Boolean
전체 기능을 활성화 합니다. false인 경우에도 서버와 최소한의 통신을 유지하기 위한 정보는 전송됩니다.

counter_enabled

Default : true
Type : Boolean
성능 카운터 추적을 활성화 합니다. 성능 카운터는 액티브 트랜잭션, 사용자, CPU, Memory, SQL, 외부 HTTP 호출 등의 데이터를 포함합니다. 단, enable이 false면 무시됩니다.

stat_enabled

Default : true
Type : Boolean
통계 정보 추적을 활성화 합니다. 5분마다 트랜잭션, SQL Query, 외부 HTTP 호출, User Agent, Client IP등의 통계 데이터가 수집되는데 이들 정보의 수집이 중단됩니다. 단, enable이 false면 무시됩니다.

active_stack_enabled

Default : true
Type : Boolean
액티브 스택 추적을 활성화 합니다. 참고로, counter_enabled 값이 비활성화 된 경우 액티브 트랜잭션 데이터가 수집되지 않으므로 액티브 스택 또한 수집되지 않습니다.

2.4.6. 트랜잭션 프로파일 데이터에 관한 설정

profile_http_header_enabled

Default : false
Type : Boolean
프로파일에 HTTP 헤더 정보를 출력합니다. 헤더 수집의 여부와 무관하게 헤더를 프로파일에 노출할 것인가에 대한 설정입니다.

profile_http_parameter_enabled

Default : false
Type : Boolean
http 파라미터를 프로파일링을 활성화합니다. 단 파라미터는 별도 보안키를 입력해야 조회할 수 있습니다. 보안 키는 에이전트 설치 경로의 paramkey.txt 파일에 6 자리로 지정합니다. paramkey.txt 가 존재하지 않는 경우 자동 생성되며 random 키가 설정됩니다.

profile_dbc_close(*)

Default : false
Type : Boolean (profile_connection_open_enabled=true 에서만 동작)
profile_connection_open_enabled이 활성화 되어 있는 경우, 프로파일에 DB Connection이 close될 때의 정보를 출력합니다.

profile_step_normal_count

Default: 1000
Type : Int
트랜잭션 프로파일의 기본 스텝 수를 지정합니다.

profile_step_heavy_count

Default: 1020
Type : Int
프로파일 기본 스텝을 초과한 경우, 최대 heavy스텝 수를 제한합니다. profile_step_normal_count에서 profile_step_heavy_time을 초과하는 스텝을 카운팅합니다. 따라서, 응답시간이 없는 스텝들은 수집되지 않습니다.

profile_step_max_count

Default: 1024
Type : Int
프로파일 스텝의 최대 수를 설정합니다. 수집된 프로파일 스텝 수가 이 값을 초과하면 이후 수집되는 스텝들은 모두 버려집니다. profile_step_heavy_count을 최대 1000으로 설정한다면 profile_step_max_count만큼 액티브 스택이 수집됩니다.

profile_step_heavy_time

Default: 100
Type : MiliSecond
Heavy한 스텝의 기준을 지정 합니다. 지정된 값보다 수행시간이 긴 경우 profile_step_normal_count 를 초과하는 경우라도 profile_step_heavy_count 이내에서 기록됩니다.

profile_basetime

Default: 0
Type : MiliSecond
트랜잭션이 설정된 값 이하의 시간내에 종료된 경우 프로파일 정보를 수집하지 않습니다. 단, 5 분단위로 최초 호출된 URL, 에러가 발생한 트랜잭션에 대한 프로파일 정보는 수집됩니다.

query_string_enabled

Default : false
Type : Boolean
트랜잭션 URL의 쿼리 스트링을 함께 수집하는 기능을 활성화합니다.

query_string_urls

Default : NONE
Type : String
트랜잭션에서 쿼리 스트링을 수집 할 URL들을 등록합니다. 여러 개를 등록할 때는 콤마(,)를 사용합니다.

profile_sql_param_enabled

Default : false
Type : Boolean
SQL 파라미터를 수집을 활성화합니다. 단 파라미터는 별도 보안키를 입력해야 조회할 수 있습니다. 보안 키는 에이전트 설치 경로의 paramkey.txt 파일에 6 자리로 지정합니다. paramkey.txt 가 존재하지 않는 경우 자동 생성되며 random 키가 설정됩니다.

profile_sql_resource_enabled

Default : false
Type : Boolean
프로파일에서 SQL 이 수집될 때 해당 스텝에서 사용한 CPU 와 Memory 사용량을 추적합니다. 트랜잭션에서 리소스들의 사용량을 확인할 때 구간으로 나누어 추적이 용이합니다.

profile_httpc_resource_enabled

Default : false
Type : Boolean
프로파일에서 HTTP Call 스텝이 수집될 때 해당 스텝에서 사용한 CPU 와 Memory 사용량을 추적합니다.

hook_method_patterns

Default : None
Type : String
특정 메소드의 응답시간을 측정하고 싶을때 사용합니다. [MODULE_NAME]:[CLASS_NAME].[FUNCTION_NAME] 혹은 [MODULE_NAME]:[FUNCTION_NAME] 형식으로 값을 사용합니다. , 구분자를 통하여 여러 메소드 패턴을 지정할 수 있으며 모듈에 대한 전체 클래스나, 클래스에 대한 전체 모듈은 asterisk(*)를 사용하여 추적이 가능 합니다.

단, 전체 모듈에 대한 추적은 오버헤드가 발생 할 수 있으니 운영환경시에는 가급적 정확한 모듈명과 메소드명에 대한 사용을 권장합니다.

mtrace_rate

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

mtrace_spec

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

mtrace_send_url_length

Default : 80
Type : Integer

2.4.7. 사용자 추적을 위한 설정

trace_user_enabled(*)

Default : true
Type : Boolean
실시간 사용자를 추적할지를 결정합니다. 이 값을 활성화 하는 경우 기본값은 IP가 됩니다.

trace_user_using_ip(*)

Default : true
Type : Boolean
실시간 사용자의 구분을 IP로 하고자 하는 경우 설정합니다. 이 데이터는 Real Time User에서 확인 가능합니다. 단, user_header_ticket옵션과 배타적으로 설정을 동시에 적용할 수 없습니다.

2.4.8. 트랜잭션 추적을 위한 설정

trace_error_callstack_depth

Default: 50
Type : Int
트랜잭션에서 에러 콜 스택을 수집할 때, 콜스택 최대 라인수를 지정합니다. 이 데이터는 에러 통계데이터에서 조회 할 수 있습니다.

trace_active_callstack_depth

Default: 50
Type : Int
트랜잭션에서 액티브 스택을 수집할 때, 콜스택 최대 라인수를 지정합니다.

trace_active_transaction_slow_time

Default: 3000
Type : MiliSecond
엑티브 트랜잭션의 아크이퀄라이저에서 slow 구간의 응답기준을 지정합니다.

trace_active_transaction_very_slow_time

Default: 8000
Type : MiliSecond
엑티브 트랜잭션의 아크이퀄라이저에서 very slow 구간의 응답기준을 지정합니다.

trace_active_transaction_lost_time

Default: 300000
Type : MiliSecond
트랜잭션의 종료를 기다리는 제한 시간. 5분안에 트랜잭션이 끝나지 않는 경우 트랜잭션을 정보를 더이상 수집하지 않습니다.

web_static_content_extensions(*)

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

2.5. 성능 카운터 & 통계 확장

stat_domain_enabled

Default : false
Type : Boolean
도메인별 트랜잭션 통계를 수집합니다.

stat_domain_max_count

Default : 7000
Type : Int
5분동안 애플리케이션에서 수집할 도메인별 트랜잭션 통계의 최대 레코드 수입니다.

stat_mtrace_enabled

Default : false
Type : Boolean
멀티 서버 트랜잭션에서 Callser&Callee간에 버전별 의존성 통계를 수집합니다.

stat_mtrace_max_count

Default : 7000
Type : Int
멀티 서버 트랜잭션에서 Callser&Callee간에 버전별 의존성 통계의 최대 레코드 수입니다.

stat_login_enabled

Default : false
Type : Boolean
로그인별 트랜잭션 통계를 수집합니다.

stat_login_max_count

Default : 7000
Type : Int
5분동안 애플리케이션에서 수집할 로그인별 트랜잭션 통계의 최대 레코드 수입니다.

stat_referer_enabled

Default : false
Type : Boolean
Referer별 트랜잭션 통계를 수집합니다.

stat_referer_max_count

Default : 7000
Type : Int
5분동안 애플리케이션에서 수집할 Referer별 트랜잭션 통계의 최대 레코드 수입니다.

stat_tx_max_count

Default : 5000
Type : Int

stat_sql_max_count

Default : 5000
Type : Int

stat_httpc_max_count

Default : 5000
Type : Int

stat_error_max_count

Default : 1000
Type : Int

stat_useragent_max_count

Default : 500
Type : Int

2.5.1. 운영을 위한 설정

active_stack_second

Default : 10
Type : Seconds
액티브 스택을 추적하는 간격을 설정합니다. (주의: 값을 바꾸는 것을 권장하지 않습니다.)

값을 바꾸는 것을 권장하지 않습니다.
realtime_user_thinktime_max

Default : 300000
Type : MiliSeconds
실시간 사용자 측정시 동일 사용자로 인정되는 최대 호출간격을 지정합니다.

time_sync_interval_ms

Default : 300000
Type : MiliSeconds
에이전트와 서버간 시간 동기화 주기를 지정합니다. 동기화 하지 않을 경우 0으로 지정합니다.

text_reset

Default : 0
Type : Int
와탭 에이전트는 한번 보낸 텍스트유형 데이터는 hash 처리되므로 다음날까지 재전송하지 않습니다. 이전 설정값과 다른 값을 설정하는 경우 재전송 합니다.

트랜잭션 URL, SQL String 등이 텍스트유형 데이터에 해당합니다.
trace_auto_normalize_enabled(*)

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

trace_normalize_enabled

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

false 로 변경시 패스파라미터 파싱이 비활성화됩니다. 이 경우 통계데이터의 의미가 약화됨으로 디버그 용도로만 잠시 사용하는 것이 좋습니다.
trace_normalize_urls

Default : NONE
Type : String
트랜잭션 URL을 파싱하여 정규화 합니다. 호출 URL패턴을 파싱하여 패스 파라미터를 제거합니다. 예를 들어, /a/{v}/b라고 선언하면 /a/123/b → /a/{v}/b로 치환합니다. 여러 개를 등록 할 때는 콤마(,)를 사용합니다. /a/*/b 로 사용하여 특정 형식의 패스 파라미터를 제거하여 수집할 수 있습니다.

trace_httpc_normalize_enabled

Default : true
Type : Boolean
외부 HTTP 호출(HTTP Call) URL을 파싱하여 정규화 하는 기능을 활성화합니다.

trace_httpc_normalize_urls

Default : NONE
Type : String
외부 HTTP 호출하는 URL을 파싱하여 정규화합니다. 호출 URL패턴을 파싱하여 패스 파라미터를 제거합니다. 예를 들면, /a/{v}/b라고 선언하면 /a/123/b → /a/{v}/b로 치환한다. 여러 개를 등록 할 때는 콤마(,)를 사용합니다. /a/*/b 로 사용하여 특정 형식의 패스 파라미터를 제거하여 수집할 수 있습니다.

trace_sql_normalize_enabled

Default : true
Type : Boolean
SQL문에서 리터럴 부분을 추출하여 SQL문을 정규화 하는 기능을 활성화합니다.

2.5.2. 로그를 위한 설정

log_rotation_enabled

Default : true
Type : Boolean
에이전트 로그파일을 매일 변경합니다. (로그파일 기본 경로: $WHATAP_HOME/logs/whatap-xxx.log)

log_keep_days

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