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로 전송

고객사 환경에 따라 개별 DB Agent를 타겟 서버에 설치하여 exemONE 에이전트에 등록 후 데이터를 수집합니다.

ex) 보안상 수집서버(Default Agent)와 직접 연결이 불가능한 경우, 추가 데이터(OS 정보, Slow Query 등) 수집이 필요한 경우 등​

2. 지원 환경​

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

DB	지원 버전
Oracle	12c 이상
PostgreSQL	9.6 이상
MySQL	5.7 이상
MariaDB	10 이상
SQL Server	2012 이상
MongoDB	3.0.0 이상
Tibero	5 이상
Redis	3.0.0 이상
Cubrid	9.2.1 이상
Altibase	6.1 이상
ClickHouse	24.8.6.70
SingleStore	8.9 이상

2-2. Cloud DB 지원​

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

2-3. 지원 OS​

3. 통신 포트​

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

수집서버 db agent (Default agent)의 경우 별도 Agent 등록없이 타겟 연결이 가능합니다.

[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를 확인하여 에러 발생 여부 확인

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

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

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

{DB_AGENT_HOME}/conf/agent.yaml

5-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+)

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

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

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

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

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

6. 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

7. 수동 패치 방법​

1. db-agent 중지:

{DB_AGENT_HOME}/stop.sh

2. 별도 디렉토리 생성 및 bin 파일 수행:

mkdir ins
chmod +x setup_exemone-db-agent_{version}.bin
./setup_exemone-db-agent_{version}.bin

3. 생성된 실행 파일을 기존 경로에 복사:

cp -R exemone-db-agent/exemone-db-agent-{version} {DB_AGENT_HOME}

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

5. db-agent 시작:

{DB_AGENT_HOME}/start.sh

8. 관리 스크립트​

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

Oracle 접속 에러​

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

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

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

암호화:

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

복호화:

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

10. 주의사항​

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

참고 문서:

• DB Agent 설치 가이드
• DB Agent 지원 환경
• DB Agent 필요 Port
• DB Agent Linux 환경 설치
• DB Agent Windows 환경 설치
• DB Agent 옵션
• DB Agent 수동 패치 가이드
• DB Agent 로그 경로 변경 방법
• DB Agent Linux 서비스 등록 가이드
• DB Agent systemd 등록 방법
• Agent 등록 가이드
• DB Agent 수집 쿼리 수정 가이드
• 에이전트 목록 및 관리
• 모듈별 사용 Port
• 비밀번호 암호화/복호화 방법
• 지표 수집 주기 관리 설정 가이드