에이전트 설치

와탭 데이터베이스 모니터링 서비스 이용을 위한 기본 설치 방법을 안내합니다.

와탭 데이터베이스 에이전트 다운로드

에이전트 파일을 다운로드하세요. 다음 두 가지 방법을 이용하세요.
- 와탭 모니터링 서비스 화면에서 Download 버튼을 선택해 다운로드할 수 있습니다.
- 리눅스 wget 방식으로 다운로드를 할 수 있습니다. 다음 명령어를 이용하세요.
```
wget -O whatap.agent.database.tar.gz "https://service.whatap.io/download/dbx_agent?type=mongodb&format=tar.gz"
```
노트
보안 설정으로 인해 tar 형식의 파일을 다운로드할 수 없는 사용자를 위해 ZIP 형식의 파일도 함께 제공합니다. 설치 화면에서 .zip 다운로드 버튼을 선택하세요.

다운로드한 파일을 분석할 서버에 복사한 다음 압축을 해제하세요.(윈도우, 리눅스 동일)

에이전트 구성 파일

파일명	설명
whatap.conf	데이터베이스 서버의 데이터를 수집하는 수집 서버의 주소와 서버의 프로젝트 액세스 키를 입력하는 파일입니다. 에이전트 설정에 관한 자세한 내용은 다음 문서를 참조하세요.
alert/alert.conf	수집하는 모니터링 항목에 임계치를 설정하는 파일입니다. 임계치를 초과하는 경우 알림 이벤트가 발생합니다.
scripts/	원격으로 sql 스크립트를 실행할 수 있는 스크립트들을 모아둔 디렉터리입니다.
ps.sh	프로세스 아이디를 읽어 오는 스크립트입니다. 에이전트 프로세스를 종료할 때 해당 아이디를 참고합니다.
stop.sh	에이전트 프로세스를 종료할 때 사용하는 스크립트입니다.
uid.sh (uid.bat)	데이터베이스 접속 정보를 조합하여 암호화된 UID를 생성하기 위한 쉘 스크립트 파일입니다. db.user 파일을 생성합니다. 최초 한 번만 설정해두면 암호화된 UID를 통해 모니터링 대상 데이터베이스 서버로부터 데이터 수집을 진행합니다. 모니터링용 계정 생성에 관한 자세한 내용은 다음 문서를 참조하세요.
start.sh (start.bat)	에이전트 실행을 위한 쉘 스크립트 파일입니다. 에이전트를 실행하면 데이터베이스 서버의 모니터링 정보를 수집하기 시작합니다.
startd.sh (startd.bat)	에이전트 실행을 위한 쉘 스크립트 파일로 백그라운드로 실행할 수 있습니다.
whatap.agent.dbx-`X.Y.Z`.jar	Tracer 프로그램, 데이터베이스 서버의 정보를 수집하고, 수집한 정보를 서버로 전송하는 프로그램입니다.
jdbc	데이터베이스 서버 연결을 위해 참조하는 라이브러리들을 모아두는 디렉터리입니다. 에이전트와 데이터베이스 서버의 연결을 위한 라이브러리를 직접 다운로드해 java의 classpath 옵션에 경로를 설정하여 사용합니다.
xos/	데이터베이스 서버의 프로세스 사용량을 모니터링할 수 있는 부가 옵션 에이전트가 포함된 디렉터리입니다.
⎿ xos.conf	데이터베이스 서버의 프로세스 사용량 데이터를 수집 및 데이터 전송을 위한 에이전트 서버의 주소와 통신 포트를 입력하는 파일입니다.
^* xcub/	CUBRID 데이터베이스의 SQL 텍스트 수집과 지표 계산을 수행하는 부가 에이전트 파일이 들어있는 디렉터리입니다.
⎿ ^* xcub.conf	CUBRID 데이터베이스 및 부가 에이전트 연결 정보를 입력하는 파일입니다.

노트

^*: xcub 경로의 파일은 CUBRID 모니터링을 위한 전용 파일입니다.

압축을 해제한 폴더로 진입해서 whatap.conf 파일을 확인하세요. whatap.conf 파일에 프로젝트 액세스 키 정보 및 와탭 서버 정보, db 접속 정보를 입력하세요.
whatap.conf
```
license={Access_Key}
whatap.server.host=13.124.11.223/13.209.172.35 # WhaTap server information

dbms=mongodb
db={Database_name} # sid
db_ip={DB_server_IP_address}
db_port={DB_server_port}
```
다음 디렉터리에 JDBC 드라이버를 다운로드하세요. /압축해제한 폴더/jdbc

데이터베이스 서버의 운영체제와 버전에 맞는 JDBC 드라이버를 다운로드하세요.

MongoDB JDBC Drivers: https://github.com/mongodb/mongo-jdbc-driver

노트

DB 구성에 따라 whatap.conf 파일에 추가 설정이 필요할 수 있습니다. 자세한 내용은 다음 문서를 참조하세요.
DB 서버의 자원을 추가로 모니터링하려면 XOS 에이전트를 이용해야 합니다. 자세한 내용은 다음 문서를 참조하세요.

/압축해제한 폴더/jdbc/README.md 파일에서 각 데이터베이스별 JDBC 드라이버 설치 경로를 확인할 수도 있습니다.

계정 생성

데이터베이스 모니터링을 하기 위해 필요한 권한을 가진 계정을 생성하세요. root(admin) 계정으로 로그인해 계정을 생성하세요.

노트

이미 있는 계정을 사용하고 싶다면 DB 유저 파일 생성으로 넘어가세요. 권한이 없을 경우 모니터링을 시작할 수 없습니다.
예시 코드에서 whatap은 DB 사용자 계정 이름입니다. 사용자가 이용하는 사용자 계정 이름으로 변경하세요.

예시 코드의 DB_Password에는 사용자 비밀번호를 입력하세요.

db.createUser(
  {
    user: "whatap",
    pwd: "DB_Password",
    roles: [
        { "role" : "clusterMonitor", "db" : "admin" },
   ]
  }
)

IAM 인증으로 접속하기

정보

신규 절입니다. DB 비밀번호 대신 AWS IAM 인증 토큰으로 접속하는 방법을 안내합니다. 기능은 DBX 에이전트 v2.63 대에 들어갔는데 독스에는 aws_iam_auth 옵션 설명만 있고, 계정을 만드는 단계에서는 비밀번호 없이도 된다는 안내가 없었습니다. 내용은 DB 팀 노션 문서와 강희정 님이 정리해 주신 내용을 바탕으로 작성했습니다.

확인 요청 3건

MariaDB는 독스에 제품 디렉터리가 없어 MySQL 문서에 함께 안내했습니다. MariaDB 사용자가 MySQL 문서를 참조하는 구조가 맞는지 확인 부탁합니다.
RDS·Aurora에서 Oracle·SQL Server·DB2는 미지원이라고 명시했습니다. 맞는지 확인 부탁합니다.
Role 설정 절의 AWS 공식 문서 링크는 제가 찾아 넣었습니다. 의도하신 링크와 다르면 알려주세요.

Amazon DocumentDB 5.0 이상 환경에서는 DB 비밀번호 대신 AWS IAM 인증 토큰으로 접속할 수 있습니다. MongoDB 드라이버 4.1 이상이 필요합니다. 에이전트의 jdbc 폴더에서 드라이버 버전을 확인하세요.

비밀번호 방식을 사용한다면 이 단계를 건너뛰세요.

1단계. 접속 계정 준비하기

mongosh로 admin(마스터) 계정에 접속한 다음, 접속에 사용할 Role ARN을 $external 데이터베이스의 사용자로 등록하세요.

mongosh
db.getSiblingDB("$external").createUser({
  user: "arn:aws:iam::{ACCOUNT}:role/{ROLE}",
  roles: [
    { role: "readAnyDatabase", db: "admin" },
    { role: "clusterMonitor",  db: "admin" }
  ]
})

여기서 등록하는 Role은 4단계. Role 설정하기에서 만드는 Role입니다.

2단계. whatap.conf 설정하기

whatap.conf 파일에 다음 옵션을 추가하세요.

whatap.conf
aws_iam_auth=true
aws_region=ap-northeast-2
db_ssl=true

db_user는 설정하지 않습니다. Role ARN으로 인증합니다.

AssumeRole 방식을 사용한다면 aws_arn 옵션을 추가하세요. EC2 Role 방식은 옵션을 추가하지 않습니다.

whatap.conf
aws_arn=arn:aws:iam::{ACCOUNT}:role/{ROLE}

3단계. AWS 사전 설정하기

IAM 정책은 필요하지 않습니다. 4단계. Role 설정하기로 넘어가세요.

4단계. Role 설정하기

앞에서 만든 정책을 Role에 부착하고 에이전트에 연결합니다. 운영 환경에서는 EC2 Role 방식을 권장합니다. 액세스 키를 저장하지 않아도 됩니다.

EC2 Role
AssumeRole

신뢰할 수 있는 서비스를 EC2로 지정해 IAM Role을 만드세요.
앞에서 만든 정책을 Role에 부착하세요.

DocumentDB는 정책이 필요하지 않으므로 이 단계를 건너뜁니다.
에이전트를 실행하는 EC2 인스턴스에 Role을 연결하세요. 자세한 방법은 AWS 문서를 참조하세요.

이 Role의 ARN을 1단계의 $external 사용자로 등록하세요.

교차 계정 환경 등 위임이 필요한 경우에 사용합니다.

위임받을 Role을 만들고 앞에서 만든 정책을 부착하세요.

DocumentDB는 정책이 필요하지 않으므로 이 단계를 건너뜁니다.
에이전트가 실행되는 EC2의 Role이 sts:AssumeRole을 수행할 수 있도록 신뢰 관계를 설정하세요. 자세한 방법은 AWS 문서를 참조하세요.
whatap.conf의 aws_arn 옵션에 이 Role의 ARN을 지정하세요.

이 Role의 ARN을 1단계의 $external 사용자로 등록하세요.

DB 접속 정보 암호화(UID 생성 및 갱신)

팁

user와 password를 사용하지 않는 경우 (인증 없이 MongoDB에 접속 가능한 경우) DB 유저 파일 생성 단계를 건너뛰어도 됩니다.

데이터베이스 모니터링을 위해 2번 단계에서 생성한 DB 모니터링 계정 정보를 에이전트에 안전하게 등록해야 합니다. 와탭은 DB 접속 정보를 암호화된 UID 형태로 저장하며, 에이전트는 이 UID를 이용하여 DB에 접속합니다.

username과 password를 입력한 뒤 다음 스크립트를 실행하세요.

주의

비밀번호 변경 시 반드시 재실행

DB 모니터링 계정의 비밀번호가 변경된 경우, 반드시 본 단계를 다시 수행해야 합니다.

UID는 DB 접속 정보를 암호화한 값이므로,
비밀번호 변경 후 UID를 갱신하지 않으면 DB 접속 오류로 인해 모니터링 데이터 수집이 중단됩니다.

Linux
Windows

./uid.sh {DB_USER} {DB_PASSWORD}

uid.bat {DB_USER} {DB_PASSWORD}

정보

최초 한번만 설정하면 그 이후부터는 암호화된 UID를 통해 모니터링 대상 데이터베이스 서버로부터 데이터 수집을 진행합니다.
DB 유저 파일을 생성하기 위해서는 프로젝트 액세스 키가 whatap.conf 파일에 입력되어 있어야 합니다. 액세스 키 확인

특수문자 포함 시 처리 방법

MongoDB 환경에서 DB_USER 또는 DB_PASSWORD에 특수문자가 포함된 경우, 다음 순서로 처리해야 합니다.

1단계: 퍼센트 인코딩 적용 (필수)

MongoDB는 특수문자가 포함된 경우 퍼센트 인코딩(Percent Encoding)을 먼저 적용해야 합니다.

예시

원본 비밀번호: whatap@#
퍼센트 인코딩 적용 후: whatap%40%23

팁

퍼센트 인코딩 규칙에 대한 자세한 내용은 MongoDB Connection String URI Format 공식 문서를 참고하세요.

2단계: Escape 문자 적용 (필요 시)

퍼센트 인코딩 적용 후에도 Shell에서 해석되는 특수문자(!, \, $ 등)가 포함된 경우, Escape 문자(\)를 추가로 적용해야 합니다.

예시

# 기본 사용
./uid.sh whatap whatap%40%23

# Shell 해석 문제 발생 시
./uid.sh whatap whatap\%40\%23

중요

MongoDB는 특수문자 포함 시 퍼센트 인코딩이 우선입니다.
적용 순서: 퍼센트 인코딩 → 필요 시 Escape 문자
퍼센트 인코딩을 적용하지 않으면 UID 생성은 되어도 실제 DB 접속이 실패할 수 있습니다.

모니터링 시작하기

에이전트를 설치한 경로에서 쉘 스크립트(또는 배치 파일)를 실행하세요.

Linux
Windows

./start.sh

데몬처럼 사용하고 싶은 경우에는 다음 명령어를 실행하세요. 단 nohup을 설치한 환경에서만 동작합니다.

./startd.sh

start.bat

화면에 표시된 실행 로그에 에러가 없는지 확인하고, 대시보드 화면(인스턴스 목록)에 차트가 정상 표시되는지 확인하세요. 이상이 없다면 Ctrl+C를 눌러 실행을 종료하고, 다음 순서에 따라 윈도우 서비스에 등록하세요.

서비스 등록하기

다음 명령어를 실행해 서비스를 등록하세요.

install_WindowsService.bat create WhatapDBXAgent

서비스를 등록하면 Windows의 서비스 관리 도구에서 아래와 같이 확인할 수 있습니다. 해당 서비스를 찾아 마우스 오른쪽 버튼으로 클릭하고, 시작(Start) 옵션을 선택해 서비스를 시작하세요.

노트

제어판 > Windows 도구 > 서비스(services.msc)에서 WhatapDBXAgent 서비스를 시작하거나 중지할 수 있습니다. 사용하는 Windows 버전에 따라 서비스 경로는 다를 수 있습니다.

서비스 삭제하기

다음 명령어를 실행해 서비스를 삭제할 수 있습니다.

install_WindowsService.bat delete WhatapDBXAgent

데이터베이스 모니터링을 위한 에이전트 설치를 완료했습니다. 다음 문서에서 설치 후 점검 사항을 확인하세요.

부가 에이전트(XOS) 설치 및 기타 옵션 적용하기

데이터베이스 서버의 자원을 추가로 모니터링하려면 데이터베이스 서버에 별도의 XOS 에이전트를 실행해 데이터를 수집할 수 있습니다.

노트

x86 아키텍쳐 기반에서 동작하는 OS 환경에만 적용할 수 있습니다.
부가 에이전트 설치 과정은 필수가 아닌 선택 사항입니다.

XOS 에이전트 설정 옵션에 대한 자세한 내용은 다음 문서를 참조하세요.

whatap.conf 파일 설정하기

DBX 에이전트가 설치된 경로의 whatap.conf 파일에 다음 옵션을 설정하세요.

whatap.conf
xos=1
xos_port=3002

xos 폴더(/압축 해제 폴더/xos/)를 데이터베이스 서버로 이동하세요.

xos.conf 파일 설정하기

데이터베이스 서버로 이동한 xos 경로의 xos.conf 파일에 다음 옵션을 설정하세요.

xos.conf
dbx_ip={DB_Agent_IP}
dbx_port=3002 # default 3002
cpu_limit=0
mem_limit=10240

팁

에이전트 설치 메뉴에서 DB Agent IP, DB Agent Port 항목에 DB 정보를 입력하면 에이전트 옵션을 자동 생성할 수 있습니다.

XOS 에이전트 실행하기

XOS 에이전트를 실행하세요.

./start.sh

노트

DBX 에이전트로 모니터링한 데이터를 전송하기 위해 dbx_port로 설정한 포트(default 3002)가 열려 있어야 합니다. (UDP Outbound)
XOS 에이전트를 백그라운드로 실행하려면 ./startd.sh 파일을 실행하세요.

다음 단계

설치 점검하기

프로젝트 생성 및 에이전트 설치, 기본 에이전트 옵션까지 모두 적용했다면 다음 문서에서 점검 사항을 확인하세요.
설치 문제 해결

에이전트 설치 시 발생할 수 있는 다양한 문제들과 이를 해결하기 위한 구체적인 지침을 제공합니다. 자세한 내용은 다음 문서를 참조하세요.
에이전트 설정

에이전트 설정(whatap.conf) 파일에 옵션을 적용해 모니터링을 위한 다양한 기능을 제공합니다. 자세한 내용은 다음 문서를 참조하세요.
데이터베이스 서버 자원을 추가로 모니터링하려면 부가 에이전트(XOS)에 추가 옵션을 설정하세요. 자세한 내용은 다음 문서를 참조하세요.

모니터링 시작하기

모든 설정을 완료한 다음 데이터베이스 서버의 지표를 에이전트가 정보를 수집하기 시작합니다. 먼저 인스턴스 목록 메뉴에서 모니터링 데이터가 수집되는지 확인하세요. 인스턴스 목록에 대한 자세한 내용은 다음 문서를 참조하세요.

와탭 데이터베이스 에이전트 다운로드​

계정 생성​

IAM 인증으로 접속하기​

1단계. 접속 계정 준비하기​

2단계. whatap.conf 설정하기​

3단계. AWS 사전 설정하기​

4단계. Role 설정하기​

DB 접속 정보 암호화(UID 생성 및 갱신)​

특수문자 포함 시 처리 방법​

1단계: 퍼센트 인코딩 적용 (필수)​

2단계: Escape 문자 적용 (필요 시)​

모니터링 시작하기​

서비스 등록하기​

서비스 삭제하기​

부가 에이전트(XOS) 설치 및 기타 옵션 적용하기​

whatap.conf 파일 설정하기​

xos.conf 파일 설정하기​

XOS 에이전트 실행하기​

다음 단계​