DB Agent 설치

1. 모듈 설명​

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

DB Agent는 두 가지 형태로 존재합니다.

• Default DB Agent (수집서버 내장): 엑셈원 패키지에 포함되어 수집 서버에서 대상 DB로 직접 접속하여 데이터를 수집합니다.
• 개별 DB Agent: 대상 DB 서버에 직접 설치하여 해당 DB의 데이터를 수집한 후 Receiver로 전송합니다. 보안상 수집 서버와 직접 연결이 불가능하거나, OS 정보, Slow Query 등 추가 데이터 수집이 필요한 경우 개별 DB Agent를 사용합니다.

2. 지원 환경​

3. 통신 포트​

4. 설치 절차​

개별 DB Agent를 설치하는 방법은 다음과 같습니다. 수집 서버 내장 DB Agent는 별도 에이전트 등록 없이 대상 연결이 가능합니다.

4-1. 엑셈원 웹 UI에서 Agent 등록​

1. 프로필 > 환경설정 > 관리 > 에이전트 메뉴로 이동합니다.

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

3. 에이전트 타입에서 데이터베이스를 선택합니다.

4. 에이전트 생성 화면에서 Agent ID 및 Access Token을 확인합니다. Access Token은 Regenerate 선택 후 확인하며, 확인 후 반드시 [저장]을 클릭합니다. 에이전트 이름을 직접 입력합니다.

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

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

4-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. 에이전트가 실행되면 logs 폴더가 생성됩니다. logs/agent.log 파일을 확인하여 에러 발생 여부를 확인합니다. 정상적으로 연결된 경우 다음과 같은 로그가 발생합니다.

방법 2. bin 파일로 설치

5. bin 파일에 실행 권한을 부여합니다.

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

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

7. exemone-db-agent/conf/agent.yaml 파일을 수정하여 Agent ID, Access Token, Receiver 정보를 입력합니다.

8. 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. 에이전트가 실행되면 logs 폴더가 생성됩니다. logs/agent.log 파일을 확인하여 에러 발생 여부를 확인합니다. 정상적으로 연결된 경우 다음과 같은 로그가 발생합니다.

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

agent.yaml 파일은 {DB_AGENT_HOME}/conf/agent.yaml 경로에 위치하며, 주요 설정 항목은 다음과 같습니다.

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

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 이상 버전부터 systemd 서비스 등록이 지원됩니다.

1. db-agent 설치 후 conf/agent.yaml 파일에 name: agent 항목을 추가합니다.

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

2. 서비스 파일을 복사하고 적용합니다.

   # 서비스 파일 복사
   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. 참고 사항​

9-1. Oracle 접속 에러 발생 시​

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

9-2. 비밀번호 암호화/복호화​

보안 정책에 따라 모니터링 대상 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와 대상 DB 간 DB Listener Port가 개방되어야 합니다.
4. Access Token 저장 필수: Agent 생성 후 Regenerate로 토큰 확인 시 반드시 [저장]을 클릭해야 합니다. 저장하지 않으면 토큰이 적용되지 않습니다.
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. 패키지 파일 준비: 설치 파일은 제품기술팀에 문의하여 준비합니다.