TrueWatch 워크숍: TrueWatch로 MySQL 모니터링하기: 처음부터 끝까지 설정 가이드 (단계별)

참고: MySQL 통합에 대한 전체 세부 정보와 필드 정의는 TrueWatch MySQL 통합 문서에서 확인할 수 있습니다.

이 가이드로 달성할 수 있는 것

이 단계별 가이드를 따라 하면 다음을 수행할 수 있습니다:

TrueWatch DataKit을 설치 및 구성하여 MySQL에 연결
보안이 강화된 최소 권한 모니터링 사용자 생성
(선택 사항) MySQL 일반/슬로우 쿼리 로그 활성화 및 수집
TrueWatch에서 실용적인 MySQL 모니터링 대시보드 구축

이 가이드는 누구를 위한 것인가: 엔터프라이즈급 MySQL 모니터링을 빠르게 구축하고자 하는 백엔드 엔지니어, SRE, DBA를 위한 가이드입니다.

사전 준비 사항

접근 가능한 MySQL 5.7+ / 8.0+ 인스턴스 (클라우드 RDS도 가능)
권장: performance_schema를 완전히 활용하려면 MySQL 8.0 사용
사용자를 생성하고 권한을 부여할 수 있는 권한
TrueWatch DataKit을 배포할 수 있는 환경 (Docker 또는 호스트 설치)

아키텍처 한눈에 보기

MySQL  ← (모니터링 사용자, performance_schema)
  ↑
DataKit (컨테이너 또는 호스트) → 메트릭 / 로그 / 슬로우 쿼리를 TrueWatch로 전송

eBPF/호스트 수준 텔레메트리가 필요하신가요? 호스트 설치를 권장합니다. DB 전용 모니터링이라면 컨테이너로 충분합니다.

1단계: performance_schema 확인 및 활성화

많은 데이터베이스 메트릭이 MySQL performance_schema에서 수집됩니다. 활성화 여부를 확인하세요:

SHOW VARIABLES LIKE 'performance_schema';

Value = OFF로 표시되면 환경에 맞게 활성화하세요:

my.cnf에서:

[mysqld]
performance_schema=ON

MySQL을 재시작한 후 ON으로 설정되었는지 확인하세요.

관리형 서비스(예: Aliyun RDS)는 performance_schema가 비활성화되어 있거나 제한된 경우 일부 측정 항목(예: mysql_user_status)을 제한할 수 있습니다. 공식 FAQ 및 해결 방법은 TrueWatch MySQL 통합 문서를 참고하세요.

2단계: 최소 권한 모니터링 사용자 생성

보안 및 관찰 가능성을 위해 전용 읽기 전용 사용자를 생성하세요 (사용자명/비밀번호는 필요에 맞게 변경):

CREATE USER 'datakit'@'%' IDENTIFIED WITH caching_sha2_password BY 'datakit_password';
GRANT PROCESS ON *.* TO 'datakit'@'%';
GRANT SELECT ON *.* TO 'datakit'@'%';
GRANT SELECT ON performance_schema.* TO 'datakit'@'%';
GRANT SELECT ON mysql.user TO 'datakit'@'%';
GRANT REPLICATION CLIENT ON *.* TO 'datakit'@'%';
FLUSH PRIVILEGES;

이러한 권한이 중요한 이유:

PROCESS: 실행 중인 쿼리와 연결을 검사
SELECT (performance_schema 포함): 성능 및 통계 데이터 읽기
REPLICATION CLIENT: 복제 상태 읽기 (해당하는 경우)

3단계: DataKit 설치 및 시작 (택 1)

DataKit을 컨테이너 또는 호스트에 설치하세요 (공식 가이드에서 간소화된 명령어):

3A. Docker (빠른 시작)

#1) TrueWatch 콘솔 → DataKit → Docker에서 DataWay를 선택하고 생성된 명령어/토큰을 복사하세요. #2) 대상 호스트에서 다음을 실행하세요:

docker run -d --name datakit \
  --hostname "$(hostname)" \
  -p 9529:9529 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/conf.d:/usr/local/datakit/conf.d \
  -e ENV_DATAWAY="https://<your-openway-host>?token=<your_token>" \
  -e ENV_HTTP_LISTEN="0.0.0.0:9529" \
  pubrepo.truewatch.com/truewatch/datakit:1.80.1

#3) 다음 단계의 mysql.conf를 마운트된 conf.d/ 디렉터리에 넣으세요 (conf.d/db/ 권장). DataKit이 자동으로 로드합니다.

더 많은 환경 변수 및 고급 옵션(프록시, 리소스 제한, 로깅 등)은 공식 문서를 참고하세요: DataKit 설치 문서.

3B. 호스트 설치 (eBPF/호스트 메트릭 권장)

#1) TrueWatch 콘솔 → DataKit → Linux에서 DataWay를 선택하고 토큰이 포함된 명령어를 복사하세요.

#2) 대상 호스트에서 다음을 실행하세요 (DataKit을 설치하고 시작):

DK_DATAWAY="https://<your-openway-host>?token=<your_token>" bash -c "$(curl -L https://static.truewatch.com/datakit/install.sh)"

#3) mysql.conf를 DataKit의 conf.d/db/ 아래에 배치한 후 서비스를 재시작하세요:

sudo systemctl restart datakit

DK_INSTALL_ONLY, 프록시, 업그레이드 등 추가 옵션은 공식 문서를 참고하세요: DataKit 설치 문서.

4단계: DataKit MySQL 입력 구성 (inputs.mysql)

DataKit의 conf.d/db 디렉터리에서 mysql.conf를 생성하거나 편집하세요:

[[inputs.mysql]]
  host = "db"              # 또는 사용 중인 MySQL 주소 (FQDN/IP)
  user = "datakit"         # 모니터링 사용자
  pass = "datakit_password"
  port = 3306
  interval = "10s"
  innodb = true             # 주요 InnoDB 메트릭 수집
  dbm = true                # 데이터베이스 모니터링 활성화 (쿼리 분석)
  election = true           # DataKit이 여러 개일 경우 하나의 리더만 수집

필드 의미 및 튜닝 팁: TrueWatch MySQL 통합 문서를 참고하세요.

DataKit을 재시작(또는 핫 리로드)하면 메트릭 수집이 시작됩니다.

5단계 (선택 사항): MySQL 일반/슬로우 쿼리 로그 수집

TrueWatch는 MySQL 일반 및 슬로우 쿼리 로그를 수집하여 지연 시간이 긴 SQL을 정확히 파악할 수 있습니다.

5A. 슬로우 쿼리 로깅 활성화 (MySQL)

SET GLOBAL slow_query_log = 'ON';
SET GLOBAL log_queries_not_using_indexes = 'ON';  -- 선택 사항: 인덱스를 사용하지 않는 쿼리 표시
-- 권장 튜닝 (my.cnf를 통해 영구 적용):
SET GLOBAL long_query_time = 1;                   -- 슬로우 쿼리 기준 임계값 (초)

영구적으로 적용하려면 my.cnf에 추가하세요 (예시):

[mysqld]
slow_query_log=ON
long_query_time=1
log_queries_not_using_indexes=ON
log_output=FILE
slow_query_log_file=/var/log/mysql/slow.log

5B. DataKit 로그 수집 (호스트 설치 시 일반적)

conf.d/mysql.conf에 추가하세요 (또는 새 섹션 생성):

[inputs.mysql.log]
  files = ["/var/log/mysql/*.log"]  # 실제 절대 경로에 맞게 조정

로그 필드 매핑(일반/슬로우)에 대한 자세한 내용은 TrueWatch MySQL 통합 문서를 참고하세요.

6단계: 데이터 수집 확인

#1) DataKit 상태 페이지(기본 포트 9529)에서 입력 상태를 확인하세요 #2) TrueWatch Explorer에서 mysql, mysql_replication_log와 같은 측정 항목을 검색하세요 #3) connections, query_time, lock_time, rows_examined, rows_sent와 같은 필드를 확인하세요

특정 측정 항목(예: mysql_user_status)이 누락된 경우 performance_schema가 활성화되어 있는지 확인하거나 RDS 제한 사항을 확인하세요. TrueWatch MySQL 통합 문서의 FAQ를 참고하세요.

7단계: 실용적인 MySQL 대시보드 구축

A. 템플릿 대시보드 사용 (권장)

#1) 왼쪽의 Scenes → 상단의 Dashboards → Create를 클릭하세요.

#2) System Views에서 mysql을 검색하고 Mysql Monitor View(또는 클라우드별 MySQL 템플릿)를 선택하세요.

#3) 이 템플릿에는 연결, 쿼리 지연 시간, InnoDB, 복제에 대한 일반적인 차트가 포함되어 있습니다. 필요에 따라 커스터마이즈하세요.

템플릿 소스 및 필드 참조: TrueWatch MySQL 통합 문서.

B. 위젯 직접 구성하기 (유연한 방식)

대시보드 미리보기

위젯 구성 예시 (QPS / TPS)

QPS: mysql 메트릭의 Questions에 non_negative_derivative를 적용하여 초당 쿼리 수를 구합니다.

TPS: A+B 표현식을 사용하여 Handler_commit과 Handler_rollback에 각각 non_negative_derivative를 적용한 후 합산하여 초당 트랜잭션 수를 구합니다.

아래는 일반적인 DB 모니터링 요구 사항에 대해 검증된 위젯입니다. 필요에 따라 Simple/Expression/DQL 쿼리를 사용하여 TrueWatch 대시보드에 추가하세요.

필드 예시는 mysql, mysql_replication_log와 같은 측정 항목을 참조합니다. Explorer에서 필드 사용 가능 여부를 확인하세요.

A. 개요

시계열 (연결 수)
- 소스: mysql.connections
- 차원: server (host:port)
- 목적: 동시성 및 스파이크 모니터링
단일 값/추세 (p95 쿼리 시간)
- 소스: mysql.query_time
- 집계: 5분 동안의 p95
- 목적: 테일 레이턴시를 한눈에 파악
단일 값/추세 (잠금 대기 시간)
- 소스: mysql.lock_time
- 집계: 5분 평균 (또는 p95)
- 목적: 잠금 경합 및 블로킹 감지
단일 값 (분당 슬로우 쿼리 수)
- 소스: 슬로우 쿼리 로그 (inputs.mysql.log)
- 방법: db_slow_statement가 존재하는 이벤트 수를 카운트
- 목적: 슬로우 쿼리 급증 감지

B. InnoDB 및 처리량

시계열 (검사한 행 수 / 전송한 행 수)
- 소스: mysql.rows_examined, mysql.rows_sent
- 집계: 합계 또는 비율
- 목적: 읽기 양 대비 반환된 행 수를 파악하여 효율성 추정
테이블 (상위 핫 테이블/인덱스)
- 소스: mysql.index_name, mysql.object_name, mysql.object_schema
- 집계: query_signature 또는 object_name으로 그룹화하여 평균 query_time과 개수 표시
- 목적: 핫 테이블/인덱스 및 느린 작업 파악

C. 상위 N개 문제 쿼리 (로그/이벤트)

테이블 (평균 소요 시간 기준 상위 슬로우 쿼리)
- 소스: 슬로우 쿼리 로그 또는 mysql 이벤트
- 열: query_signature, sql_text (또는 정규화된 message)
- 메트릭: avg(query_time), count()
테이블 (상위 대기 이벤트)
- 소스: mysql.wait_event, event_name
- 메트릭: sum(event_timer_wait)

D. 복제 (해당하는 경우)

단일 값/테이블 (마스터 / 실행된 GTID Set 요약)
- 소스: mysql_replication_log.Executed_Gtid_Set, Master_Host, Master_Port
- 목적: 마스터 관계 및 GTID 진행 상황 확인

팁: 사용 가능하다면 Seconds_Behind_Master를 단일 값/시계열로 추가하여 복제 지연을 확인하세요.

모범 사례 및 보안

애플리케이션 계정과 분리된 전용 최소 권한 모니터링 사용자를 사용하세요
스테이징 환경에서는 더 높은 수집 빈도(예: interval = "10s")를 사용해도 무방하지만, 프로덕션에서는 비용/성능에 맞게 조정하세요
long_query_time과 log_queries_not_using_indexes를 조정하여 노이즈와 신호의 균형을 맞추세요
컨테이너 환경에서는 민감한 경로 공유를 피하기 위해 파일 마운트보다 stdout/로그 드라이버를 사용하세요
자격 증명은 파일에 커밋하지 말고 시크릿/환경 변수에 저장하세요

FAQ 및 문제 해결

Q: mysql_user_status 측정 항목이 보이지 않습니다.

A: performance_schema가 ON인지 확인하세요:

SHOW VARIABLES LIKE 'performance_schema';

OFF인 경우 사용 중인 DB/RDS 제공업체에 맞게 활성화하세요. 일부 RDS 제품은 이를 제한할 수 있습니다. TrueWatch MySQL 통합 문서를 참고하세요.

Q: DataKit은 실행 중인데 데이터가 수집되지 않습니다.

mysql.conf의 연결 정보(host/user/pass/port)를 확인하세요
보안 그룹/방화벽이 DataKit에서 MySQL로의 접근을 허용하는지 확인하세요
DataKit 상태 페이지/로그에서 연결 또는 권한 오류를 확인하세요

Q: 슬로우 쿼리가 표시되지 않습니다.

slow_query_log가 활성화되어 있는지 확인하세요
컨테이너에서 파일을 수집하는 경우 절대 경로가 읽기 가능한지 확인하세요 (stdout/사이드카 방식이 더 간단한 경우가 많습니다)
Explorer에서 로그 인덱스에서 마커(예: [MYSQL_QUERY]) 또는 슬로우 로그 필드를 검색하세요

참고 자료

공식 통합 문서 및 필드 정의: TrueWatch MySQL 통합 문서
통합 진행 과정 및 근거 (모니터링 사용자, DataKit 입력, 사이드카): demo-project/INTEGRATION_GUIDE.md

이 단계들을 통해 MySQL을 TrueWatch와 통합하고 실행 가능한 대시보드를 구축했습니다. 다음으로는 알림(Monitors), 예약된 리포트, 서비스 간 상관관계 분석을 추가하여 엔드투엔드의 프로덕션 준비가 완료된 데이터베이스 관찰 가능성을 달성하세요.