본문으로 건너뛰기

DB Agent 설치

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

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

참고 문서:

1. 모듈 설명​

exemONE DB Agent(exemone-db-agent)는 데이터베이스의 성능 지표(세션, SQL, Wait Event, Tablespace, Parameter 등)를 수집하여 exemONE 수집 서버(Receiver)로 전송하는 모니터링 에이전트입니다.

DB Agent는 2가지 형태로 존재합니다:

  • Default DB Agent (수집서버 내장): exemONE 패키지에 포함되어 수집서버에서 Target DB로 직접 접속하여 데이터 수집
  • 개별 DB Agent: Target DB 서버에 직접 설치하여 해당 DB의 데이터를 수집 후 Receiver로 전송

2. 통신 포트​

exem-db-agent는 Unix를 지원하지 않습니다.

구분출발지도착지TypePort내용
Default DB Agent (수집서버 내장)exemONE 수집 서버Target DBTCPDB Listener PortDB 지표 수집
개별 DB Agent모니터링 대상 장비exemONE 수집 서버 (Receiver)gRPC9009범용 gRPC 요청 및 응답

3. 지원 데이터베이스​

3-1. On-Premise DB 지원 버전​

DB지원 버전
Oracle12c 이상
PostgreSQL9.6 이상
MySQL5.7 이상
MariaDB10 이상
SQL Server2012 이상
MongoDB3.0.0 이상
Tibero5 이상
Redis3.0.0 이상
Cubrid9.2.1 이상
Altibase6.1 이상
ClickHouse24.8.6.70
SingleStore8.9 이상

3-2. Cloud DB 지원​

✅ : cloud 환경, MFC 환경 지원 / ❌ : 지원하지 않음 / ⚠️ : cloud 환경 지원하나 exemONE에서 미지원

환경PostgreSQLOracleMySQLMariaDBSQL Server
AWS✅✅✅✅✅
Azure✅❌✅✅✅
OCI⚠️✅⚠️❌❌
NCP✅❌✅❌✅
GCP✅❌✅❌✅
SCP✅❌✅✅✅

4. DB Agent 지원 OS​

환경지원 OS
LinuxCentOS 7 이상
Windows윈도우 10 이상

5. 설치 절차 (단계별)​

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

단계 1. Agent 추가​

  • 프로필 > 환경설정 > 관리 > 에이전트 메뉴로 이동
  • 상단의 [에이전트 추가] 버튼 클릭

  • 에이전트 타입에서 데이터베이스를 선택
  • [갱신] 버튼을 클릭하면 에이전트 ID와 엑세스 토큰이 발급됩니다
  • 에이전트 이름을 직접 입력합니다

또는 Setting > Database > Agent Management 탭에서도 가능합니다:

단계 2. Agent ID 및 Access Token 확인​

Agent 생성 후 편집 버튼을 선택하여 Agent ID 및 Access Token을 확인합니다.

  • Access Token의 경우 Regenerate 선택 후 토큰 확인
  • 토큰 확인 후 Save 필수

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

단계 3. Instance 등록​

  • Instance 탭에서 Add Group 선택하여 그룹 추가
  • Add Instance 선택하여 인스턴스 추가
  • Agent 항목에는 단계 1에서 추가한 Agent를 등록합니다

[Phase 2] DB 서버에 exemone-db-agent 설치​

Linux 환경 설치​

방법 1. tar 파일로 설치​

단계 1. exemone 계정 생성 후 exemone-db-agent 압축 해제

단계 2. conf/agent.yaml 파일 내 Agent ID, Access Token, Receiver 정보 추가

  • 값 입력 시 agent_id: → : 뒤에 꼭 한 칸이 띄워져 있어야 합니다.

단계 3. ./startup.sh 스크립트 실행하여 exemone-db-agent 실행

단계 4. agent가 실행되면 logs 폴더가 생성되며, logs/agent.log를 확인하여 에러 발생 여부 확인

  • 정상적으로 연결된 경우 아래와 같이 로그 발생:

방법 2. bin 파일로 설치​

단계 1. bin 파일 실행 권한 부여

chmod +x setup_exemone-db-agent_v3.0.412.9.0.bin

단계 2. bin 파일 실행

./setup_exemone-db-agent_v3.0.412.9.0.bin
=====================================================
exemone-db-agent Install
=====================================================

new install start
Would you like to do a new install? (y/n)
y
xmSuccess(0): Installation is complete.

단계 3. exemone-db-agent/conf/agent.yaml 파일 수정 (Agent ID, Access Token, Receiver 정보 입력)

단계 4. exemone-db-agent/start.sh 실행

./start.sh
xmSuccess(0): exemONE DB agent start success

Windows 환경 설치​

단계 1. setup_exemone-db-agent_{version}.exe 파일 실행

  • 서비스 등록하여 사용을 원하면 체크하여 설치

단계 2. {exemone-db-agent-home}\conf\agent.yaml 파일 내 Agent ID, Access Token, Receiver 정보 추가

  • 값 입력 시 agent_id: → : 뒤에 꼭 한 칸이 띄워져 있어야 합니다.

단계 3. start.bat 실행하여 exemone-db-agent 실행

단계 4. agent가 실행되면 logs 폴더가 생성되며, logs/agent.log를 확인하여 에러 발생 여부 확인

  • 정상적으로 연결된 경우 아래와 같이 로그 발생:

6. 설정 파일 상세 (agent.yaml)​

6-1. agent.yaml 파일 위치​

{DB_AGENT_HOME}/conf/agent.yaml

6-2. agent.yaml 설정 항목​

global:
  agent_id: //please enter        # exemONE에서 발급받은 Agent ID
  access_token: //please enter    # exemONE에서 발급받은 Access Token
  receiver: //please enter        # 수집 서버 주소 (IP:9009)
  installed_path: //please enter  # db-agent 설치 경로
  run_path: //please enter        # db-agent 실행 경로
log:
  caller: false                   # 로그 호출자 포함 여부
  level: info                     # 로그 레벨
  file: /home/exem/exemone-db-agent/logs/agent.log  # 로그 경로
  name: agent                     # systemd 등록 시 추가 필요
  max-backups: 1                  # 보관할 로그 파일 수 (v3.0.504.15.44+)
  max-size: 1                     # 로그 파일 max 사이즈 (MB, v3.0.504.15.44+)
  max-age: 3                      # 로그 파일 보관 일수 (v3.0.504.15.44+)

6-3. 주요 설정 항목 상세​

설정 항목설명비고
global.agent_idexemONE 웹에서 발급받은 Agent ID필수. : 뒤에 공백 필수
global.access_tokenexemONE 웹에서 발급받은 Access Token필수. Save 후 확인
global.receiver수집 서버 Receiver 주소 (IP:9009)필수
global.installed_pathdb-agent 설치 경로필수
global.run_pathdb-agent 실행 경로필수
log.caller로그 호출자(함수명, 라인번호) 포함 여부기본값: false
log.level로그 레벨 설정info, warn, error, panic, debug, trace
log.file로그 파일 경로경로 변경 시 에이전트 재기동 필요
log.max-backups보관할 로그 파일 수v3.0.504.15.44 이후 지원
log.max-size로그 파일 최대 크기 (MB 단위)v3.0.504.15.44 이후 지원. 1024로 계산
log.max-age로그 파일 보관 일수v3.0.504.15.44 이후 지원

6-4. 로그 경로 변경 방법​

  1. db-agent 중지: {DB_AGENT_HOME}/stop.sh
  2. {DB_AGENT_HOME}/conf/agent.yaml 파일 내 로그 경로 변경

  1. db-agent 시작: {DB_AGENT_HOME}/start.sh

사전 설정: 변경할 로그 경로에 에이전트 실행 계정의 권한이 설정되어 있어야 합니다.

7. Linux systemd 서비스 등록 (선택사항)​

db-agent v3.0.506.15.10 이상부터 지원

단계 1. db-agent 설치 후 conf/agent.yaml 파일 등록 정보 수정​

agent.yaml에 name: agent 항목을 추가합니다:

log:
  caller: false
  level: info
  file: /home/exemone/db_agent/exemone-db-agent/logs/agent.log
  name: agent   # ==> 추가

단계 2. service 파일 복사 및 적용​

# 서비스 파일 복사
sudo cp exemone-db-agent.service /etc/systemd/system/

# 서비스 파일 적용
sudo systemctl daemon-reload

단계 3. 서비스 실행 및 확인​

# 서비스 실행
sudo systemctl start exemone-db-agent

# 서비스 상태 확인
systemctl status exemone-db-agent

# 서비스 종료
sudo systemctl stop exemone-db-agent

8. DB별 모니터링 권한 및 사전 설정​

8-1. Oracle​

필요 권한:

GRANT CREATE SESSION TO exemone;
GRANT SELECT ANY dictionary TO exemone;
GRANT SELECT_CATALOG_ROLE TO exemone;
GRANT ALTER system TO exemone;

-- AWS RDS인 경우
grant execute on rdsadmin.rdsadmin_util to exemone;

SELECT ANY DICTIONARY 권한 부여가 어려운 경우, v$session, v$sql, v$sysstat, v$system_event 등 개별 view에 대한 SELECT 권한을 부여해야 합니다. 상세 목록은 Oracle 권한을 참고하세요.

8-2. PostgreSQL​

사전 설정 (DB 재기동 필요):

track_functions = 'pl'
shared_preload_libraries = 'pg_stat_statements'

SQL 실행 정보 수집 설정:

\c [모니터링 대상 dbname]
create extension pg_stat_statements;

-- SQL text 길이 제한 옵션 (선택, 기본값: 1024, 권장: 1048576)
-- PostgreSQL 재기동 필요
track_activity_query_size

필요 권한:

-- PostgreSQL 10 이상 (superuser 권한이 어려운 경우)
grant pg_monitor to exemone;

-- PostgreSQL 10 미만
alter user exemone with superuser;

-- SQL 데이터 수집
GRANT USAGE ON SCHEMA {schema 명} TO exemone;
GRANT connect ON database {database 명} TO exemone;

-- Plan 조회
GRANT USAGE ON SCHEMA {schema 명} TO exemone;
GRANT select ON {schema 명}.{table 명} TO exemone;

SSL 설정 (선택):

Setting > Database > Custom Configuration에서 SSL mode 설정 가능:

  • require: SSL 암호화 사용, CA 확인 안 함 (인증서 파일 불필요)
  • verify-ca: require + CA 발급 확인 (서버 공개키 파일 필요)
  • verify-full: verify-ca + 호스트 이름 확인 (서버 공개키 파일 필요)

8-3. MySQL / MariaDB​

사전 설정 (DB 재기동 필요):

performance_schema = ON
max_digest_length = 4096
performance_schema_max_digest_length = 4096
performance_schema_max_sql_text_length = 4096

Slow Query 수집 설정:

set global slow_query_log = on
set global slow_query_log_file = {slow query 로그 파일 경로}
set global long_query_time = {초}

필요 권한:

grant process on *.* to exemone;
grant select on performance_schema.* to exemone@'{db-agent 설치 서버 IP}';
grant show databases on *.* to exemone@'{db-agent 설치 서버 IP}';
grant select on dbname.* to exemone@'{db-agent 설치 서버 IP}';
grant replication client on *.* to exemone@'{db-agent 설치 서버 IP}';
grant replication slave on *.* to exemone@'{db-agent 설치 서버 IP}';
grant super on *.* to exemone@'{db-agent 설치 서버 IP}';
grant select on information_schema.processlist to exemone@'{db-agent 설치 서버 IP}';

추가 권한 (버전별 Replication, Session Kill 등)은 MySQL/MariaDB 권한을 참고하세요.

8-4. SQL Server​

필요 권한 (sysadmin 또는 아래 권한 설정):

-- SQL Server 2022 이상 / Azure
alter server role ##MS_serverStateReader## ADD MEMBER exemone;
GRANT VIEW DEFINITION TO exemone;

-- SQL Server 2012~2019
grant view server state to exemone;

-- 각 DB
grant execute on dbo.fn_cdc_hexstrtobin to exemone;
grant view definition to exemone;

모니터링 방식 (sqlserver.mode):

  • procedure (기본값): maxgauge DB 자동 생성을 위해 create any database 권한 필요
  • query (Azure 환경): create database 권한 불필요

8-5. MongoDB​

기본 모니터링 권한: clusterAdmin 권한

8-6. Tibero​

CREATE SESSION   -- DB 접속 권한
SELECT ANY DICTIONARY   -- 딕셔너리 테이블(v$, DBA) 접근 권한

-- Session Kill 권한
ALTER SYSTEM

8-7. Redis​

-- info, ping, cluster, client 네 가지 권한 필요
-- slowlog 설정된 경우 slowlog 권한 추가 필요
-- Redis 6.0 미만은 user가 없어 ip, port, pw만으로 모니터링 가능
ACL SETUSER user on >password +INFO +PING +CLUSTER +CLIENT +SLOWLOG

8-8. Altibase​

CREATE SESSION: DB 접속 권한
SELECT ANY TABLE: 모든 테이블(SYSTEM_, V$)에 대한 select 권한
지원 버전: 6.3 이상

KILL SESSION 사용 시 모니터링 계정을 'SYS'로 등록 필요

8-9. ClickHouse​

-- SELECT, KILL QUERY 권한
grant select on system.events to monitor_user;
grant select on system.merges to monitor_user;
grant select on system.metrics to monitor_user;
grant select on system.mutations to monitor_user;
grant select on system.parts to monitor_user;
grant select on system.part_log to monitor_user;
grant select on system.processes to monitor_user;
grant select on system.query_log to monitor_user;
grant select on system.replicas to monitor_user;
grant select on system.clusters to monitor_user;
grant select on system.text_log to monitor_user;
grant select on system.disks to monitor_user;
grant select on system.distribution_queue to monitor_user;

8-10. SingleStore​

GRANT USAGE, SHOW METADATA, PROCESS, CLUSTER, SHOW ROUTINE ON *.* TO exemone;

8-11. Cubrid​

  • CMS 계정에 모니터링 권한 필요 (restful api 호출 방식으로 브로커, DB 데이터 수집)
  • DB 인스턴스 등록 시 CMS 정보 + DB 정보 모두 입력 필요

9. Custom Configuration 공통 옵션​

Setting > Database > 인스턴스 추가/편집 시 커스텀 설정 항목에서 공통(common) 옵션을 설정할 수 있습니다.

옵션설명기본값
common._use_query커스텀 옵션 사용 여부 (true: 커스텀 옵션으로 수집, false: DB 매트릭 수집 설정으로 수집)-
common.cloud_metric_from_minuteCloud 환경 metric 수집 범위 from 시간 (분)-5
common.cloud_metric_to_minuteCloud 환경 metric 수집 범위 to 시간 (분)0
common.max_idle_connections인스턴스별 대기 세션 최대 연결 수4
common.max_open_connections인스턴스별 사용 중 세션 최대 연결 수4
common.max_msg_rows메시지 버퍼 사이즈 (연구소 확인 후 설정)1000
common.once_collect_at_startingAgent 시작 시 데이터 즉시 수집 여부-
common.~use_disk_metric호스트 마운트 메트릭 수집 여부 (api v3.0.508.154+, db-agent v3.0.508.67+)false

10. 수집 쿼리 수정 방법​

Default Agent (수집 서버 내장) 수집 쿼리 수정​

1. query export 수행:

# 도커 패키지
$EXEMONE_HOME/containers/exemone-db-agent/scripts 경로에서:
./export.sh [DB 타입]

# 바이너리 패키지
./[설치된 db-agent 파일] export --type [DB 타입] --path ${QUERY_PATH}/queries

2. query 수정 및 적용:

  • queries 폴더 내 db-agent 버전명으로 폴더 생성
    • 도커 패키지: $EXEMONE_HOME/containers/exemone-db-agent/queries/
    • 바이너리 패키지: $EXEMONE_HOME/services/exemone-db-agent/queries/
  • 생성된 폴더 내 수정할 sql 파일을 복사 후 수정 (원본 파일명과 동일하게 저장)

3. db-agent 재기동:

# 도커 패키지
./scripts/restart.sh db-agent

# 바이너리 패키지
./onectl restart db-agent

개별 DB Agent 수집 쿼리 수정​

# export 명령 수행
./[설치된 db-agent 파일] export --type [DB 타입] --path ${QUERY_PATH}/queries

# 예시
./exemone-db-agent-v3.0.504.15.46 export --type mysql --path /home/exemone/agent/exemone-db-agent/queries

이후 과정은 Default Agent와 동일합니다. 재기동은 ./stop.sh + ./start.sh로 진행합니다.

참고: db-agent에서 수행하는 쿼리를 exemONE에서 모니터링할 경우, dbtype.own_query_filter 값을 false로 설정합니다 (true: 제외, false: 포함).

11. 수동 패치 방법​

  1. db-agent 중지:
{DB_AGENT_HOME}/stop.sh
  1. 별도 디렉토리 생성 및 bin 파일 수행:
mkdir ins
chmod +x setup_exemone-db-agent_{version}.bin
./setup_exemone-db-agent_{version}.bin
  1. 생성된 실행 파일을 기존 경로에 복사:
cp -R exemone-db-agent/exemone-db-agent-{version} {DB_AGENT_HOME}

  1. .env 파일에서 버전 정보 수정 (DB_AGENT_VERSION)

  2. db-agent 시작:

{DB_AGENT_HOME}/start.sh

웹 UI를 통한 패치 (host-agent, db-agent, ndm-agent 가능)​

  1. 환경설정 > 에이전트 > 에이전트 패치 탭에서 [파일 추가] 버튼 선택
  2. 패치할 에이전트 파일 업로드

  1. 업로드한 파일을 체크 선택하면 패치 가능한 에이전트 목록 표시

  1. [패치 실행] 버튼 클릭하여 패치 진행
  2. 에이전트 패치 이력 탭에서 패치 실행 내역 확인 가능

12. 지표 수집 주기 관리​

각 데이터베이스마다 지표별 수집 활성화 및 수집 주기를 설정할 수 있습니다.

방법 1. 환경설정을 통한 설정​

Setting > Data > Metric Collection Cycle Management > Categories에서 Database 선택

  • Interval 설정 가능 값: 1초, 3초, 5초, 10초, 15초, 20초, 30초, 1분, 10분, 1시간, 1일

방법 2. 인스턴스 설정을 통한 설정​

Setting > Database > Target Instance Add/Edit > Database Metric Collection Setting

  • Custom Configuration에서 common._use_query 값을 false로 변경 후 Database Metric Collection Setting에서 설정

13. 관리 스크립트​

스크립트설명
./startup.sh 또는 ./start.shdb-agent 시작
./stop.shdb-agent 종료
start.bat (Windows)db-agent 시작 (Windows 환경)

14. 에러 발생 시 참고 사항​

Oracle 접속 에러​

Oracle DB의 경우 아래와 같은 에러가 발생하면, db-agent 설치 경로 내 .env 파일에 Oracle 접속을 위한 환경변수 값을 추가합니다.

비밀번호 암호화/복호화​

보안 정책에 따라 모니터링 대상 DB 비밀번호를 암호화된 형태로 관리할 수 있습니다.

암호화:

{EXEMONE_HOME}/scripts/crypto-cli encrypt --plaintext {평문}

복호화:

{EXEMONE_HOME}/scripts/crypto-cli decrypt --ciphertext {암호화 텍스트}

15. 주의사항​

  1. agent_id 설정 시 YAML 문법 주의: agent_id: → : 뒤에 반드시 한 칸 공백이 있어야 합니다.
  2. Unix 미지원: exem-db-agent는 AIX, HP-UX, SunOS 등 Unix 환경을 지원하지 않습니다. Linux 및 Windows만 지원합니다.
  3. 방화벽 포트 개방: 개별 DB Agent → Receiver 간 gRPC 9009 포트, Default DB Agent → Target DB 간 DB Listener Port가 개방되어야 합니다.
  4. Access Token 저장 필수: Agent 생성 후 Regenerate로 토큰 확인 시 반드시 Save를 클릭해야 합니다. Save하지 않으면 토큰이 적용되지 않습니다.
  5. Oracle 환경변수: Oracle DB 접속 에러 시 .env 파일에 Oracle 환경변수(LD_LIBRARY_PATH, ORACLE_HOME 등)를 추가해야 합니다.
  6. systemd 등록: db-agent v3.0.506.15.10 이상에서만 systemd 서비스 등록이 지원됩니다.
  7. 로그 설정: max-backups, max-size, max-age 옵션은 db-agent v3.0.504.15.44 이후 버전부터 지원됩니다.
  8. 수집 쿼리 수정 후 반드시 재기동: 수정된 쿼리를 적용하려면 db-agent를 재기동해야 합니다.
  9. 패키지 파일 준비: 설치 파일은 제품기술팀에 문의하여 준비합니다.