DBX 에이전트 설정

DBX 에이전트에 필요한 설정은 whatap.conf 파일에 작성합니다. 설정할 수 있는 옵션은 다음을 참조하세요.

기본 옵션

license String

에이전트를 설치할 때 서버로부터 부여받은 프로젝트 액세스 키를 설정합니다. 프로젝트 액세스 키는 에이전트가 속한 프로젝트와 보안 통신을 위한 암호 키를 포함하고 있습니다.
whatap.server.host String

기본값 127.0.0.1,127.0.0.1

에이전트가 수집한 데이터를 전송할 와탭 수집 서버의 IP 주소를 설정하세요. 수집 서버 이중화로 2개 이상의 IP를 가진 경우 쉼표(,)를 구분자로 사용하세요. 설정한 IP 주소에는 수집 서버 proxy 데몬이 리스닝 상태로 서비스돼야 합니다.

whatap.server.port String

기본값 6600

수집 서버 포트(port)를 설정합니다. 포트는 하나만 설정할 수 있으므로 whatap_server_host에 설정한 수집 서버들은 동일 포트를 사용해야 합니다.
dbms String

mysql

주의
다른 옵션 값을 입력할 경우 모니티링을 위한 데이터 수집이 정상 작동하지 않을 수 있습니다.

db_ip String

모니터링할 데이터베이스 서버의 IP 주소를 설정합니다.

db_port String

데이터베이스가 통신에 사용하는 포트를 설정합니다.

aws_iam_auth Boolean

기본값 false

DB 비밀번호 대신 AWS IAM 인증 토큰으로 접속하는 옵션입니다. true로 설정하면 IAM 인증 토큰으로 접속하고, 기본값인 false인 경우 기존 비밀번호 방식으로 접속합니다.

AWS RDS·Aurora(MySQL, MariaDB, PostgreSQL) 환경에서 사용할 수 있습니다. Oracle, SQL Server, DB2는 지원하지 않습니다.

설정 방법은 IAM 인증으로 접속하기를 참조하세요.

노트
aws_arn 옵션 값에 따라 whatap.conf에 AWS 액세스 키(access key)와 시크릿 키(secret key)를 직접 입력할 수도 있습니다.
db_ssl Boolean

기본값 false

DB 접속에 SSL을 사용할지 설정합니다. IAM 인증을 사용하려면 true로 설정하세요.

mariadb_driver Boolean

기본값 false

MariaDB 고유 인증 방식(예: ed25519)을 사용하는 환경을 모니터링하기 위한 옵션입니다. true로 설정하면 기존 MySQL 드라이버 대신 MariaDB 전용 드라이버(org.mariadb.jdbc)로 접속하여, MySQL 드라이버로는 인증할 수 없었던 ed25519 인증 계정을 모니터링할 수 있습니다.

노트
이 옵션을 사용하려면 에이전트 설치 경로의 jdbc/ 디렉터리에 MariaDB Connector/J(3.x 버전) 드라이버 파일을 배치해야 합니다.
SSL 연결이 필요한 환경(예: require_secure_transport=ON)에서는 connect_option=?sslMode=TRUST 옵션과 함께 사용하세요.

데이터 수집

db_param_enabled Boolean

기본값 true

DB 파라미터 수집 여부를 설정합니다.

conn_fail_count Int

기본값 15

15번 연속 connection error가 발생할 때 알림을 보냅니다. 원하는 횟수를 입력해 알림 발생 기준을 조정할 수 있습니다.

deadlock_interval Int

기본값 60

deadlock 정보를 가져오는 간격(단위: 분)을 설정합니다. deadlock 정보는 설정한 간격 동안 발생했던 가장 마지막의 deadlock 정보만을 가져옵니다.

long_run_session_sec Second

기본값 10 (단위: 초)

설정한 시간보다 길게 수행되고 있는 세션을 long run 세션으로 처리합니다.

tables Boolean

기본값 true

테이블 사이즈 정보를 수집합니다. 통계/보고서 > 데이터베이스 사이즈 메뉴에서 해당 데이터베이스를 선택하면 테이블 사이즈 정보를 확인할 수있습니다.

table_filesize Boolean

기본값 true

테이블 사이즈 수집 시 innodb_tablespaces의 file_size를 함께 수집합니다.

tables_hour Int

기본값 5

테이블 사이즈 정보를 저장하기 위해 정보를 수집하는 시각을 설정합니다. 기본값으로 5이며 새벽 5시에 수집을 시작합니다.

tables_min_row Int

기본값 10000

테이블 정보를 수집할 때 설정한 값보다 작은 row 수를 가진 테이블 정보는 수집하지 않습니다.

replication_name String

리플리케이션 이름을 설정하면 동일한 replication_name을 갖는 DB 사이에 Master/Slave 관계가 있는 것으로 간주합니다.

리플리케이션 세트를 정의하는 옵션으로 마스터, 슬레이브 노드에 모두 동일한 값의 replication_name 옵션을 설정하면 인스턴스 모니터링에서 트리 구조로 표시됩니다. 또한 이 옵션 값을 기준으로 Flex 보드에서 리플리케이션 상태를 모니터링하는 위젯을 제공합니다.

skip_whatap_session Int

기본값 0

1을 설정하면 와탭에서 수집하기 위한 query가 동작하는 세션을 active session list에 표시하지 않습니다.(기본값: 0)

skip_sys_session Int

기본값 1

2를 설정하면 sys 세션(root,system user,event_scheduler)이 active session에서 보이지 않습니다. 1을 설정하면 sys 세션이 보이지만 total runtime에서는 제외합니다.
save_literal_param Boolean

기본값 true

리터럴 파라미터 수집 여부를 설정합니다. false로 설정하면 리터럴 파라미터를 수집하지 않습니다.
sqlstat_send_interval Int

기본값 5분

SQL 통계 데이터를 생성하고 전송하는 주기를 설정합니다. 1분 또는 5분 으로 설정할 수 있으며, 보다 정밀한 분 단위 통계 분석이 필요한 경우 1로 설정하면 됩니다. 이 설정은 Top SQL 화면에서 1분 단위의 상세한 분석을 가능하게 해줍니다.
statements_min_row Int

기본값 10000 (row)

MYSQL SQL 통계 메뉴에서 사용하는 데이터를 수집하는 기준입니다. performance_schema.events_statements_summary_by_digest를 조회하며 다음 합산 값이 statements_min_row 보다 큰 경우 수집합니다.

sum_rows_affected + sum_rows_sent + sum_rows_examined

노트
MYSQL SQL 통계 메뉴에 대한 자세한 내용은 다음 문서를 참조하세요.

xview_min_sec Int

기본값 0

xview 수집 시, 쿼리의 수행 시간이 설정된 시간보다 오래 걸릴 때만 수집합니다. 기본 설정으로는 수행 시간이 0초 이상인 모든 쿼리를 수집합니다.

trx_rseg_history_len Boolean MySQL 5.7 or later DBX agent v1.6.15 or later

기본값 false

trx_rseg_history_len 지표를 수집 여부를 설정합니다. true로 설정하면 db_mysql_counter 카테고리에서 확인할 수 있습니다.
active_transactions Boolean MySQL 5.5 or later DBX agent v1.6.15 or later

기본값 false

active_transactions 지표를 수집 여부를 설정합니다. true로 설정하면 db_mysql_counter 카테고리에서 확인할 수 있습니다.
collect_variables_metric Boolean DBX agent v1.6.15 or later

기본값 false

DB 파라미터를 실시간으로 수집할 수 있습니다. variables_metric 옵션에 설정한 파라미터를 수집합니다.
variables_metric String DBX agent v1.6.15 or later

uptime, version, read_only와 같이 DB 파라미터 이름을 설정하세요. 2개 이상의 값을 설정하려면 쉼표(,)를 구분자로 이용하세요. collect_variables_metric 옵션을 true로 설정한 다음 DB 파라미터 이름을 설정하면, db_mysql_variables 카테고리에서 확인할 수 있습니다.
whatap.conf
```
collect_variables_metric=true
variables_metric=uptime,version
```

사용자 지표 수집 (SQLMON)

SQLMON으로 사용자 정의 SQL 결과를 주기적으로 수집해 메트릭스로 저장합니다. 결과가 숫자이고 실행 부하가 낮은 쿼리에 적합합니다.

sqlmon Int

기본값 1
- 1 dbx와 sqlmon 동시 실행
- 2 sqlmon만 실행

지원 버전: dbx 2.3.5 이상

설정하기

dbx 에이전트 하위에 sqlmon 디렉터리를 만들고, 수집하려는 쿼리를 <filename>.sql 파일로 생성합니다.

dbx/
└── sqlmon/
    ├── active_sessions.sql
    └── lock_count.sql

수집할 쿼리를 <filename>.sql 파일로 저장합니다.

.sql 파일의 첫 번째 라인에 실행 옵션을, 두 번째 라인부터 SQL 문을 작성합니다.

옵션 형식
주기(분);동작시간;태그명
SQL문

항목	설명	예시
주기	실행 주기(분 단위), 최솟값 `1`	`1` → 1분마다 실행
동작 시간	`HHMM-HHMM` 형식, 쉼표(`,`)로 여러 구간 지정 가능. `0`이면 상시 실행	`0900-1100` → 09:00 ~ 11:00에만 실행
태그명	메트릭스에 저장할 태그 이름. 생략 시 파일명이 태그명으로 사용됨	`whatap`

예시: 1분 주기, 09:00~11:00 동작, 태그명 whatap
1;0900-1100;whatap
SELECT count(*) FROM active_sessions

예시: 1분 주기, 상시 동작, 태그명은 파일명 사용
1;0
SELECT count(*) FROM active_sessions

노트

동작 시간은 날짜를 걸쳐 설정할 수 있습니다. (예: 2300-0100 → 23:00 ~ 익일 01:00)
태그명을 생략할 경우 동작 시간 뒤에 세미콜론(;)을 붙이지 않습니다.
SQL 문 끝에 세미콜론(;)을 붙이지 않습니다.

whatap.conf에 SQLMON을 활성화합니다.
에이전트를 재기동합니다.
사이트맵 > 메트릭스 조회에서 sqlmon 카테고리를 확인합니다.

# whatap.conf
sqlmon=1

락 수집 관련 설정

모니터링 대상 DB MySQL 8.0이상, DBX에이전트 2.53.01 이상 일 경우 락 모니터링 수집 조건을 다양하게 줄 수 있습니다.

lock Boolean

기본값 true

락 수집 여부를 지정합니다.
skip_lock_active_limit Int

기본값 150

active_sessions(Threads_running) 갯수가 skip_lock_active_limit 이상일 경우 lock 수집 하지 않습니다.
lock_interval Int

기본값 5 (s)

lock 수집 주기를 지정합니다.
custom_lock_interval String

지정한 시간대의 lock 수집 주기를 지정합니다.

노트
ex) custom_lock_interval=60;0000-0230 # 00:00부터 02:30 까지는 lock 수집 주기를 60초로 지정합니다.
custom_lock_interval=0;0000-0230 # 00:00부터 02:30 까지는 lock을 수집하지 않습니다.

액티브 세션 제외 설정

DBX 에이전트는 MySQL의 액티브 세션 목록을 수집하지만 특정 세션을 제외할 수 있는 옵션을 제공합니다. 제외한 세션은 total_runtime을 계산할 때 포함하지 않으며 SQL 통계 메뉴에서도 해당 SQL은 표시되지 않습니다.

limit_active_session Int

기본값 200

active session 을 지정한 갯수까지만 수집합니다. 0으로 설정하면 limit없이 수집합니다.
skip_command String

액티브 세션 수집 시 옵션값으로 설정한 command에 해당하는 세션은 수집하지 않습니다. 예를 들어, 다음과 같이 설정하면 Daemon과 Sleep 상태의 세션은 수집에서 제외할 수 있습니다.
whatap.conf
```
skip_command=Daemon,Sleep
```
노트
옵션값으로 설정할 수 있는 command에 대한 자세한 내용은 다음 링크를 참조하세요.
skip_sys_session Int

기본값 1
- 0: sys 세션(root, system user)을 액티브 세션 수집과 total_runtime에 포함합니다.
- 1: sys 세션을 액티브 세션 수집에 포함하지만 total_runtime에서는 제외합니다.
- 2: sys 세션을 액티브 세션 수집과 total_runtime에서 제외합니다.
skip_user String

옵션값으로 설정한 사용자 계정을 액티브 세션과 total_runtime에서 제외합니다. 예를 들어, 다음과 같이 설정하면 root, system user, event_scheduler 계정에 대한 수집을 제외할 수 있습니다.
whatap.conf
```
skip_user=root,system user,event_scheduler
```
skip_whatap_session Int

기본값 0

옵션값을 1로 설정하면 와탭의 수집 쿼리를 액티브 세션 수집과 total_runtime에서 제외합니다.

슬로우 쿼리 수집 설정

슬로우 쿼리를 수집하려면 먼저 데이터베이스(DB)를 설정한 후, 사용자의 환경(온프레미스 또는 AWS RDS/Aurora)에 따라 WhaTap 설정 방법이 달라집니다.

노트

슬로우 쿼리 기능은 MySQL과 PostgreSQL만 지원합니다.

주의

데이터베이스 설정 확인하기

WhaTap 설정 전, MySQL 데이터베이스(DB)에 슬로우 쿼리 관련 파라미터를 설정해야 합니다. 슬로우 쿼리 로그 기능이 활성화되어 있는지 확인하고 WhaTap을 설정합니다.

slow_query_log=on  
long_query_time=3  # 3초 

온프레미스 환경

자체 서버에서 운영하는 경우, WhaTap의 DBX/XOS 설정 방식을 사용합니다. DBX 에이전트 설치 외에 DB 서버에 XOS를 반드시 설치해야 합니다. XOS 에이전트 설정 방법은 다음 문서를 참고하세요.

DBX whatap.conf 파일에 slow_query_log=on 옵션을 추가합니다.
- slow_query_log Boolean
  슬로우 쿼리 로깅 기능을 활성화(on)하거나 비활성화(off)합니다. MySQL의 기본값은 on입니다
XOS가 설치되어 있으면 파일명을 자동 인식합니다. 파일명이 자동으로 인식되지 않는다면, XOS whatap.conf 파일에 slow_query=로 설정합니다.

AWS RDS/Aurora 환경

AWS RDS/Aurora 환경은 XOS 에이전트를 설치할 수 없으므로, DBX 에이전트 설정 또는 클라우드 설정을 통해 슬로우 쿼리를 수집할 수 있습니다.

DBX 에이전트 설정하기

AWS RDS/Aurora 환경에서 슬로우 쿼리를 수집하기 위해 DBX whatap.conf 파일에 다음과 같이 설정합니다.
whatap.conf
```
slow_query_log=on  # 클라우드 설정
cloud_watch=on
aws_region=
aws_arn=
cloud_watch_metrics=
cloud_watch_instance= 
```
클라우드 설정하기

관리 > 클라우드 설정 메뉴에서 제공되는 가이드를 따라 실행하면 사용자의 AWS 환경에서 자동으로 모니터링 리소스를 생성하여 슬로우 쿼리 데이터를 수집합니다. 별도의 추가 설정이 필요하지 않습니다. 자세한 내용은 다음 문서를 참고하세요.

AES 256 암호화 적용

와탭 DBX 에이전트는 수집된 데이터를 암호화하여 서버로 전송합니다. 데이터의 중요도나 설정에 따라 이를 변경할 수 있습니다. 기본적으로 XOR 연산과 AES 알고리즘을 통한 암호화를 사용하며 평문을 128비트 단위로 나누어 암호화, 복호화를 수행합니다. 사용자 설정에 따라 256비트까지 확장할 수 있습니다.

와탭 DBX 에이전트를 설치한 경로에서 whatap.conf 파일에 다음과 같이 옵션을 추가하세요.

whatap.conf
cypher_level=256

설정을 추가한 다음 에이전트를 다시 시작하세요.

에이전트 이름 설정

자동 설정하기

에이전트 설정(whatap.conf)에서 이름을 설정하지 않으면, 에이전트 이름은 IP 주소와 포트 번호가 결합되어 자동 지정됩니다. 예를 들어, IP 주소가 10.11.12.13이고 포트 번호가 3000이라면, 에이전트 이름은 DBX-12-13-3000으로 설정됩니다.

에이전트 이름을 결정하는 주요 변수는 다음을 참조하세요.

설정	설명
`{type}`	DBX 값을 사용합니다.
`{ip0}`	IPv4 주소 중 첫 번째 단위를 사용합니다. (예시, 10.11.12.13 중 10)
`{ip1}`	IPv4 주소 중 두 번째 단위를 사용합니다. (예시, 10.11.12.13 중 11)
`{ip2}`	IPv4 주소 중 세 번째 단위를 사용합니다. (예시, 10.11.12.13 중 12)
`{ip3}`	IPv4 주소 중 네 번째 단위를 사용합니다. (예시, 10.11.12.13 중 13)
`{port}`	데이터베이스 서버 포트

노트

RDS와 같이 IP 주소가 숫자가 아니라면 DBX-{ip0}-{hash}-{port} 형식으로 이름이 설정됩니다. 여기서 {hash} 값은 IP 주소를 4자리의 16진수로 변환한 값입니다.

수동 설정하기

에이전트 이름을 직접 설정하고 싶다면, whatap.conf 파일에서 whatap.name 또는 object_name 옵션에 원하는 이름을 입력하세요. 사용자가 입력한 이름이 에이전트 이름으로 설정됩니다.

whatap.conf
whatap.name=agent-1234
# or
object_name=agent-1234

화면에서 설정하기

whatap.conf 파일을 직접 편집하지 않고, 와탭 모니터링 서비스 화면에서 같은 옵션을 설정할 수도 있습니다. 관리 > 에이전트 설정 메뉴를 선택하세요. 화면에서 저장한 값은 에이전트 설치 경로의 설정 파일과 동기화됩니다.

왼쪽 목록에서 설정할 에이전트를 선택하세요.
옵션 값을 입력한 후 저장하세요.
변경한 옵션을 적용하려면 화면 오른쪽 위 재시작 버튼을 클릭하세요.

에이전트 설정 메뉴는 DBX 에이전트 2.63.05 버전 이상에서 사용할 수 있습니다. 이보다 낮은 버전이면 설정 폼 대신 업데이트 안내가 표시됩니다.

AI 설정 진단

WhaTap AI가 현재 설정값과 아직 설정하지 않은 옵션을 데이터베이스 모니터링 관점에서 진단하고 개선안을 추천합니다. 설정 항목에 익숙하지 않은 사용자나 설치를 담당하는 엔지니어가 초기 설정을 잡을 때 활용할 수 있습니다.

추천 항목 중 값이 구체적으로 정해진 항목은 적용 버튼을 클릭하면 폼에 바로 반영됩니다.
이름이나 식별자처럼 사용자가 값을 정해야 하는 항목은 입력창에 값을 입력한 후 적용하세요.
추천 항목을 한 번에 반영하려면 모두 적용 버튼을 클릭하세요.

적용한 값은 폼에만 임시로 반영됩니다. 드로어 안 저장 버튼을 클릭한 후 확인 모달에서 저장을 완료하세요. 저장한 옵션은 에이전트를 다시 시작한 다음 적용됩니다.

기본 옵션​

데이터 수집​

사용자 지표 수집 (SQLMON)​

설정하기​

락 수집 관련 설정​

액티브 세션 제외 설정​

슬로우 쿼리 수집 설정​

온프레미스 환경​

AWS RDS/Aurora 환경​

AES 256 암호화 적용​

에이전트 이름 설정​

자동 설정하기​

수동 설정하기​

화면에서 설정하기​

AI 설정 진단​