Whatap Focus Agent Guide

제목 : Focus Agent Guide
작성자 : WhaTap Support
이메일 : support@whatap.io
날짜 : 2020-12-06
버전 : 1.1

설명 : 본 문서는 WhaTap Focus 에이전트를 설명합니다.

1. 개요

Focus는 와탭 모니터링에서 제공하지 않는 임의의 데이터를 시계열로 업로드하는 프로그램 입니다. 운영팀에서 자체 개발한 체크 스크립트나 데이터베이스 쿼리를 주기적 혹은 일회성으로 작동하여 수집된 값을 업로드 할 수 있습니다. 업로드된 값은 해당 프로젝트의 분석/매트릭스 챠트 메뉴에서 확인할 수 있습니다. 또 통합 매트릭스 대시보드에 추가할 수 있습니다.

Focus를 사용하시려면 와탭 프로젝트중 Server, Applicaton(Java, PHP, NodeJS, Python), Database, Kubernetes 프로젝트 중 하나를 선택후에 해당 프로젝트의 라이선스 문자열과 수집서버 IP를 실행옵션으로 지정하여 사용하실수 있습니다.

1.1. 지원 환경

X86 기반에서 동작하는 Windows, Linux, FreeBSD, OSX 및 ARMv5,6,7 및 ARM64 Linux OS에 적용 할 수 있습니다. 지원 리스트에 포함되지 않는 환경이라면 support@whatap.io 로 별도 문의 주시기를 부탁 드립니다.

Table 1. 제품 지원 환경
제품 환경 지원 환경

Focus

Windows

Windows 2008R2 이상

Linux

Debian 7.0 이상
Ubuntu 12.04 이상
Centos, Readhat 6.0 이상
Amazon Linux 1.0 이상
SUSE 12.1 이상

FreeBSD

FreeBSD 10 이상

OSX

Lion 10.7 이상

Raspberry Pi OS

8 이상

1.2. 구성 파일

Table 2. Linux / FreeBSD / OSX / Raspberry Pi OS
파일명 설명

focus

데이터 수집 및 전송 프로그램

Table 3. Windows
파일명 설명

focus.exe

데이터 수집 및 전송 프로그램

2. 설치

와탭 포커스는 단일 실행파일로 구성되어 별도의 설치과정이나 등록과정이 불필요 합니다. 실행파일을 다운로드 하여 임의의 위치에서 실행하실 수 있습니다.

2.1. 실행파일 다운로드

와탭 Focus 는 단일 실행파일로 구성되어 버젼별로 다운로드 하여 바로 사용하실 수 있습니다.

64 bit Debian / Ubuntu / RedHat / CentOS / Amazon Linux / SUSE
wget http://repo.whatap.io/focus/linux_amd64/focus
chmod +x ./focus
64 bit OSX
wget http://repo.whatap.io/focus/darwin_amd64/focus
chmod +x ./focus
64 bit FreeBSD
wget http://repo.whatap.io/focus/freebsd_amd64/focus
chmod +x ./focus
64 bit Windows
Invoke-WebRequest -Uri http://repo.whatap.io/focus/windows_amd64/focus.exe -OutFile focus.exe
ArmV5 Linux
wget http://repo.whatap.io/focus/linux_arm_5/focus
chmod +x ./focus
ArmV6 Linux
wget http://repo.whatap.io/focus/linux_arm_6/focus
chmod +x ./focus
ArmV7 Linux
wget http://repo.whatap.io/focus/linux_arm_7/focus
chmod +x ./focus
Arm64 Linux
wget http://repo.whatap.io/focus/linux_amd64/focus
chmod +x ./focus

3. 설정방법

와탭 프로젝트에서 임의의 수집데이터를 업로드 할 수 있습니다. Focus는 해당 프로젝트의 기본 에이전트가 설치되지 않아도 사용하실 수 있습니다.

3.1. 라이선스 및 수집 서버 IP 확인

선택한 프로젝트의 관리 / 에이전트 설치 메뉴에서 프로젝트 코드, 수집서버 IP와 라이선스를 확인합니다.

Linux Shell
export WHATAP_LICENSE=xxxx-xxxxxx-xxxxxx
export WHATAP_HOST=xxxx.xxxx.xxxx
export WHATAP_PCODE=xxx
Windows Powershell
$WHATAP_LICENSE=xxxx-xxxxxx-xxxxxx
$WHATAP_HOST=xxxx.xxxx.xxxx
$WHATAP_PCODE=xxx

3.2. 알림 보내기

사용자 정의 알림을 즉시 보낼 수 있습니다. 알림을 보낸 후 Focus는 종료하게 됩니다.

Windows Powershell
#알림의 심각도를 선택합니다.
$level="{info|warn|fatal}"
#알림의 제목
$title="원하는 알림의 제목"
#알림의 본문
$message="원하는 알림의 본문"
.\focus.exe -license $WHATAP_LICENSE `
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST `
    -alert -level $level -title $title -message $message
Linux Shell
#알림의 심각도를 선택합니다.
level={info|warn|fatal}
#알림의 제목
title=원하는 알림의 제목
#알림의 본문
message=원하는 알림의 본문
./focus -license $WHATAP_LICENSE \
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST \
    -alert -level $level -title $title -message $message

3.3. SQL Query 결과 수집하기

사용자 정의 SQL Query 의 실행 결과를 시계열로 무기한 수집합니다.

Windows Powershell
#매트릭 카테고리
$CATEGORY="my_category"
#데이터 베이스 드라이버
$driver="{mysql|postgres}"
#데이터베이스 접속 정보
$dburl="아이디:패스워드@tcp(아이피:포트)/데이터베이스"
#Sql Query
$sqlquery="select some, columns from sometable"

.\focus.exe -license $WHATAP_LICENSE `
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST `
    -category $CATEGORY `
    -rdb $driver -rdb.connect $dburl `
    -rdb.sql $sqlquery
Linux Shell
#매트릭 카테고리
category=my_category
#데이터 베이스 드라이버
driver={mysql|postgres}
#데이터베이스 접속 정보
dburl="아이디:패스워드@tcp(아이피:포트)/데이터베이스"
#Sql Query
sqlquery="select some, columns from sometable"
./focus -license $WHATAP_LICENSE \
    -category $category \
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST \
    -rdb $driver -rdb.connect $dburl \
    -rdb.sql $sqlquery

3.4. 로그파일 키워드 매칭시 로그 수집하기

지정한 텍스트 로그 파일에서 로그 발생시 키워드를 포함하면 해당 로그 라인을 수집합니다.

Windows Powershell
#매트릭 카테고리
$CATEGORY="my_category"
#로그파일
LOG_FILE=로그파일 경로
#로그 키워드를 ,로 연결하여 입력
LOG_KEYWORDS=keyword1,keyword2

.\focus.exe -license $WHATAP_LICENSE `
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST `
    -category $CATEGORY `
    -tail $LOG_FILE `
    -tail.keys $LOG_KEYWORDS
Linux Shell
#매트릭 카테고리
category=my_category
#로그파일
LOG_FILE=로그파일 경로
#로그 키워드를 ,로 연결하여 입력
LOG_KEYWORDS=keyword1,keyword2
./focus -license $WHATAP_LICENSE \
    -category $category \
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST \
    -tail $LOG_FILE \
    -tail.keys $LOG_KEYWORDS \

3.5. OS 자원사용량 수집하기

Focus가 작동중인 서버의 자원 사용량을 수집합니다.

Linux Shell
#매트릭 카테고리
category=my_category
#디스크 모니터링 활성화 여부
diskenabled=true|false
#모니터링할 디스크 마운트
diskmount=/mypartition
#NIC 모니터링 활성화 여부
nicenabled=true|false
#모니터링할 NIC
nic=eth0

./focus -license $WHATAP_LICENSE \
    -category $category \
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST \
    -sys \
    -sys.disk.enabled $diskenabled \
    -sys.disk $diskmount \
    -sys.net.enabled $nicenabled \
    -sys.net $nic

3.6. 임의의 프로그램 및 스크립트 실행 결과를 수집하기

임의의 프로그램 및 스크립트를 실행하고 stdout 으로 출력되는 결과를 지속적으로 수집합니다. 와탭 Focus는 json dictionary 형식으로 stdin으로 입력되면 해당 dictionary의 key, value를 수집합니다. 입력 수단으로 파이프를 사용하게 되므로 버퍼링을 사용하지 않도록 설정하는것이 필요합니다.

지속적으로 수집하는것이 아니라 일회성으로 수집하기를 원하면 아래옵션을 적용할 수 있습니다. -onetime

수집 시간을 지정하고 싶으면 아래 옵션으로 지정할 수 있습니다. -now {unix epoch time(second)}

Linux Shell
#매트릭 카테고리
CATEGORY="my_category"


프로그램 혹은 스크립트 | \
json dictionary 형태로 재가공 | \
./focus -license $WHATAP_LICENSE \
    -category $category \
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST

아래 예는 top 명령을 실행하여 특정 프로세스의 cpu, memory 사용량을 계속하여 수집 합니다.

Linux Shell
#매트릭 카테고리
CATEGORY="my_category"

export PID=수집하기 원하는 프로세스의 PID
top -b -p $PID | awk '/'$PID'/{ printf "{\"pid\": %s, \"cpuPercent\": %s, \"memoryPercent\": %s, \"cmd\": \"%s\"}\n",$1, $9, $10, $12}; system("")' | \
./focus -license $WHATAP_LICENSE \
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST \
    -category $CATEGORY

4. 활용사례

Focus를 활용하여 자주 사용하는 명령 및 기타 활용 사례를 나열합니다. 이를 통해 개발 및 운영시 확인 가능한 데이터를 시계열로 확인할 수 있도록 하여 개발 운영에 도움이 되었으면 합니다.

4.1. 라이선스 및 수집 서버 IP 확인

선택한 프로젝트의 관리 / 에이전트 설치 메뉴에서 프로젝트 코드, 수집서버 IP와 라이선스를 확인합니다.

Linux Shell
export WHATAP_LICENSE=xxxx-xxxxxx-xxxxxx
export WHATAP_HOST=xxxx.xxxx.xxxx
export WHATAP_PCODE=xxx

4.2. TOP 을 활용하여 pid 별 CPU, Memory 수집

아래 예는 top 명령을 실행하여 특정 프로세스의 cpu, memory 사용량을 계속하여 수집 합니다.

Linux Shell
#매트릭 카테고리
CATEGORY="my_category"
export PID=수집하기 원하는 프로세스의 PID

top -b -p $PID | awk '/'$PID'/{ printf "{\"pid\": %s, \"cpuPercent\": %s, \"memoryPercent\": %s, \"cmd\": \"%s\"}\n",$1, $9, $10, $12}; system("")' | \
./focus -license $WHATAP_LICENSE \
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST \
    -category $CATEGORY

4.3. NETSTAT 활용

아래 예는 netstat 명령을 실행하여 하여 TCP Connection 상태 별 갯수를 수집 합니다.

Linux Shell
#매트릭 카테고리
CATEGORY="my_category"

netstat -nat| tail -n+3 |  awk '{print $6}' | sort | uniq -c | awk 'BEGIN { printf "{" } {if (NR!=1) {printf ", "}}{printf "\"%s\":%s",$2,$1} END { print "}" }' | \
./focus -license $WHATAP_LICENSE \
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST \
    -category $CATEGORY -onetime

4.4. VMSTAT 활용

아래 예는 vmstat 명령을 실행하여 항목별 지수를 수집 합니다.

Linux Shell
#매트릭 카테고리
CATEGORY="my_category"

vmstat -n 5 | awk ' NR>2 {printf "{ \"r\":%s,\"b\":%s, \"swpd\" :%s, \"free\" :%s, \"buff\" :%s, \"cache\" :%s, \"si\" :%s, \"so\":%s, \"bi\" :%s, \"bo\" :%s,  \"in\" :%s,  \"cs\":%s, \"us\":%s, \"sy\":%s, \"id\":%s, \"wa\":%s, \"st\" :%s }\n", $1,$2, $3,$4, $5,$6, $7,$8, $9,$10, $11,$12, $13,$14, $15,$16,$17}\n' | \
./focus -license $WHATAP_LICENSE \
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST \
    -category $CATEGORY

4.5. DU 활용

아래 예는 du 명령을 실행하여 하여 임의의 디렉토리 용량을 수집 합니다.

Linux Shell
#매트릭 카테고리
CATEGORY="my_category"
TARGET=용량수집을 원하는 디렉토리

du -sb $TARGET --max-depth=0 | awk 'BEGIN { printf "{" } {if (NR!=1) {printf ", "}}{printf "\"%s\":%s",$2,$1} END { print "}" }' | \
./focus -license $WHATAP_LICENSE \
    -pcode $WHATAP_PCODE -server.host $WHATAP_HOST \
    -category $CATEGORY -onetime