MariaDB Database Monitoring 설정 트러블슈팅

원문 보기 위키 갱신 2026.10.05

이 페이지에서는 MariaDB에서 Database Monitoring을 설정하고 사용할 때 발생하는 일반적인 문제와 해결 방법을 설명드릴게요. Datadog은 최신 안정 버전의 Agent를 유지하고 최신 설정 문서를 따를 것을 권장합니다. 이 문서는 Agent 버전 릴리스에 따라 달라질 수 있어요.

출처: 문서

본문

일반적인 문제 진단하기

Database Monitoring 구성 후 데이터가 표시되지 않음

설정 지침을 따르고 에이전트를 구성한 뒤에도 데이터가 보이지 않는다면, 대부분 에이전트 구성이나 API 키에 문제가 있는 경우가 많아요. 트러블슈팅 가이드를 따라 에이전트에서 데이터를 받고 있는지 확인하세요.

시스템 메트릭 같은 다른 데이터는 받는데 Database Monitoring 데이터(쿼리 메트릭과 쿼리 샘플 등)는 받지 못한다면, 에이전트나 데이터베이스 구성에 문제가 있을 가능성이 높아요. 에이전트 구성을 설정 지침의 예시와 비교해 일치하는지 확인하고, 구성 파일의 위치를 다시 점검하세요.

디버깅을 시작하려면 먼저 Agent status 명령을 실행해 Datadog로 수집되고 전송되는 데이터에 대한 디버깅 정보를 확인하세요.

Config Errors 섹션을 확인해 구성 파일이 유효한지 확인하세요. 예를 들어 다음은 인스턴스 구성이 없거나 파일이 유효하지 않음을 나타냅니다.

  Config Errors
  ==============
    mysql
    -----
      Configuration file contains no valid instances

구성이 유효하다면 출력은 다음과 같아요.

=========
Collector
=========

  Running Checks
  ==============

    mysql (5.0.4)
    -------------
      Instance ID: mysql:505a0dd620ccaa2a
      Configuration Source: file:/etc/datadog-agent/conf.d/mysql.d/conf.yaml
      Total Runs: 32,439
      Metric Samples: Last Run: 175, Total: 5,833,916
      Events: Last Run: 0, Total: 0
      Database Monitoring Query Metrics: Last Run: 2, Total: 51,074
      Database Monitoring Query Samples: Last Run: 1, Total: 74,451
      Service Checks: Last Run: 3, Total: 95,993
      Average Execution Time : 1.798s
      Last Execution Date : 2021-07-29 19:28:21 UTC (1627586901000)
      Last Successful Execution Date : 2021-07-29 19:28:21 UTC (1627586901000)
      metadata:
        flavor: MariaDB
        version.build: unspecified
        version.major: 10
        version.minor: 11
        version.patch: 6
        version.raw: 10.11.6-MariaDB
        version.scheme: semver

출력에 다음 줄이 있고 값이 0보다 큰지 확인하세요.

Database Monitoring Query Metrics: Last Run: 2, Total: 51,074
Database Monitoring Query Samples: Last Run: 1, Total: 74,451

에이전트 구성이 올바르다고 확신되면 에이전트 로그에서 데이터베이스 통합 실행 시도와 관련한 경고나 오류를 확인하세요.

또한 Datadog Agent에서 check CLI 명령을 실행하고 출력에서 오류를 검사해 점검을 명시적으로 실행할 수도 있어요.

# 에이전트 자체 호스팅 설치의 경우
DD_LOG_LEVEL=debug DBM_THREADED_JOB_RUN_SYNC=true datadog-agent check mysql -t 2

# 에이전트 컨테이너 기반 설치의 경우
DD_LOG_LEVEL=debug DBM_THREADED_JOB_RUN_SYNC=true agent check mysql -t 2

쿼리에 explain plan이 없음

일부 또는 모든 쿼리에 explain plan이 없을 수 있어요. 이는 지원되지 않는 쿼리 명령, 지원되지 않는 클라이언트 애플리케이션이 만든 쿼리, 오래된 에이전트, 불완전한 데이터베이스 설정 때문일 수 있어요. explain plan 누락의 가능한 원인은 다음과 같습니다.

이벤트 statements 컨슈머가 없음

explain plan을 캡처하려면 이벤트 statements 컨슈머를 활성화해야 해요. 설정 파일(예: mysql.conf)에 다음 옵션을 추가하면 됩니다.

performance-schema-consumer-events-statements-current=ON

Datadog은 추가로 다음을 활성화할 것을 권장합니다.

performance-schema-consumer-events-statements-history-long=ON

이 옵션은 모든 스레드에서 더 많은 최근 쿼리 추적을 활성화합니다. 켜면 빈도가 낮은 쿼리의 실행 세부 정보를 캡처할 가능성이 높아져요.

explain plan 프로시저가 없음

에이전트는 datadog 스키마에 datadog.explain_statement(...) 프로시저가 존재해야 해요. datadog 스키마 생성에 대한 자세한 내용은 설정 지침을 참고하세요.

에이전트가 explain plan을 수집할 수 있도록 explain_statement 프로시저를 만드세요.

DELIMITER $$
CREATE PROCEDURE datadog.explain_statement(IN query TEXT)
    SQL SECURITY DEFINER
BEGIN
    SET @explain := CONCAT('EXPLAIN FORMAT=json ', query);
    PREPARE stmt FROM @explain;
    EXECUTE stmt;
    DEALLOCATE PREPARE stmt;
END $$
DELIMITER ;

정규화된 explain plan 프로시저가 없음

에이전트는 에이전트가 샘플을 수집할 수 있는 모든 스키마에 explain_statement(...) 프로시저가 존재해야 해요.

explain plan을 수집하려는 모든 스키마에 이 프로시저를 만드세요. <YOUR_SCHEMA>를 데이터베이스 스키마로 바꾸세요.

DELIMITER $$
CREATE PROCEDURE <YOUR_SCHEMA>.explain_statement(IN query TEXT)
    SQL SECURITY DEFINER
BEGIN
    SET @explain := CONCAT('EXPLAIN FORMAT=json ', query);
    PREPARE stmt FROM @explain;
    EXECUTE stmt;
    DEALLOCATE PREPARE stmt;
END $$
DELIMITER ;
GRANT EXECUTE ON PROCEDURE <YOUR_SCHEMA>.explain_statement TO datadog@'%';

에이전트가 지원되지 않는 버전으로 실행 중

에이전트가 7.61.0 이상 버전으로 실행 중인지 확인하세요. Datadog은 새 기능, 성능 개선, 보안 업데이트를 활용하기 위해 에이전트를 정기적으로 업데이트할 것을 권장합니다.

쿼리가 잘림 (Queries are truncated)

샘플 쿼리 텍스트 크기를 늘리는 방법은 잘린 쿼리 샘플에 대한 섹션을 참고하세요.

쿼리를 설명할 수 없음 (Query cannot be explained)

BEGIN, COMMIT, SHOW, USE, ALTER 같은 일부 쿼리는 데이터베이스에서 유효한 explain plan을 생성할 수 없어요. explain plan을 지원하는 쿼리는 SELECT, UPDATE, INSERT, DELETE, REPLACE뿐입니다.

쿼리가 비교적 빈도가 낮거나 빠르게 실행됨

쿼리가 데이터베이스 전체 실행 시간에서 유의미한 비중을 차지하지 않아 샘플링 대상으로 선택되지 않았을 수 있어요. 쿼리를 캡처하려면 샘플링 비율 높이기를 시도해 보세요.

쿼리 메트릭이 없음

쿼리 메트릭 데이터 누락을 진단하는 다음 단계를 따르기 전에 에이전트가 성공적으로 실행 중이고 에이전트 데이터 누락을 진단하는 단계를 따랐는지 확인하세요. 쿼리 메트릭 누락의 가능한 원인은 다음과 같습니다.

Prepared-statement 메트릭은 MariaDB 10.5.2 이상이 필요해요 (performance_schema.prepared_statements_instances). events_statements_summary_by_digest에서 나오는 쿼리 메트릭은 지원되는 모든 MariaDB 버전에서 수집됩니다.

performance_schema가 꺼져 있으면 쿼리 메트릭과 prepared-statement 메트릭 모두 수집되지 않아요. performance_schema가 활성화되어 있지 않은 섹션을 참고하세요.

인덱스 메트릭이 없음

에이전트가 다음 오류를 표시하면:

Error querying mysql.innodb_index_stats: (1142, "SELECT command denied to user 'datadog'@'172.20.0.5' for table 'innodb_index_stats'")

인덱스 메트릭을 수집하기 위해 datadog 사용자에게 SELECT 권한을 부여해 오류를 해결하세요.

GRANT SELECT ON mysql.innodb_index_stats TO datadog@'%';

`performance_schema`가 활성화되어 있지 않음

에이전트는 performance_schema 옵션이 활성화되어 있어야 해요. MySQL과 달리 MariaDB는 기본적으로 performance_schema를 활성화하지 않습니다. 활성화하는 방법은 설정 지침을 참고하세요.

블로킹 쿼리가 없거나 불완전함

블로킹 쿼리 수집이 꺼져 있음

블로킹 쿼리 수집은 기본적으로 꺼져 있어요. 인스턴스 구성에서 query_activity.collect_blocking_queries: true로 활성화하세요. 설정 지침의 PROCESS와 SELECT ON performance_schema.* 권한 외에 추가 부여는 필요하지 않아요.

MySQL 8.0보다 블로킹 쿼리 컬럼이 적음

MariaDB는 최신 버전에서도 항상 MySQL 5.7이 사용하는 동일하고 더 단순한 블로킹 쿼리 컬럼과 조인을 사용해요. MySQL 8.0에서 사용 가능한 더 풍부한 블로킹 쿼리 컬럼은 MariaDB에서 사용할 수 없어요.

교착 상태(deadlock) 수가 평평하게 보임

교착 상태 수는 MariaDB에서 업데이트되지 않아요. 실제로 데이터베이스에서 교착 상태가 발생해도 교착 상태 메트릭은 0으로 유지될 수 있어요.

특정 쿼리가 없음

일부 쿼리의 데이터는 있는데 Database Monitoring에서 특정 쿼리나 쿼리 집합이 보이길 기대한다면 이 가이드를 따르세요.

가능한 원인	해결 방법
쿼리가 "top query"가 아님. 즉 선택한 시간대의 어느 시점에서도 총 실행 시간 합계가 상위 200개 정규화된 쿼리에 들지 않음.	"Other Queries" 행으로 그룹화되었을 수 있어요. 어떤 쿼리가 추적되는지에 대한 자세한 내용은 수집된 데이터 (Data Collected)를 참고하세요. 추적되는 상위 쿼리 수는 Datadog 지원팀에 문의해 늘릴 수 있어요.
`events_statements_summary_by_digest`가 가득 찼을 수 있음.	`performance_schema`의 MariaDB 테이블 `events_statements_summary_by_digest`는 저장하는 digest(정규화된 쿼리) 수에 최대 제한이 있어요. 유지 관리 작업으로 이 테이블을 정기적으로 잘라내면 시간이 지나며 모든 쿼리를 추적하는 데 도움이 돼요. 자세한 내용은 고급 설정 (Advanced configuration)을 참고하세요.
에이전트를 마지막으로 재시작한 뒤 쿼리가 한 번만 실행됨.	쿼리 메트릭은 에이전트가 재시작된 뒤 두 개의 서로 다른 10초 구간에서 쿼리가 최소 한 번 이상 실행된 후에만 내보내져요.

쿼리 샘플이 잘림

더 긴 쿼리는 데이터베이스 구성 때문에 전체 SQL 텍스트가 표시되지 않을 수 있어요. 워크로드에 맞게 약간의 튜닝이 필요해요.

Datadog Agent에 보이는 MariaDB SQL 텍스트 길이는 다음 시스템 변수로 결정됩니다.

max_digest_length=4096
performance_schema_max_digest_length=4096
performance_schema_max_sql_text_length=4096

쿼리 활동이 없음

쿼리 활동 누락을 진단하는 다음 단계를 따르기 전에 에이전트가 성공적으로 실행 중이고 에이전트 데이터 누락을 진단하는 단계를 따랐는지 확인하세요. 쿼리 활동 누락의 가능한 원인은 다음과 같습니다.

`performance-schema-consumer-events-waits-current`가 활성화되어 있지 않음

에이전트는 performance-schema-consumer-events-waits-current 옵션이 활성화되어 있어야 해요. 기본적으로 꺼져 있어요. 활성화하는 방법은 설정 지침을 참고하세요. 또는 데이터베이스를 재시작하지 않으려면 런타임 설정 컨슈머를 설정하는 방법도 고려해 보세요. 에이전트가 런타임에 performance_schema.events_* 컨슈머를 활성화할 수 있도록 다음 프로시저를 만드세요.

DELIMITER $$
CREATE PROCEDURE datadog.enable_events_statements_consumers()
    SQL SECURITY DEFINER
BEGIN
    UPDATE performance_schema.setup_consumers SET enabled='YES' WHERE name LIKE 'events_statements_%';
    UPDATE performance_schema.setup_consumers SET enabled='YES' WHERE name = 'events_waits_current';
END $$
DELIMITER ;
GRANT EXECUTE ON PROCEDURE datadog.enable_events_statements_consumers TO datadog@'%';

참고: 이 옵션은 추가로 performance_schema가 활성화되어 있어야 해요.

수집된 스키마에서 테이블이 없음

에이전트가 다음과 같이 시작하는 경고를 기록하면:

No tables were found across any of the N databases.

MariaDB는 해당 테이블에 대한 권한을 가진 사용자에게만 INFORMATION_SCHEMA의 테이블을 노출하므로, 권한이 없는 datadog 사용자는 아무 테이블도 보지 못해요. REFERENCES 권한을 부여하면 에이전트에게 데이터를 읽을 능력 없이 테이블 메타데이터를 볼 수 있게 해 주므로 이 경고를 해결할 수 있어요.

GRANT REFERENCES ON *.* TO datadog@'%';

자세한 내용은 스키마 수집 (Collecting schemas)을 참고하세요.

MariaDB 쿼리 메트릭 및 샘플에서 스키마 또는 데이터베이스가 없음

schema 태그("database"라고도 함)는 쿼리를 만든 연결에 기본 데이터베이스(Default Database)가 설정된 경우에만 MariaDB 쿼리 메트릭과 샘플에 표시돼요. 기본 데이터베이스는 애플리케이션이 데이터베이스 연결 파라미터에 "schema"를 지정하거나, 기존 연결에서 USE Statement를 실행해 설정합니다.

연결에 기본 데이터베이스가 구성되어 있지 않으면, 그 연결이 만든 어떤 쿼리에도 schema 태그가 없어요.

MariaDB 알려진 제한 사항

MariaDB는 동일한 MySQL 통합으로 모니터링되며, 메트릭과 이벤트는 MySQL 데이터와 구분하기 위해 dbms_flavor:mariadb로 태그가 지정돼요. 다음 기능은 MySQL과 다르거나 MariaDB에서 지원되지 않아요.

호환되지 않는 InnoDB 메트릭

다음 InnoDB 메트릭은 특정 MariaDB 버전에서 사용할 수 없어요.

메트릭 이름	MariaDB 버전
`mysql.innodb.hash_index_cells_total`	10.5, 10.6, 10.11, 11.4
`mysql.innodb.hash_index_cells_used`	10.5, 10.6, 10.11, 11.4
`mysql.innodb.os_log_fsyncs`	10.11, 11.4
`mysql.innodb.os_log_pending_fsyncs`	10.11, 11.4
`mysql.innodb.os_log_pending_writes`	10.11, 11.4
`mysql.innodb.pending_log_flushes`	10.11, 11.4
`mysql.innodb.pending_log_writes`	10.5, 10.6, 10.11, 11.4
`mysql.innodb.pending_normal_aio_reads`	10.5, 10.6, 10.11, 11.4
`mysql.innodb.pending_normal_aio_writes`	10.5, 10.6, 10.11, 11.4
`mysql.innodb.rows_deleted`	10.11, 11.4
`mysql.innodb.rows_inserted`	10.11, 11.4
`mysql.innodb.rows_updated`	10.11, 11.4
`mysql.innodb.rows_read`	10.11, 11.4
`mysql.innodb.s_lock_os_waits`	10.6, 10.11, 11.4
`mysql.innodb.s_lock_spin_rounds`	10.6, 10.11, 11.4
`mysql.innodb.s_lock_spin_waits`	10.6, 10.11, 11.4
`mysql.innodb.x_lock_os_waits`	10.6, 10.11, 11.4
`mysql.innodb.x_lock_spin_rounds`	10.6, 10.11, 11.4
`mysql.innodb.x_lock_spin_waits`	10.6, 10.11, 11.4

MariaDB explain plan

MariaDB는 explain plan에 대해 MySQL과 동일한 JSON 형식을 생성하지 않아요. cost_info, rows_examined_per_scan, rows_produced_per_join, used_columns를 포함한 일부 explain plan 필드가 MariaDB explain plan에서 누락될 수 있어요. explain plan 수집 자체는 MySQL과 동일하게 동작하지만, 이러한 필드를 사용하는 계획 시각화는 MariaDB 쿼리에 대해 덜 상세할 수 있어요.

`mysql.performance.errors_raised`가 수집되지 않음

이 메트릭은 MySQL 8.0 이상에서만 수집되며 MariaDB에서는 사용할 수 없어요.

기능적 인덱스가 스키마 메타데이터에 반영되지 않음

MariaDB는 기능적 인덱스를 지원하지 않아요. 인덱스 메타데이터 수집은 항상 MySQL 8.0.13 이상에서 사용할 수 있는 추가 표현식 정보 없이 일반 인덱스 쿼리를 사용합니다.

클러스터 태그가 지원되지 않음

클러스터 태그는 MariaDB에서 수집되지 않아요.