Web Server Agent 설치

이제 모든 관련 문서를 확인했습니다. 상세한 답변을 작성합니다.

exemONE Web Server Agent 설치 방법 및 설정 상세 가이드

참고 문서:
Web Server Agent 개요
Web Server Agent Binary 설치
Web Server Agent Docker 설치
Web Daemon - Nginx Module 설치
Web Daemon - Apache Module 설치
모듈별 사용 Port
WebServer CPU/Memory 지표 설정

1. 모듈 설명

exemONE Web Server Agent(exem-webserver-agent)는 Nginx, Apache 등 웹 서버의 성능 지표(트랜잭션, 응답시간, 요청 수 등)를 수집하여 exemONE 수집 서버(Receiver)로 전송하는 모니터링 에이전트입니다.

Web Server 모니터링은 2단계 구조로 이루어져 있습니다:

Web Server Agent: 수집 서버(Receiver)와 통신하는 중간 에이전트 (Binary 또는 Docker로 설치)
Web Module (Nginx Module / Apache Module): 웹 서버에 직접 탑재되어 데이터를 수집하고 Web Server Agent로 전송하는 모듈

[Nginx/Apache] ←→ [Web Module] --12848-→ [Web Server Agent] --9009-→ [Receiver/수집서버]

2. 지원 버전

항목	지원 버전
exemONE	3.0.506.15.0 릴리즈 버전 이후
Java	JDK 17 이상 (Web Server Agent Binary 설치 시)
Nginx	1.14.1, 1.14.2, 1.18.0, 1.20.1, 1.24.0, 1.27.0, 1.28.0
Apache	2.4

개별 모듈 최소 버전:

exemone-alerter-v3.0.506.15.6 
exemone-api-v3.0.506.15.18 
exemone-core-v3.0.506.15.12 
exemone-gateway-v3.0.506.15.1 
exemone-ingester-v3.0.506.15.11 
exemone-receiver-v3.0.506.15.5 
exemone-front-v3.0.506.15.27 

3. 통신 포트

출발지	도착지	Type	Port	내용
Web Server Agent	exemONE 수집 서버 (Receiver)	gRPC	9009	Receiver와의 통신
Web Module (Nginx/Apache)	Web Server Agent	TCP	12848	모듈 → Agent 데이터 전송

방화벽에서 9009 포트 (Receiver 연결용)와 12848 포트 (모듈 연결용)를 반드시 오픈해야 합니다.

4. 전체 설치 흐름

Nginx 모니터링 절차:

Web Server Agent 설치 (Binary 또는 Docker)
exemONE 웹 UI에서 Agent 등록
Nginx/Apache에 Web Module 설치 후 웹 서버와 함께 구동

5. [Phase 1] exemONE 웹 UI에서 Agent 등록

단계 1. exemONE 설정 페이지 접속

좌측 메뉴에서 [프로필 > 환경설정] 으로 이동합니다.

단계 2. [관리 > 에이전트] 메뉴 이동

단계 3. 웹서버 에이전트 등록

상단의 [에이전트 추가] 버튼을 클릭합니다.

에이전트 타입은 반드시 "웹 서버" 로 선택
[갱신] 버튼을 클릭하면 에이전트 ID와 엑세스 토큰이 발급됩니다
에이전트 이름은 직접 입력

발급받은 에이전트 ID와 엑세스 토큰 정보를 반드시 기록해 두시고, [저장] 버튼을 클릭하여 에이전트가 목록에 정상적으로 추가되었는지 확인하세요.

6. [Phase 2] Web Server Agent 설치

Web Server Agent는 2가지 설치 방식을 제공합니다.

설치 방식	적합 환경	특징
Binary 설치	물리 서버, VM 환경	bin 파일로 설치, JDK 17 필수
Docker 설치	Docker 환경	Docker 이미지 로드 후 docker-compose로 실행

6-1. Binary 설치

사전 설정

JDK 17 이상 설치 필수
- JDK 17 이하 버전만 설치되어 있는 경우, 함께 전달된 zulu17 패키지(예: zulu17.58.21-ca-jdk17.0.15-linux_x64.tar.gz)를 활용하여 JDK 17을 설치
방화벽 포트 개방: 9009 포트, 12848 포트

단계 1. 설치 파일 준비

exem-webserver-agent_${VERSION}.bin 바이너리 설치 파일을 준비합니다.

단계 2. 실행 권한 부여

chmod +x exem-webserver-agent_${VERSION}.bin

단계 3. 설치 파일 실행

./exem-webserver-agent_${VERSION}.bin

단계 4. 설치 안내 및 JAVA 확인

[1] 을 입력하면 설치가 시작됩니다
JAVA 17 이상이 설치되어 있는 경우: [y] 입력
JAVA 17 이상이 설치되어 있지 않은 경우: [n] 입력 시 설치 스크립트가 종료됩니다

단계 5. Agent 정보 입력

exemONE에서 발급받은 Token, Agent ID, Agent Name, Receiver IP 를 입력합니다.

단계 6. 설치 디렉토리 입력

설치할 디렉토리를 입력하면, 해당 경로 아래에 webserver 폴더가 자동으로 생성됩니다.

단계 7. 실행

exem/webserver/bin 폴더에서 실행합니다.

단계 8. 설치 완료 확인

설치가 완료되면 bin 디렉토리의 startAgent.sh 스크립트에 실행 정보가 자동으로 입력됩니다.

6-2. Docker 설치

사전 설정

방화벽 포트 개방: 9009 포트, 12848 포트

단계 1. 설치 파일 압축 해제

exem-webserver-agent-package.tar.gz 파일의 압축을 해제합니다.

단계 2. 도커 이미지 로드

docker load -i exemone-webserver-agent-v3.0.12.tar.gz

단계 3. Docker 설치 관련 환경 변수 설정

수정 파일: exem-webserver-agent-package/.env

#exemONE 실행 유저 ID 
EXEMONE_USER_UID=1000
EXEMONE_USER_GID=1000

#Webserver 패키지 실행 경로 지정 
EXEMONE_WEBSERVER_AGENT_PATH=exem-webserver-agent-package

#Webserver docker 이미지 및 버전 입력 
WEBSERVER_AGENT_IMAGE=maxgauge/exemone-webserver-agent
WEBSERVER_AGENT_VERSION=v3.0.16

단계 4. Webserver Agent 실행 관련 환경 변수 설정

exemONE에서 발급받은 Token, Agent ID, Agent Name, Receiver IP를 입력합니다.

수정 파일: exem-webserver-agent-package/configs/.env

#Webserver Agent 정보 입력(exemONE 웹페이지에서 발급받은 정보)
WEB_AGENT_NAME=webserver-docker-127
WEB_AGENT_ID=0da17add-a58d-4d86-b4c2-dec8e75c12ca
WEB_AGENT_ACCESS_TOKEN=8dba739c-124f-439b-82d4-822de3310def
WEB_AGENT_RECEIVER_ADDR=10.10.48.127:9009

단계 5. 포트 설정

exem-webserver-agent-package/docker-compose.yml 파일의 ports 항목에 필요한 포트를 추가합니다.

단계 6. 설치 및 실행 권한 부여

chmod +x exem-webserver-agent-package/install.sh

단계 7. Web Agent 구동

cd exem-webserver-agent-package
./scripts/restart.sh

7. [Phase 3] Web Module 설치 (Nginx / Apache)

Web Server Agent 설치 완료 후, 모니터링 대상 웹 서버에 Web Module을 설치해야 합니다.

7-1. Nginx Module 설치

사전 설정

Nginx가 설치되어 있어야 합니다
수집서버에 연동된 Web Agent가 구동 중이어야 합니다
Nginx 설치 버전을 확인합니다:

$ nginx -V
nginx version: nginx/1.18.0

바이너리 설치 파일을 준비합니다: setup_exem-nginx-module_{Version}.bin

단계 1. Nginx Module 설치 실행

./setup_exem-nginx-module_{Version}.bin

=====================================================
EXEM NGINX Module Setup
=====================================================
choise work
1. unpack
2. install(default)
:
SETUP TYPE[install]
Delete directory after work?[y(default)/n]:
unpack nginx modules

=====================================================
exem-nginx-module v3.0.8(96163db) Install on linux 3.10
=====================================================
nginx supported version:
> 1.14.1 1.14.2 1.18.0 1.20.1 1.24.0 1.27.0 1.28.0

// 모니터링할 Nginx 버전을 선택합니다. 
Install Nginx Version(version|all): 1.24.0

// 설치 디렉토리 및 설정 파일을 선택합니다.
// 미입력 시, 기본값으로 적용됩니다. 
Install Directory (/home/exemone/nginx-module):
nginx module config filename(exem_ngx_mod.conf):

// unique id를 미설정 시, Nginx 재구동할 때마다 앱이 개별 등록됩니다.
(optional)Do you want to fix the 'unique id'?[yes(default)/no]:
Group ID to register(default):

// 미입력 시, hostname으로 적용됩니다. 
(optional)Module Name to register(exemone-48.130): test

Install Directory [/home/exemone/nginx-module]
Group ID [default]
Module Name [test]
Generated Unique ID [abc4b7c6-8138-438a-8aa3-4005603a26b9]
=====================================================

// nginx 설정 파일에 아래 내용 추가 필요합니다. 
+--> Add the following line to 'nginx.conf' >--+
load_module "/home/exemone/nginx-module/modules/ngx_http_exem_module_1.24.0.so";
http {
  include /home/exemone/nginx-module/conf/exem_ngx_mod.conf;
}

단계 2. exem_ngx_mod.conf 파일 수정

파일 위치: ~/nginx-module/conf/exem_ngx_mod.conf

############################################
### EXEM Nginx Module Configuration File ###

exem_group_id default;
exem_unique_id abc4b7c6-8138-438a-8aa3-4005603a26b9;

# module name(default: hostname)
# exem_module_name test;

# EXEMBID with host agent
#exem_bid <input host bid>;

# log path (default:logs/exem_ngx_mod.log)
#exem_log_path logs/exem_ngx_mod.log;
# log level (default:none)
#exem_log_level debug;

# connection ip to agent (default:127.0.0.1)
exem_connect_ip 10.10.48.130;

# connection port to agent (default:12848)
#exem_connect_port 12848;

# skip collect exem metrics (default:true)
#exem_skip_metrics_req true;

server {
    listen 127.0.0.1:12849;
    server_name 127.0.0.1;
    location /exem/v1/metrics {
        stub_status_exem;
    }
}

Nginx Module 설정 옵션 상세

옵션	기본값	설명
`exem_unique_id`	Random	한 개의 webserver로 묶을 아이디. 미설정 시 webserver 시작 때마다 랜덤 값으로 변경됨
`exem_group_id`	없음	화면에서 등록된 그룹 아이디
`exem_module_name`	hostname	화면에서 보여질 webserver name. 미설정 시 hostname으로 적용
`exem_bid`	hostname	연계된 host agent와 동일한 값으로 적용해야 함. 미설정 시 hostname으로 적용
`exem_log_level`	none	로그 레벨: none < error < warning < info < debug
`exem_log_path`	logs/mod.log	로그 파일 경로
`exem_log_max_size`	10	로그 파일 최대 크기(MB). 초과 시 새로 작성됨
`exem_connect_ip`	127.0.0.1	Web Server Agent에 연결할 IP
`exem_connect_port`	12848	Web Server Agent에 연결할 Port

단계 3. nginx.conf 파일 수정

모니터링 대상인 Nginx의 설정 파일에 아래 내용을 추가합니다:

load_module "/home/exemone/nginx-module/modules/ngx_http_exem_module_1.24.0.so";
http {
  include /home/exemone/nginx-module/conf/exem_ngx_mod.conf;
}

Nginx 모듈 호환성 에러 발생 시 조치

Nginx 실행 시 모듈 호환성 에러가 발생하면:

setenforce 0

참고: Nginx의 Master가 root로 실행 / Worker 노드가 nginx로 실행 중인 경우, nginx 모듈을 root로 설치하여 실행해야 합니다.

7-2. Apache Module 설치

사전 설정

Apache가 설치되어 있어야 합니다
수집서버에 연동된 Web Agent가 구동 중이어야 합니다
Apache 설치 버전을 확인합니다:

# apache2 -v
Server version: Apache/2.4.62 (Debian)
Server built:   2024-10-04T15:21:08

바이너리 설치 파일을 준비합니다: setup_exem-httpd-module_{Version}.bin

단계 1. Apache Module 설치 실행

./setup_exem-httpd-module_{Version}.bin

=====================================================
 EXEM HTTPD Module Setup 
=====================================================
choise work
1. unpack
2. install(default)
: 2
SETUP TYPE[install]
Delete directory after work?[y(default)/n]: y
unpack httpd modules

=====================================================
exem-httpd-module v3.0.10(344fb88) Install on linux 3.10
=====================================================
Install HTTPD Version(2.4): 2.4
Install Directory (/root/test/httpd-module): 
ExEm Connect IP(127.0.0.1): 127.0.0.1
ExEm Connect Port(12848): 12848
Group ID to register(default): apache-group
(optional)Module Name to register(a1cafd406aaf): apache-sample
EXEM BID with host agent(a1cafd406aaf)
httpd module config filename(exem_httpd_mod.conf): 
Do you want to fix the 'unique id'?[yes(default)/no]: yes

Install Directory [/root/test/httpd-module] 
Connect IP to Agent [127.0.0.1] 
Connect Port to Agent [12848] 
Group ID [apache-group] 
Module Name [apache-sample] 
Generated Unique ID [2fc7f9c7-ef23-435f-adb7-b6837389f728] 
=====================================================

+--> Add the following line to 'httpd.conf' >--+
# exem module
Include /root/test/httpd-module/conf/exem_httpd_mod.conf

단계 2. exem_httpd_mod.conf 파일 수정

파일 위치: ~/httpd-module/conf/exem_httpd_mod.conf

############################################
### EXEM Httpd Module Configuration File ###

LoadModule exem_module /root/test/httpd-module/modules/mod_exem_24_linux_64.so

<IfModule exem_module>

ExEmGroupID apache-group
ExEmUniqueID 2fc7f9c7-ef23-435f-adb7-b6837389f728

# module name(default: hostname)
ExEmModuleName apache-sample

# EXEMBID with host agent
ExEmBID a1cafd406aaf

# Send data(packet) logging
ExEmDump false

# default ip:127.0.0.1, port:12848
ExEmConnectIP 127.0.0.1
ExEmConnectPort 12848

# default 5 sec
ExEmConnectReconnectSec 5

# do not use 0(zero)
ExEmLogPath logs/mod_exem.log
ExEmLogLevel info

# default 10 Megabyte
ExEmLogMaxSize 10

# metrics configuration (default: 127.0.0.1:12829/exem/v1/metrics)
#ExEmMetricAddr 127.0.0.1:12829
#ExEmMetricLocation /exem/v1/metrics

</IfModule>

Apache Module 설정 옵션 상세

옵션	기본값	설명
`ExEmUniqueID`	Random	한 개의 webserver로 묶을 아이디. 미설정 시 시작 때마다 랜덤 값으로 변경됨
`ExEmGroupID`	"default"	수집 대상으로 관리될 그룹 아이디
`ExEmModuleName`	없음	화면에서 보여질 webserver name (미설정 시 hostname 사용)
`ExEmBID`	없음	host agent와 연동에 필요한 ID. hostname이 인프라스트럭처 호스트 목록에 동일 이름이 있을 경우 웹서버와 맵핑이 되지 않습니다
`ExEmDump`	false	debug 용 패킷 덤프 옵션
`ExEmConnectIP`	127.0.0.1	Web Server Agent에 연결할 IP
`ExEmConnectPort`	12848	Web Server Agent에 연결할 Port
`ExEmConnectReconnectSec`	5	Agent와 연결 끊어진 경우 재연결 시간(초)
`ExEmLogPath`	logs/mod_exem.log	로그 파일 경로
`ExEmLogLevel`	info	로그 레벨: none < error < warning < info < debug
`ExEmLogMaxSize`	10	로그 파일 최대 크기(MB). 초과 시 새로 작성됨
`ExEmMetricAddr`	127.0.0.1	Agent에서 metric 수집에 필요한 연결 주소
`ExEmMetricLocation`	12829	Agent에서 metric 수집에 필요한 연결 URI

단계 3. Apache 설정 파일 수정 및 재기동

모니터링 대상인 Apache 설정 파일에 exemONE Apache Module 설정 파일 경로를 include합니다.

고객사 Apache 환경에 따라 설정 파일이 다를 수 있습니다:

Debian/Ubuntu 계열: /etc/apache2/apache2.conf
Red Hat 계열: /etc/httpd/conf/httpd.conf

# exem module
Include /root/test/httpd-module/conf/exem_httpd_mod.conf

8. CPU / Memory 지표 모니터링 설정 (선택)

Web Server 화면에서 Process CPU, Process Memory 등 사용량을 함께 보려면 추가 설정이 필요합니다.

사전 조건: Web Module 서버에 host-agent가 설치되어 있어야 합니다.

단계 1. Web Module의 EXEMBID 설정

Web Module conf 폴더에서 EXEMBID (Nginx: exem_bid, Apache: ExEmBID)를 설정합니다. 빈 값이면 hostname으로 저장됩니다.

주의: infrastructure에 동일한 hostname이 있다면 해당 EXEMBID 부분을 변경해야 합니다.

단계 2. Host Agent의 EXEMBID 동일 설정

Web Module에 설정한 EXEMBID와 동일하게 host-agent에도 설정해야 합니다. host-agent도 EXEMBID를 따로 설정하지 않으면 hostname을 가져옵니다.

확인 방법

설정이 완료되면 webServer 화면에서 Process 관련 필드에 데이터가 표시됩니다.

webserver > webserver Detail > metric 탭에서 Process 태그가 붙어있는 지표를 확인할 수 있습니다.

9. 주의사항

exemONE 버전 확인 필수: Web Server Agent는 exemONE 3.0.506.15.0 이후 버전에서만 지원됩니다.
JDK 17 이상 필수 (Binary 설치 시): JDK 17 미만 버전에서는 Agent가 구동되지 않습니다.
방화벽 포트 2개 개방 필수: 9009 (Receiver 연결), 12848 (모듈 연결) 포트가 모두 개방되어야 합니다.
설치 순서 준수: Web Server Agent를 먼저 설치하고 구동한 후, Web Module(Nginx/Apache)을 설치해야 합니다.
Unique ID 설정 권장: unique id를 설정하지 않으면 Nginx/Apache 재구동할 때마다 앱이 개별 등록되므로, 설치 시 unique id를 고정하는 것을 권장합니다.
Nginx 버전 호환성: 지원되는 Nginx 버전(1.14.1, 1.14.2, 1.18.0, 1.20.1, 1.24.0, 1.27.0, 1.28.0)만 모니터링 가능합니다.
SELinux 에러 발생 시: Nginx 실행 시 모듈 호환성 에러가 발생하면 setenforce 0 명령으로 조치합니다.
Nginx Master/Worker 권한: Nginx Master가 root로, Worker가 nginx로 실행되는 환경에서는 nginx 모듈을 root로 설치하여 실행해야 합니다.
EXEMBID 일치 필수: CPU/Memory 지표 연계를 위해 Web Module과 host-agent의 EXEMBID가 반드시 동일해야 합니다.
패키지 파일 준비: 설치 파일은 제품기술팀에 문의하여 준비합니다.

Web Server Agent 설치

exemONE Web Server Agent 설치 방법 및 설정 상세 가이드

1. 모듈 설명​

2. 지원 버전​

3. 통신 포트​

4. 전체 설치 흐름​

5. [Phase 1] exemONE 웹 UI에서 Agent 등록​

단계 1. exemONE 설정 페이지 접속​

단계 2. [관리 > 에이전트] 메뉴 이동​

단계 3. 웹서버 에이전트 등록​

6. [Phase 2] Web Server Agent 설치​

6-1. Binary 설치​

사전 설정​

단계 1. 설치 파일 준비​

단계 2. 실행 권한 부여​

단계 3. 설치 파일 실행​

단계 4. 설치 안내 및 JAVA 확인​

단계 5. Agent 정보 입력​

단계 6. 설치 디렉토리 입력​

단계 7. 실행​

단계 8. 설치 완료 확인​

6-2. Docker 설치​

사전 설정​

단계 1. 설치 파일 압축 해제​

단계 2. 도커 이미지 로드​

단계 3. Docker 설치 관련 환경 변수 설정​

단계 4. Webserver Agent 실행 관련 환경 변수 설정​

단계 5. 포트 설정​

단계 6. 설치 및 실행 권한 부여​

단계 7. Web Agent 구동​

7. [Phase 3] Web Module 설치 (Nginx / Apache)​

7-1. Nginx Module 설치​

사전 설정​

단계 1. Nginx Module 설치 실행​

단계 2. exem_ngx_mod.conf 파일 수정​

Nginx Module 설정 옵션 상세​

단계 3. nginx.conf 파일 수정​

Nginx 모듈 호환성 에러 발생 시 조치​

7-2. Apache Module 설치​

사전 설정​

단계 1. Apache Module 설치 실행​

단계 2. exem_httpd_mod.conf 파일 수정​

Apache Module 설정 옵션 상세​

단계 3. Apache 설정 파일 수정 및 재기동​

8. CPU / Memory 지표 모니터링 설정 (선택)​

단계 1. Web Module의 EXEMBID 설정​

단계 2. Host Agent의 EXEMBID 동일 설정​

확인 방법​

9. 주의사항​

1. 모듈 설명

2. 지원 버전

3. 통신 포트

4. 전체 설치 흐름

5. [Phase 1] exemONE 웹 UI에서 Agent 등록

단계 1. exemONE 설정 페이지 접속

단계 2. [관리 > 에이전트] 메뉴 이동

단계 3. 웹서버 에이전트 등록

6. [Phase 2] Web Server Agent 설치

6-1. Binary 설치

사전 설정

단계 1. 설치 파일 준비

단계 2. 실행 권한 부여

단계 3. 설치 파일 실행

단계 4. 설치 안내 및 JAVA 확인

단계 5. Agent 정보 입력

단계 6. 설치 디렉토리 입력

단계 7. 실행

단계 8. 설치 완료 확인

6-2. Docker 설치

사전 설정

단계 1. 설치 파일 압축 해제

단계 2. 도커 이미지 로드

단계 3. Docker 설치 관련 환경 변수 설정

단계 4. Webserver Agent 실행 관련 환경 변수 설정

단계 5. 포트 설정

단계 6. 설치 및 실행 권한 부여

단계 7. Web Agent 구동

7. [Phase 3] Web Module 설치 (Nginx / Apache)

7-1. Nginx Module 설치

사전 설정

단계 1. Nginx Module 설치 실행

단계 2. exem_ngx_mod.conf 파일 수정

Nginx Module 설정 옵션 상세

단계 3. nginx.conf 파일 수정

Nginx 모듈 호환성 에러 발생 시 조치

7-2. Apache Module 설치

사전 설정

단계 1. Apache Module 설치 실행

단계 2. exem_httpd_mod.conf 파일 수정

Apache Module 설정 옵션 상세

단계 3. Apache 설정 파일 수정 및 재기동

8. CPU / Memory 지표 모니터링 설정 (선택)

단계 1. Web Module의 EXEMBID 설정

단계 2. Host Agent의 EXEMBID 동일 설정

확인 방법

9. 주의사항