2. 시스템 에이전트 설치

이 장에서 하는 일

시스템 에이전트는 서버 한 대의 상태를 수집해 APM 서버로 보냅니다. CPU·메모리·디스크· 네트워크 같은 운영체제 자원과, 그 서버에서 함께 도는 웹 서버(Apache·NGINX)·데이터베이스· 컨테이너의 상태를 봅니다.

왜 필요한가 — WAS 에이전트가 "애플리케이션 안에서 무슨 일이 일어나는가"를 본다면, 시스템 에이전트는 "그 애플리케이션이 올라가 있는 서버가 괜찮은가"를 봅니다. 응답이 느려졌을 때 코드가 문제인지 서버 자원이 모자란 것인지 가르려면 둘 다 있어야 합니다.

어디에 설치하나 — 모니터링할 서버마다 한 벌씩 설치합니다. WAS 가 도는 서버뿐 아니라 웹 서버·데이터베이스 서버도 해당합니다. WAS 에이전트와 달리 애플리케이션을 건드리지 않고 별도 프로세스로 따로 돕니다. 그래서 WAS 를 재기동하지 않아도 됩니다.

설치를 마치면 — 콘솔의 시스템 메뉴에서 그 서버의 자원 사용량을 볼 수 있습니다.

설치 흐름

단계	하는 일	왜
1	설치 파일 내려받기	콘솔이 이 서버에 맞는 에이전트를 내려줍니다
2	압축을 풀고 접속 정보 설정	에이전트가 어느 APM 서버로 데이터를 보낼지 알려 줍니다
3	플러그인 켜기 (선택)	웹 서버·데이터베이스도 함께 보려면 해당 플러그인을 켭니다
4	에이전트 시작	수집이 시작되고 콘솔에 서버가 나타납니다

3단계는 건너뛰어도 됩니다. 운영체제 자원만 보려면 1·2·4 만으로 충분합니다.

시스템 에이전트의 구조

에이전트는 코어와 플러그인 두 층으로 되어 있습니다.

	무엇을 하나	설정이 필요한가
코어	운영체제 자원(CPU·메모리·디스크·네트워크)을 직접 읽습니다	접속 정보만 — 켜고 끄는 개념이 없습니다
플러그인	같은 서버에서 도는 다른 제품에 물어봅니다	켜야 하고, 대상 제품 쪽 설정도 함께 필요합니다

플러그인을 하나도 켜지 않아도 운영체제 자원은 수집됩니다. 플러그인은 "이 서버의 Apache 도 같이 보고 싶다" 같은 필요가 있을 때 더하는 것입니다.

설치 디렉터리

압축을 풀면 아래 구조가 생깁니다. 고칠 파일은 두 종류뿐입니다.

khan-sys-agent/
├── bin/
│   ├── start.sh · kill.sh · tail.sh      기동 · 종료 · 로그 보기
├── conf/
│   └── khan-sys-agent.conf               ← ① 접속 정보 (필수)
├── plugins/
│   ├── disabled.txt                      ← ② 어느 플러그인을 켤지
│   ├── khan-plugin-apache-5.1.0/         플러그인 본체 (건드리지 않음)
│   └── khan-plugin-apache.conf/
│       └── config.properties             ← ③ 플러그인 설정 (켠 것만)
└── logs/

③ 을 khan-plugin-apache.conf/ 에 두는 이유 — 플러그인 본체 디렉터리 (khan-plugin-apache-5.1.0/conf/)에도 같은 파일이 있지만, 그쪽은 플러그인을 올릴 때 덮어써집니다. 버전 이름이 없는 .conf 디렉터리에 두면 설정이 살아남습니다.

무엇을 하고 싶은가 — 어디를 고치나

하고 싶은 것	고칠 곳	절
서버 자원을 보고 싶다	conf/khan-sys-agent.conf 의 khan.host·khan.port	설치
특정 네트워크 카드·디스크만 보고 싶다	같은 파일의 khan.network.interfaces·khan.disk.mounts	설정 표
Apache·NGINX 를 보고 싶다	plugins/disabled.txt 에서 켜고, 웹 서버에 상태 페이지를 연다	Apache · NGINX
HAProxy 를 보고 싶다	같은 방식 + HAProxy 에 stats 페이지 설정	HAProxy
데이터베이스를 보고 싶다	플러그인을 켜고, DB 에 조회용 계정을 만들고, 콘솔에서 한 번 더 켠다	MySQL · Cubrid
컨테이너를 보고 싶다	플러그인을 켜고, 런타임 소켓을 읽을 권한을 준다	Docker · CRI-O · containerd
에이전트를 껐다 켜고 싶다	bin/start.sh · bin/kill.sh	시작 및 종료
여러 서버에 한 번에 깔고 싶다	콘솔의 "설치 명령 복사"	인라인 설치

플러그인은 켜는 것만으로 끝나지 않습니다

대부분 대상 제품 쪽에도 설정이 필요합니다. Apache 는 상태 페이지를 열어야 하고, 데이터베이스는 조회 권한을 가진 계정이 있어야 하며, 데이터베이스는 콘솔에서 한 번 더 켜야 합니다. 각 플러그인 절에 "APM 모니터링을 위한 … 설정 방법" 으로 함께 실려 있습니다.

시스템 에이전트 다운로드

콘솔에서 설치 파일을 내려받습니다. 설치형과 클라우드는 내려받는 화면만 다르고, 파일을 받은 뒤 절차는 같습니다.

설정 > 가이드 & 다운로드

시스템 에이전트를 설치하기 위한 파일을 내려받습니다.
"다운로드" 버튼에 오른쪽 마우스 버튼을 이용해 "링크 주소 복사"를 클릭합니다.

설치 대상이 원격 Linux 서버라면, 복사한 링크 주소를 그 서버에서 wget 으로 바로 받는 편이 빠릅니다. 아래는 명령 형태의 예시이며, 주소는 방금 복사한 값을 씁니다.

• 시스템 에이전트 다운로드

$ wget "<복사한 링크 주소>"

[클라우드 전용] 에이전트 설치 안내 > SYS AGENT 탭

클라우드 APM 을 쓰는 경우 내려받는 자리가 다릅니다.

에이전트 설치 안내 > SYS AGENT 를 선택하면 아래와 같이 Download SYS Agent 를 클릭할 수 있는 페이지가 나옵니다. 파일을 받은 뒤부터는 위와 같습니다.

시스템 에이전트 설치

• 파일 압축해제

$ unzip sys-agent.zip

• 에이전트 설정 변경

$ cd khan-sys-agent
$ vi conf/khan-sys-agent.conf

• 접속 정보 설정

파일에 기본값이 채워진 상태로 들어 있으므로 두 줄만 고치면 됩니다.

khan.host=192.168.0.77        # APM 서버 주소 (또는 도메인)
khan.port=80                  # APM 서버 포트

나머지 항목은 모두 # 으로 주석 처리되어 있고, 기본값으로 동작합니다. 특정 네트워크 카드나 디스크만 보고 싶을 때만 주석을 풀어 값을 넣으십시오 — 전체 항목은 다음 절의 표에 있습니다.

khan.host 값이 틀리면 조용히 실패합니다

값이 잘못돼도 에이전트 프로세스는 정상적으로 떠 있습니다. 다만 콘솔에 서버가 나타나지 않습니다. 시작한 뒤 로그에서 Connected. 를 확인하십시오 (시작 및 종료 참고).

khan-sys-agent.conf 파일의 설정

khan-sys-agent.conf 파일의 설정값들은 다음과 같습니다.

설정 항목 (khan-agent.conf)	환경 변수	설명	기본값
khan.host	OMAPM_HOST	OPENMARU APM 서버의 IP 를 입력합니다. 또는 도메인을 입력 하는 경우 http:// or ws:// (tls 의 경우 https:// or wss://)
khan.port	OMAPM_PORT	OPENMARU APM 서버의 포트 번호를 입력합니다.
khan.tls	OMAPM_TLS	TLS 활성화 여부	false
khan.default.network.name	OMAPM_DEFAULT_NETWORK_NAME	기본 네트워크 카드 지정 ex) eth0
agent.compress.type	OMAPM_AGENT_COMPRESS_TYPE	암호화 알고리즘	snappy
khan.netstat	OMAPM_NETSTAT	네트워크 모니터링 여부(netstat)	true
khan.network.interfaces	OMAPM_NETWORK_INTERFACES	설정된 네트워크 인터페이스만 모니터링 ex) eth0,eth1,ens192,lo,tun0,vxlan_sys_4789	모든 인터페이스
khan.disk.mounts	OMAPM_DISK_MOUNTS	설정된 마운트 디스크만 모니터링 ex) /,/home,/data,/var/lib/docker/containers,C,D
khan.allow.commands	OMAPM_ALLOW_COMMANDS	에이전트에서 실행 명어를 제한 ex) service,systemctl
—	OMAPM_NAME	SYS 에이전트 이름 한 머신에 2개 이상의 에이전트를 설치 할 경우 구분 (Openmaru SYS Container 이미지에만 해당)

시스템 에이전트의 플러그인 설정

여기까지 하면 운영체제 자원(CPU·메모리·디스크·네트워크)은 이미 수집됩니다. 플러그인은 그 서버에서 함께 도는 다른 제품까지 보려고 켭니다.

플러그인	켜면 볼 수 있는 것	대상 제품에 필요한 것
Apache	요청 수·응답 코드 분포·워커 상태·mod_jk	mod_status · mod_info 를 localhost 에서 열기
NGINX	요청 수·활성 연결 수	stub_status 를 localhost 에서 열기
HAProxy	백엔드 상태·연결 수	listen stats 페이지 설정
MySQL	세션 수·느린 쿼리·InnoDB 상태	조회용 계정 + performance_schema · slow log
CUBRID	브로커·데이터베이스 상태	cm.conf 의 support_mon_statistic=YES + 콘솔에서 켜기
Docker	컨테이너별 CPU·메모리·네트워크	docker.sock 읽기 권한
CRI-O	같음 (OpenShift 3.6+)	crio.sock 읽기 권한
containerd	같음 (Kubernetes)	containerd.sock 읽기 권한

쓰지 않는 것은 켜지 마십시오. 켠 플러그인은 대상 제품에 주기적으로 상태를 물어보므로, 없는 제품을 켜 두면 수집 오류가 로그에 계속 쌓입니다.

플러그인을 켜는 순서

1) plugins/disabled.txt 에서 켤 플러그인의 줄 앞에 # 을 붙인다   ← 주석 처리 = 켜기
2) plugins/<플러그인>.conf/config.properties 에 접속 정보를 적는다
3) 대상 제품 쪽 설정을 바꾼다 (위 표의 세 번째 칸)
4) bin/kill.sh → bin/start.sh 로 에이전트를 다시 시작한다

disabled.txt 는 이름 그대로 "끌 목록" 입니다

파일에 적혀 있는 플러그인이 꺼집니다. 켜려면 그 줄을 지우거나 앞에 # 을 붙여 주석으로 만드십시오. 헷갈리기 쉬운 부분입니다.

플러그인 Enable 설정

플러그인을 사용하도록 설정하려면 plugins/disabled.txt 파일에 아래와 같이 설정하여 사용할 플러그인을 설정할 수 있습니다.

• plugins/disabled.txt 파일

#
# name to disable plugin
#

khan-plugin-apache
khan-plugin-nginx
khan-plugin-docker
khan-plugin-crio
khan-plugin-containerd
khan-plugin-cubrid
khan-plugin-mysql

• khan-plugin-apache와 khan-plugin-docker 플러그인을 사용하도록 설정

#
# name to disable plugin
#

#khan-plugin-apache
khan-plugin-nginx
#khan-plugin-docker
khan-plugin-crio
khan-plugin-containerd
khan-plugin-cubrid
khan-plugin-mysql

plugins 디렉터리에 플러그인 zip 파일을 복사해 놓고 시스템 에이전트를 시작하면 플러그인 모듈이 구동됩니다. 이때 zip 파일의 압축이 풀려 디렉터리가 만들어집니다.

Apache 플러그인 설정

Apache 플러그인의 설정은 plugins/khan-plugin-apache-5.1.0/conf 아래에 있는 config.properties파일을 사용하게 됩니다.

플러그인 Upgrade등으로 설정파일이 변경될 수 있기 때문에, plugins/khan-plugin-apache.conf 디렉토리에 config.properties 파일에 설정하면 플러그인 파일과 설정파일을 분리하여 사용할 수 있습니다.

• config.properties 설정파일 내용

instance=apache
host=localhost
port=80
statusUrlPath=/status?auto
infoUrlPath=/server-info?server

statusUrlPath·infoUrlPath 는 웹 서버에 열어 둔 상태 페이지 주소와 같아야 합니다. 나머지 항목은 기본값으로 동작하며, 전체 목록은 아래 표에 있습니다.

설정항목	설명	기본값
instance	OPENMARU APM에 표시될 아파치 인스턴스 이름	apache
host	정보를 수집할 Apache 서버의 Host명, localhost를 사용하는 것이 유리함	localhost
port	정보를 수집할 Apache 서버의 포트번호	80
username	현재 사용안함
password	현재 사용안함
infoUrlPath	Apache의 mod_info가 설정된 URL localhost에서 접속할 수 있도록 설정합니다. https://httpd.apache.org/docs/2.4/ko/mod/mod_info.html
statusUrlPath	Apache의 mod_status가 설정된 URL localhost에서 접속할 수 있도록 설정합니다. https://httpd.apache.org/docs/2.4/ko/mod/mod_status.html
jkStatusUrlPath	Apache jkstatus 페이지 URL을 입력합니다.	/jkstatus
modClusterManagerUrlPath	Apache mod cluster manager 접속 페이지 URL을 입력합니다.	/mod_cluster_manager
maxConnections	아파치 정보를 수집하기 위한 최대 연결 수, 1개면 충분함
maxConnectionsPerHost	아파치 정보를 수집하기 위한 연결 수
maxConnectionsPerRoute	아파치 정보를 수집하기 위한 연결 수
waitIdleCheck	Idle 체크 대기 시간
waitIdleClose	Idle Close 대기 시간
requestTimeout	요청에 응답이 없을 경우 Timeout
sessionTimeout	세션 Timeout
http.status.code.log.dir	HTTP 응답코드 모니터링 설정	homepage:/data/logs/homepage:8 console에 표시될 서비스명:Web 서버 log디렉터리 경로:응답코드 위치(공백 기준)
http.status.code.log.exclude.url.patterns	응답코드 모니터링에서 제외할 URL 패턴 지정
http.status.code.log.exclude.file.patterns	응답코드 모니터링에서 제외할 log 파일 패턴 지정

APM 모니터링을 위한 Apache 설정 방법

httpd.conf 파일에 아래와 같이 /status, /server-info URL을 localhost에서 읽을 수 있도록 권한을 설정합니다. 이때, ExtendedStatus를 On으로 설정하여 server-status에서 많은 정보를 얻을 수 있도록 합니다.

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /status>
  SetHandler server-status
  Order deny,allow
  Deny from all
  Allow from localhost
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
  SetHandler server-info
  Order deny,allow
  Deny from all
  Allow from localhost
</Location>

NGINX 플러그인 설정

nginx 플러그인 설정은 plugins/khan-plugin-nginx-5.1.0/conf 아래에 있는 config.properties 파일을 사용합니다. 플러그인 Upgrade등으로 설정파일이 변경될 수 있기 때문에, plugins/khan-plugin-nginx.conf 디렉토리에 config.properties 파일에 설정하면 플러그인 파일과 설정파일을 분리하여 사용할 수 있습니다.

config.properties 설정파일 내용

instance=nginx
host=localhost
port=80
statusUrlPath=/nginx_status

statusUrlPath 는 NGINX 에 설정한 stub_status 주소와 같아야 합니다. 나머지 항목은 기본값으로 동작하며, 전체 목록은 아래 표에 있습니다.

설정항목	설명	기본값
instance	OPENMARU APM에 표시될 nginx 인스턴스 이름	nginx
host	정보를 수집할 nginx 서버의 Host명, localhost를 사용하는 것이 유리함	localhost
port	정보를 수집할 nginx 서버의 포트번호	80
username	현재 사용안함
password	현재 사용안함
statusUrlPath	nginx의 http_stub_status_module이 설정된 URL localhost에서 접속할 수 있도록 설정합니다. http://nginx.org/en/docs/http/ngx_http_stub_status_module.html
maxConnections	nginx 정보를 수집하기 위한 최대 연결 수, 1개면 충분함	1
maxConnectionsPerHost	nginx 정보를 수집하기 위한 연결 수
maxConnectionsPerRoute	nginx 정보를 수집하기 위한 연결 수
waitIdleCheck	Idle 체크 대기 시간
waitIdleClose	Idle Close 대기 시간
requestTimeout	요청에 응답이 없을 경우 Timeout
sessionTimeout	세션 Timeout

APM 모니터링을 위한 nginx 설정 방법

ngx_http_stub_status_module 은 기본적으로 빌드되지 않기 때문에 nginx/conf.d/default.conf 파일을 아래 내용을 추가합니다.

    location /nginx_status {
    stub_status;
    allow 127.0.0.1;
    deny all;
}

HAproxy 플러그인 설정

HAproxy 플러그인 설정은 plugins/khan-plugin-haproxy-5.1.0/conf 아래에 있는 config.properties파일을 사용합니다. 플러그인 Upgrade등으로 설정파일이 변경될 수 있기 때문에, plugins/khan-plugin-haproxy.conf 디렉토리에 config.properties 파일에 설정하면 플러그인 파일과 설정파일을 분리하여 사용할 수 있습니다.

config.properties 설정파일 내용

#
# HAProxy status monitoring
#

instance=haproxy11
host=localhost
port=9000
username=admin
password=opennaru!2
infoUrlPath=/haproxy_stats
statusUrlPath=/haproxy_stats;csv

maxConnections=1
maxConnectionsPerHost=1
maxConnectionsPerRoute=1
waitIdleCheck=60000
waitIdleClose=120
requestTimeout=1000
sessionTimeout=1000

APM 모니터링을 위한 HAProxy 설정 방법

HAProxy를 모니터링하려면, HAProxy에 statistics 페이지가 설정되어 있어야 합니다.

1. 중략 ...
listen stats        #Listen on all IP’s on port 9000
bind 0.0.0.0:9000
mode http
balance
timeout client 5000
timeout connect 4000
timeout server 30000

       #This is the virtual URL to access the stats page
       stats uri /haproxy_stats

       #Authentication realm. This can be set to anything. Escape space characters with a backslash.
       stats realm HAProxy\ Statistics

       #The user/pass you want to use. Change this password!
       stats auth admin:openmaru

       #This allows you to take down and bring up back end servers.
       #This will produce an error on older versions of HAProxy.
       stats admin if TRUE

Cubrid 플러그인 설정

cubrid 플러그인의 설정은 plugins/khan-plugin-cubrid-5.1.0/conf 아래에 있는 config.properties 파일을 사용하게 됩니다. 플러그인 Upgrade등으로 설정파일이 변경될 수 있기 때문에, plugins/khan-plugin-cubrid.conf 디렉토리에 config.properties 파일에 설정하면 플러그인 파일과 설정파일을 분리하여 사용할 수 있습니다.

config.properties 설정파일 내용

cubridHome=/home/cubrid
excludedBrokers=query_editor

cubridHome 을 비우면 환경변수 CUBRID 를 씁니다. 나머지 항목은 기본값으로 동작하며, 전체 목록은 아래 표에 있습니다.

설정항목	설명	기본값
cubridHome	cubrid의 홈 디렉토리 경로를 입력합니다.
excludeBrokers	상태 수집에서 제외하고자 하는 Broker의 이름을 입력합니다.

APM 모니터링을 위한 Cubrid 설정 방법

cubrid 홈 디렉토리에 conf/cm.conf support_mon_statistic를 YES로 수정하여 데이터 베이스의 리소스 모니터링을 활성화 합니다.

~
# support monitoring statistic (YES/NO), default NO
# If you want to use the advanced monitoring feature on CUBRID Manager,
# you should set this value to YES.

support_mon_statistic=YES
~

콘솔에서 Cubrid 모니터링 켜기

플러그인과 Cubrid 쪽 설정을 마쳐도 콘솔에서 켜야 수집이 시작됩니다.

설정 > 모니터링 설정 의 일반 탭에서 모니터링 확장의 데이터베이스 모니터링 사용을 예 로 바꾸고 저장합니다.

이 항목 하나가 MySQL·MariaDB·CUBRID 를 함께 켭니다 — 데이터베이스별로 따로 켜지 않습니다.

Docker 플러그인 설정

Docker 플러그인의 설정은 plugins/khan-plugin-docker-5.1.0/conf 아래에 있는 config.properties파일을 사용하게 됩니다.

플러그인 Upgrade등으로 설정파일이 변경될 수 있기 때문에, plugins/khan-plugin-docker.conf 디렉토리에 config.properties 파일에 설정하면 플러그인 파일과 설정파일을 분리하여 사용할 수 있습니다.

config.properties 설정파일 내용

dockerHost=unix:///var/run/docker.sock

에이전트를 돌리는 계정이 이 소켓을 읽을 수 있어야 합니다. 나머지 항목은 기본값으로 동작하며, 전체 목록은 아래 표에 있습니다.

설정항목	설명	기본값
docker.host	docker 데몬의 호스트이름이나 IP를 입력합니다.	localhost
docker.port	docker 데몬의 포트 번호를 입력합니다.	4342
docker.connect.type	Docker Engine이 생성하는 Socket File을 사용할 것인지, HTTP를 이용하여 Docker Engine에 접근할 것인지를 지정합니다. sock, net을 사용할 수 있습니다. Openshift에서는 반드시 sock을 사용해야 합니다.	sock
docker.sock	Docker Engine이 생성하는 Socket File을 지정합니다. Red Hat 계열 리눅스에서는 /var/run/docker.sock 파일을 사용합니다.	/var/run/docker.sock
docker.cgroup.driver.type	cgroup driver type을 지정합니다. Openshift 3.6은 systemd 를 사용하고 Openshift 3.5는 cgroup 을 사용합니다.

CRI-O 플러그인 설정

CRI-O 플러그인의 설정은 plugins/khan-plugin-crio-5.1.0/conf 아래에 있는 config.properties파일을 사용하게 됩니다.

플러그인 Upgrade등으로 설정파일이 변경될 수 있기 때문에, plugins/khan-plugin-crio.conf 디렉토리에 config.properties 파일에 설정하면 플러그인 파일과 설정파일을 분리하여 사용할 수 있습니다.

• config.properties 설정파일 내용

crioHost=unix:///var/run/crio/crio.sock

OpenShift 3.6 이상은 이 방식을 씁니다. 나머지 항목은 기본값으로 동작하며, 전체 목록은 아래 표에 있습니다.

설정항목	설명	기본값
crio.sock	CRI-O가 생성하는 Socket File을 지정합니다. Red Hat 계열 리눅스에서는 /var/run/crio.sock 파일을 사용합니다.	/var/run/crio/crio.sock

CONTAINERD 플러그인 설정

Containerd 플러그인의 설정은 plugins/khan-plugin-containerd-5.1.0/conf 아래에 있는 config.properties파일을 사용하게 됩니다.

플러그인 Upgrade등으로 설정파일이 변경될 수 있기 때문에, plugins/khan-plugin-crio.conf 디렉토리에 config.properties 파일에 설정하면 플러그인 파일과 설정파일을 분리하여 사용할 수 있습니다.

• config.properties 설정파일 내용

containerdHost=unix:///run/containerd/containerd.sock
namespace=k8s.io

쿠버네티스는 namespace 가 k8s.io 입니다. 나머지 항목은 기본값으로 동작하며, 전체 목록은 아래 표에 있습니다.

설정항목	설명	기본값
containerd.sock	CONTAINERD가 생성하는 Socket File을 지정합니다. Red Hat 계열 리눅스에서는 /var/run/containerd/containerd.sock 파일을 사용합니다.	/var/run/containerd/containerd.sock

MySQL 플러그인 설정

Containerd 플러그인의 설정은 plugins/khan-plugin-mysql.conf 아래에 있는 config.properties파일을 사용하게 됩니다.

플러그인 Upgrade등으로 설정파일이 변경될 수 있기 때문에, plugins/khan-plugin-mysql.conf 디렉토리에 config.properties 파일에 설정하면 플러그인 파일과 설정파일을 분리하여 사용할 수 있습니다.

MySQL 플러그인에서는 Mysql, Mariadb, Percona 를 지원합니다.

설정하기 전 MySQL 의 계정 생성 및 권한 할당이 필요합니다.

MySQL 5.6 또는 MySQL 5.7 경우 다음 명령을 사용하여 사용자를 만듭니다.

## 계정 생성
mysql> CREATE USER 'openmaru'@'localhost' IDENTIFIED BY '[PASSWORD]';

MySQL 8.0 이상의 경우 비밀번호 암호화 방식을 사용하여 사용자를 만듭니다.

mysql> CREATE USER 'openmaru'@'localhost' IDENTIFIED WITH mysql_native_password by '[PASSWORD]';

권한을 등록합니다.

## 실행중인 세션 리스트 조회
mysql> GRANT PROCESS,SELECT,EXECUTE ON . TO 'openmaru'@'localhost';

## 실행중인 세션에 대한 쿼리 강제 종료
mysql> grant super on . to 'openmaru'@'localhost';

performance_schema 가 활성화된 되지 않은 경우

mysql> SHOW VARIABLES LIKE 'performance_schema';
+--------------------+-------+
| Variable_name      | Value |
+--------------------+-------+
| performance_schema | ON    |
+--------------------+-------+

mysql> GRANT SELECT ON performance_schema.* TO 'openmaru'@'localhost';

• Slow Log 모니터링 활성화

노트

log_output 이 TABLE 일 때만 사용할 수 있습니다.

mysql> show global variables where VARIABLE_NAME in ('slow_query_log', 'log_output');
+--------------------+-------+
| Variable_name      | Value |
+--------------------+-------+
| slow_query_log     | ON    |
| log_output         | TABLE |
+--------------------+-------+

my.conf
[mysqld]
general_log=on
log_output='TABLE'

• config.properties 설정파일 내용

#
# khan-plugin-mysql
#

# Enable remote monitoring (default: false)
#0.remote.enabled=false
0.cluster.name=
0.instance.id=om-mariadb
#  - ex) jdbc:mariadb://localhost:3306/mysql, jdbc:mysql://localhost:3306/mysql
0.jdbc.jdbcUrl=jdbc:mariadb://192.168.23.23:3306/mysql
#  - ex) org.mariadb.jdbc.Driver, com.mysql.jdbc.Driver, com.mysql.cj.jdbc.Driver
0.jdbc.driverClassName=org.mariadb.jdbc.Driver
0.jdbc.username=root
0.jdbc.password=opennaru
0.jdbc.maximumPoolSize=10
0.jdbc.minimumIdle=0
0.jdbc.validationTimeout=5000
0.jdbc.connectionTimeout=5000
0.path.my.cnf=/etc/my.cnf

• jdbc 설정은 HikariCP 옵션을 따른다.
• 0. 과 같이 숫자 접두어의 경우 N 개의 MySQL 을 모니터링할 때 씁니다.(로컬뿐만 아니라 원격지 MYSQL 모니터링 가능)
  • 0.instance.id=db1
  • 0....
  • 1.instance.id=db2
  • 1....

설정항목	설명	기본값
0.cluster.name	HA 가 구성된 경우 같은 명일 경우 그룹으로 인식
0.instance.id	수집서버에서 구분 할 수 있는 이름	필수
0.jdbc.jdbcUrl	접속 JDBC URL	필수
0.jdbc.driverClassName	Driver Class	필수, org.mariadb.jdbc.Driver, com.mysql.cj.jdbc.Driver
0.jdbc.username	사용자명	필수
0.jdbc.password	비밀번호	필수
0.jdbc.maximumPoolSize	Pool 최대 사이즈	10
0.jdbc.minimumIdle	Pool 최소 사이즈	0
0.jdbc.validationTimeout	유효성 체크 타임아웃	5000
0.jdbc.connectionTimeout	Pool 얻어오기전까지 기다리는 시간
0.path.my.cnf	my.conf 설정 파일 위치 (로컬 모니터링일 경우)	/etc/my.cnf

• JDBC 드라이버

아래 디렉토리의 드라이버 파일이 호환되지 않는 경우 교체합니다.

• plugins/khan-plugin-mysql-5.1.0/lib/
  • mysql-connector-java-8.0.30.jar
  • mariadb-java-client-1.8.0.jar

시스템 에이전트 시작 및 종료

• 시스템 에이전트 시작

$ cd khan-sys-agent/bin
$ ./start.sh

• 시스템 에이전트 종료

$ ./kill.sh

• 시스템 에이전트 로그확인

$ ./tail.sh

정상적으로 기동되면 로그에 다음 세 가지가 차례로 나타납니다.

확인할 것	로그에 나오는 내용
플러그인이 의도대로 켜졌나	플러그인마다 status: enable 또는 status: disable
APM 서버에 접속했나	Trying to connect : wss://… 다음에 Connected.
수집이 시작됐나	Successfully Connected.

Connected. 가 나오지 않으면 khan-sys-agent.conf 의 khan.host · khan.port 값과 방화벽을 먼저 확인하십시오. 에이전트는 접속하지 못해도 프로세스는 계속 떠 있습니다.

켠 적 없는 플러그인이 enable 로 나오거나 그 반대라면 plugins/disabled.txt 를 다시 확인하고 에이전트를 재시작하십시오.

시스템 에이전트 인라인 설치

여러 대의 서버에 시스템 에이전트를 설치할 때는 명령 한 줄을 복사해 붙여 넣는 방식이 빠릅니다. 파일을 서버마다 내려받아 옮길 필요가 없습니다.

설정 > 가이드 & 다운로드 의 에이전트 설치 파일 에서 OPENMARU APM 시스템 에이전트 줄의 설치 명령 복사 버튼을 클릭합니다.

설치 요약

구분	설명
수집서버 IP	192.168.30.6
관리 Linux 사용자 정보	khansys(1106) / khan(1105)
System Agent 서버 IP	192.168.2.9
설치 디렉토리	/svc/test/khan-agent
Plugin 사용 여부	n,n,n,n,n,n,n Apache,Nginx,Docker,Crio,Containerd,Cubrid,MySQL

## 클립보드에 복사된 텍스트 붙여 넣기
$ bash <(curl -s http://192.168.30.6/monitoring/api/agent/download/sysInstall) \
  khansys 1106 \
  khan 1105 \
  192.168.2.9 \
  192.168.30.6 \
  /svc/test/khan-agent \
  n,n,n,n,n,n,n \
  http://192.168.30.6/monitoring/resources/khan-sys-agent-5.1.0.zip

Starting installation.
########################
User : khansys
UID : 1106
Group : khan
GID : 1105
BIND IP : 192.168.2.9
TARGET IP : 192.168.30.6
Installed Path : /tmp/khan-agent/khan-sys-agent
Eabled Plugins |
  Apache	: n
  Nginx		: n
  Docker	: n
  Crio		: n
  Containerd	: n
  Cubrid	: n
  MySQL		: n
Start Install? (y/n) [n] :