본문으로 건너뛰기

직접 설치

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

구성도 확인​

DBX 에이전트는 별도 서버에 설치하거나 DB 서버에 설치할 수 있습니다. 설치할 방식을 선택하고 구성과 방화벽을 확인하세요.

별도 서버에 설치DB 서버에 같이 설치

계정 생성​

노트

  • 권한을 가진 계정이 있다면 이 단계를 생략하고 다음 단계로 넘어가세요.

  • 예시 코드에서 DB_User는 DB 사용자 계정 이름입니다. 사용자가 이용하는 사용자 계정 이름으로 변경하세요.

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

  • 권한이 없는 계정은 모니터링이 정상적으로 이루어지지 않을 수 있습니다.

  • 리플리케이션 구조의 경우 계정 생성 및 권한 부여는 Master DB에서만 수행해야 합니다. (Slave DB에서 수행할 경우 복제가 깨질 수 있습니다.)

  create user DB_User identified by 'DB_PASSWORD'; # 원하는 password를 입력하세요.
  grant process on *.* to DB_User;
  grant select on performance_schema.* to DB_User;
  grant show databases on *.* to DB_User;

  MySQL 8.0 이상에서 락 정보를 모니터링하려면 다음 권한이 반드시 필요합니다.

  grant select on `sys`.`sys_config` TO DB_User;
  grant select on `sys`.`innodb_lock_waits` TO DB_User;
  grant execute on function `sys`.`format_statement` TO DB_User;
  grant execute on function `sys`.`quote_identifier` TO DB_User;
  grant execute on function `sys`.`sys_get_config` TO DB_User;

기능 및 사용 환경에 따라 추가 권한을 부여하세요.

  • 모든 테이블 정보를 수집할 경우

    grant select on *.* to DB_User;

  • 특정 DB의 테이블만 모니터링하는 경우

    grant select on {DB_NAME}.* to DB_User;

  • Replication 사용할 경우

    grant replication client on *.* to DB_User;
    grant replication slave on *.* to DB_User;

  • Kill session 기능을 사용할 경우

    grant super on *.* to DB_User;

  • AWS RDS 환경에서 kill session 기능을 사용할 경우

    grant execute on procedure mysql.rds_kill to DB_User;
권한에 따른 지원 기능 살펴보기

기본 권한 외의 권한은 사용자의 환경에 따라 부여하지 않아도 됩니다. 단, 일부 기능이 동작하지 않을 수 있습니다.

권한command메뉴 및 기능상세 내역
기본 권한grant process on *.* to whatap;액티브 세션 수집 / 락 트리 / 데드락다른 계정에 속한 스레드 정보 표시를 위한 권한, show engine 수행
grant select on performance_schema.* to whatap;액티브 세션 수집 / 락 트리 / MYSQL SQL 통계개별 권한 부여 시 다음 표 내용 참조
grant show databases on *.* to whatap;인스턴스 목록 등데이터베이스 이름 표시
상세 권한grant select on *.* to whatap;
또는
grant select on {DB_NAME}.{TABLE_NAME} to whatap;		데이터베이스 사이즈 / 테이블 사이즈 증감 / Object detail / 플랜 조회MySQL은 해당 테이블에 대한 SELECT 권한이 없으면 데이터베이스 사이즈, Object detail, 플랜 조회 기능을 지원하지 않습니다.
replicationgrant replication client on *.* to whatap;인스턴스 목록 의 S 표시 / replication 정보 수집SHOW MASTER STATUS, SHOW SLAVE STATUS
grant replication slave on *.* to whatap;인스턴스 목록의 M 표시 / replication 정보 수집SHOW SLAVE HOSTS
세션 킬grant super on *.* to whatap;액티브 세션 리스트에서 세션 킬 기능다른 계정에 속한 스레드 종료
grant execute on procedure mysql.rds_kill to DB_User;AWS RDS의 경우 세션 킬 기능-

performance_schema.* 대신 다음 권한을 개별로 부여해도 됩니다.

권한command비고
액티브 세션 / 락 트리performance_schema.data_lock_waitsMySQL 8 버전부터
performance_schema.data_locks
performance_schema.threads-
performance_schema.metadata_locksMariaDB 10.5 버전부터
Wait event 정보performance_schema.events_waits_summary_global_by_event_name-
SQL 통계 정보performance_schema.events_statements_summary_by_digest-
Wait 지표 이름performance_schema.setup_instruments-

IAM 인증으로 접속하기​

정보

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

확인 요청 3건

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

AWS RDS·Aurora 환경에서는 DB 비밀번호 대신 AWS IAM 인증 토큰으로 접속할 수 있습니다. PostgreSQL, MySQL, MariaDB에서 사용할 수 있으며 Oracle, SQL Server, DB2는 지원하지 않습니다.

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

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

IAM 인증으로 접속할 계정을 만들고 SSL 접속을 요구하도록 설정하세요.

SQL
CREATE USER 'DB_User'@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
ALTER USER 'DB_User'@'%' REQUIRE SSL;

다음 권한은 모니터링에 필요한 권한입니다. IAM 인증과는 무관하며, 비밀번호 방식에서도 동일하게 부여합니다.

SQL
GRANT SELECT, PROCESS, REPLICATION CLIENT, REPLICATION SLAVE ON *.* TO 'DB_User'@'%';

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

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

whatap.conf
aws_iam_auth=true
aws_region=ap-northeast-2
db_ssl=true
db_user={db_user}                   # 1단계에서 만든 계정
connect_option=?sslmode=require     # PostgreSQL만 필수

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

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

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

IAM 인증 활성화

RDS 콘솔에서 대상 DB를 선택하고 수정 > 데이터베이스 인증에서 암호 및 IAM 데이터베이스 인증을 선택하세요. 즉시 적용을 선택한 다음 저장하세요.

IAM 정책 생성

IAM 콘솔에서 정책 > 정책 생성 > JSON을 선택하고 다음 정책을 입력하세요. { } 부분은 사용하는 값으로 바꾸세요.

RDS
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["rds-db:connect"],
      "Resource": [
        "arn:aws:rds-db:{REGION}:{ACCOUNT}:dbuser:db-{RESOURCE_ID}/{DB_USER}"
      ]
    }
  ]
}
Aurora
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["rds-db:connect"],
      "Resource": [
        "arn:aws:rds-db:{REGION}:{ACCOUNT}:dbuser:cluster-{RESOURCE_ID}/{DB_USER}"
      ]
    }
  ]
}

여러 인스턴스를 한 번에 허용하려면 와일드카드를 사용하세요.

Resource
"Resource": [
  "arn:aws:rds-db:*:{ACCOUNT}:dbuser:db-*/{DB_USER}",
  "arn:aws:rds-db:*:{ACCOUNT}:dbuser:cluster-*/{DB_USER}"
]

4단계. Role 설정하기​

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

  1. 신뢰할 수 있는 서비스를 EC2로 지정해 IAM Role을 만드세요.

  2. 앞에서 만든 정책을 Role에 부착하세요.

  3. 에이전트를 실행하는 EC2 인스턴스에 Role을 연결하세요. 자세한 방법은 AWS 문서를 참조하세요.

DBX 에이전트 다운로드​

DBX 에이전트 파일을 다운로드하세요. 다음 두 가지 방법을 이용하세요.

  • wget 명령어를 이용해 다운로드할 수 있습니다.

    BASH
    wget -O whatap.agent.database.tar.gz "https://service.whatap.io/download/dbx_agent?type=mysql&format=tar.gz"

  • 명령어로 다운로드할 수 없다면 와탭 모니터링 서비스 화면에서 다운로드 버튼을 선택하세요.

DBX 에이전트 파일을 다운로드한 다음 압축을 해제하세요.

BASH
tar -zxvf whatap.agent.database.tar.gz
노트

보안 설정으로 인해 tar 형식의 파일을 다운로드할 수 없는 사용자를 위해 ZIP 형식의 파일도 함께 제공합니다. 설치 화면에서 .zip 다운로드 버튼을 선택하세요.

DBX 에이전트 설정​

에이전트 설치 화면의 안내에 따라 에이전트 설정을 진행하세요. 화면에 각 항목마다 필요한 정보를 입력하면 설정 내용 및 명령어를 자동 완성할 수 있습니다.

팁

빠른 설정 가이드

setup.sh 스크립트로 간편하게 설정할 수 있습니다. [설정 가이드 보기]

whatap.conf 설정​

압축을 해제한 폴더로 이동해 whatap.conf 파일을 확인하세요. whatap.conf 파일에 프로젝트 액세스 키 정보 및 와탭 서버 정보, db 접속 정보를 입력하세요.

기본 설정​

whatap.conf
license={AccessKey}
whatap.server.host=13.124.11.223/13.209.172.35 # WhaTap server information
dbms=mysql
db=mysql
db_ip={DB_Server_IP}
db_port={DB_Server_Port}

SSL을 사용하는 경우​

whatap.conf
connect_option=?useSSL=true&verifyServerCertificate=false

JDBC 드라이버 접속 시 serverTimeZone 설정이 필요한 경우​

JDBC 드라이버 8.x 버전 이상 등을 이용한다면 접속 URL에 serverTimezone 설정이 필요할 수 있습니다. whatap.conf 파일에 다음 옵션을 설정하세요.

whatap.conf
connect_option=?serverTimezone=SERVER_TIMEZONE
# connect_option=?serverTimezone=UTC

JDBC 다운로드​

압축 파일을 해제한 DBX 에이전트 경로에 데이터베이스 서버의 운영체제와 버전에 맞는 JDBC 드라이버를 다운로드하세요. /압축을 해제한 폴더/jdbc

정보

Mysql & MariaDB 5.5 버전 이상

Select Operating Systems 항목에서 Platform Independent 항목을 선택하세요. 다운받은 파일의 압축을 풀고 jdbc 폴더로 mysql-connector-*.jar 파일을 이동하세요.

JDBC Download

노트

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

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

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

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

주의

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

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

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

BASH
./uid.sh {DB_USER} {DB_PASSWORD}
노트

  • 최초 1회 UID를 생성하면, 이후에는 암호화된 UID를 통해 DB 서버로부터 성능 데이터를 수집합니다.

  • UID 파일을 생성하기 위해서는 프로젝트 액세스 키가 whatap.conf 파일에 설정되어 있어야 합니다. 액세스 키 확인

  • Azure Database 환경의 경우 DB_USER는 DB_USER@DB_name 형식으로 입력해야 합니다.

  • DB_USER 또는 DB_PASSWORD에 특수문자가 포함된 경우, 특수문자 앞에 Escape 문자(\)를 입력하세요.

    Example
    ./uid.sh whatap whatap\!pwd

    # 특수문자가 2개 이상일 경우 각각 이스케이프 문자 추가
    ./uid.sh whatap whatap\!\@pwd

디폴트 플랜 조회하기​

디폴트 플랜 유저 파일 생성 시 에이전트가 사전 정의된 DB 정보를 사용하여 플랜을 자동으로 조회하도록 설정할 수 있습니다.

  1. 에이전트 설정(whatap.conf) 파일에 plan_db 옵션을 추가하고 DB 이름을 입력하세요.

    whatap.conf
    plan_db=(dbname)

  2. DB 설정 후 planuid.sh 스크립트를 사용하여 사용자 및 비밀번호를 설정하세요.

    ./planuid.sh user pwd
    노트

    사용자(user)와 비밀번호(pwd)에 특수 문자가 포함되어 있는 경우 각 특수 문자 앞에 역슬래시(\)를 추가하세요.

    예. user$example → user\$example

모니터링 시작하기​

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

./start.sh

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

./startd.sh

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

부가 에이전트(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)에 추가 옵션을 설정하세요. 자세한 내용은 다음 문서를 참조하세요.

  • 클라우드 설정

    클라우드 서비스에서 제공하는 모니터링 지표를 데이터베이스 프로젝트의 대시보드에서 추가로 수집하고 모니터링하려면 다음 문서를 참조하세요.

  • 모니터링 시작하기

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

최종 수정: