본문으로 건너뛰기

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 추가​

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

  • 에이전트 타입에서 데이터베이스를 선택

단계 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. 수집 쿼리 수정 방법​

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: 포함).

9. 수동 패치 방법​

  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. 에이전트 패치 이력 탭에서 패치 실행 내역 확인 가능

10. 관리 스크립트​

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

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

Oracle 접속 에러​

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

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

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

암호화:

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

복호화:

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

12. 주의사항​

  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. 패키지 파일 준비: 설치 파일은 제품기술팀에 문의하여 준비합니다.

참고 문서: