자체 호스팅(Self-Hosted) ClickHouse용 Database Monitoring 설정하기
이 기능은 프리뷰(preview) 상태이며 Datadog Agent v7.78 이상이 필요해요. Datadog Database Monitoring for ClickHouse 프리뷰에 참여하는 고객은 프리뷰 기간 동안 발생한 사용량에 대해 요금이 부과되지 않아요. 추가 활성화는 필요하지 않으며, 아래 설정 지침을 따라 시작하세요.
출처: 문서
본문
ClickHouse용 Datadog Database Monitoring (DBM)은 쿼리 메트릭, 실시간 쿼리 샘플, 완료된 쿼리 레코드를 수집해 ClickHouse 클러스터에 대한 깊은 가시성을 제공해요. 이를 통해 플릿 전체의 문제를 해결하고 쿼리 성능을 최적화할 수 있어요.
시작하기 전에
지원되는 ClickHouse 버전: 23.x 이상 (23.x, 24.x, 25.x, 26.3). 권장 최소: 23.8 LTS. ClickHouse 26.3은 Agent 7.84+가 필요해요.
지원되는 Agent 버전: 7.78+
수집되는 데이터 (Data collected)
Database Monitoring은 ClickHouse에서 다음 데이터를 수집해요:
데이터베이스 인스턴스
버전, 호스트명, 구성을 포함한 인스턴스 정보를 주기적으로(5분마다) 수집해요. tags 옵션에 정의된 사용자 정의 태그가 인스턴스에 연결되어 환경, 리전, 클러스터 또는 기타 사용자 정의 차원으로 필터링하고 그룹화할 수 있어요.
쿼리 메트릭 (Query metrics)
실행된 쿼리에 대한 집계 성능 메트릭으로, 시간 경과에 따른 쿼리 동작과 추이를 분석할 수 있게 해줘요. system.query_log에서 수집돼요.
쿼리 샘플 (Query samples)
현재 실행 중인 쿼리의 시점 스냅샷을 1초 간격으로 system.processes에서 캡처해요. ClickHouse 쿼리는 종종 1초 미만에 완료되므로, 수명이 짧은 쿼리는 샘플에 항상 나타나지 않을 수 있어요.
쿼리 완료 (Query completions)
개별 완료 쿼리 실행의 레코드로, 성공적으로 실행된 모든 쿼리를 캡처해요. 쿼리 완료를 쿼리 샘플과 함께 사용하면 샘플링 중 관찰되지 않은 수명이 짧은 쿼리를 포함한 모든 쿼리 활동을 완전히 볼 수 있어요.
실행 계획 (Explain plans)
쿼리 완료에서 관찰된 쿼리가 참조하는 테이블에 대해 EXPLAIN을 실행해 수집하는 쿼리 실행 계획으로, 쿼리 성능을 진단하는 데 도움을 줘요. SELECT 문장(포함 WITH 쿼리)만 실행 계획 수집을 지원해요. 실행 계획을 포함한 모든 수집 데이터는 난독화돼요. 이 수집은 설정에서 설명한 시스템 테이블 접근 외에도 모니터링되는 쿼리가 참조하는 테이블에 대한 SELECT 접근이 필요해요.
파츠와 병합 (Parts and merges)
활성 파츠, 분리된 파츠, 백그라운드 병합, 보류 중인 변경(mutations), 복제 큐 깊이를 포함한 스토리지 상태 데이터로, system.parts, system.detached_parts, system.merges, system.mutations, system.replication_queue, system.merge_tree_settings에서 수집돼요. 병합 중단이나 증가하는 복제 백로그 같은 스토리지 및 복제 문제를 식별하는 데 도움을 줘요.
비동기 삽입 (Async inserts)
Agent 7.83 이상에서 사용 가능하며 기본적으로 비활성화된 비동기 삽입 활동이에요. system.asynchronous_inserts의 보류 중인 버퍼 스냅샷은 플러시를 기다리는 데이터 양과 각 버퍼가 플러시되도록 예약된 시점을 보여줘요. system.asynchronous_insert_log의 플러시 레코드는 각 플러시, 성공 여부, 쓴 바이트 수와 행 수를 보여줘요. 실패하는 플러시와 플러시보다 빠르게 커지는 버퍼를 식별하는 데 도움을 줘요.
설정 (Setup)
1단계: Datadog Agent 접근 권한 부여
전용 datadog 사용자를 만들어요:
CREATE USER datadog IDENTIFIED BY '<PASSWORD>';
시스템 테이블에 필요한 권한을 부여하세요:
GRANT SELECT ON system.metrics TO datadog;
GRANT SELECT ON system.events TO datadog;
GRANT SELECT ON system.asynchronous_metrics TO datadog;
GRANT SELECT ON system.errors TO datadog;
GRANT SELECT ON system.parts TO datadog;
GRANT SELECT ON system.replicas TO datadog;
GRANT SELECT ON system.dictionaries TO datadog;
GRANT SELECT ON system.macros TO datadog;
GRANT SELECT ON system.clusters TO datadog;
GRANT SELECT ON system.settings TO datadog;
GRANT SELECT ON system.table_engines TO datadog;
GRANT SELECT ON system.one TO datadog;
GRANT SELECT ON system.query_log TO datadog;
GRANT SELECT ON system.processes TO datadog;
GRANT SELECT ON system.detached_parts TO datadog;
GRANT SELECT ON system.merges TO datadog;
GRANT SELECT ON system.mutations TO datadog;
GRANT SELECT ON system.replication_queue TO datadog;
GRANT SELECT ON system.merge_tree_settings TO datadog;
GRANT REMOTE ON *.* TO datadog;
system.processes와 system.query_log 권한은 DBM 쿼리 수집에 필요해요. system.parts, system.detached_parts, system.merges, system.mutations, system.replication_queue, system.merge_tree_settings 권한은 파츠와 병합(스토리지 상태) 수집에 필요해요. system.macros, system.clusters, system.settings, system.table_engines, system.one 권한은 각 인스턴스의 클러스터, 호스팅 유형, 노드를 식별하는 데 필요해요. 나머지 권한은 핵심 ClickHouse 인프라 메트릭 수집을 가능하게 해요.
참고: 위 권한은 쿼리 메트릭, 쿼리 샘플, 쿼리 완료, 파츠와 병합 수집에 충분해요. 이는 에이전트에게 애플리케이션 데이터 접근을 부여하지 않아요.
선택 사항: 실행 계획 수집을 위한 접근 권한 부여
실행 계획 수집은 위의 시스템 테이블뿐 아니라 모니터링되는 쿼리가 참조하는 테이블에 대한 SELECT 접근이 필요해요:
GRANT SELECT ON <database>.* TO datadog;
이 권한이 제공되지 않으면 에이전트는 해당 테이블에 대한 쿼리에서 EXPLAIN을 실행할 수 없어요. 쿼리 메트릭, 샘플, 완료는 계속 작동하지만, 영향받은 쿼리에 대해 실행 계획이 수집되지 않고 Datadog는 해당 쿼리에 수집 오류를 표시해요.
선택 사항: 비동기 삽입 모니터링을 위한 접근 권한 부여
비동기 삽입 모니터링(Agent 7.83 이상)을 활성화한다면 비동기 삽입 시스템 테이블에 대한 접근을 부여하세요:
GRANT SELECT ON system.asynchronous_inserts TO datadog;
GRANT SELECT ON system.asynchronous_insert_log TO datadog;
system.asynchronous_inserts는 보류 중인 버퍼 스냅샷(collect_pending_async_inserts)에 필요해요. system.asynchronous_insert_log는 플러시 레코드(collect_async_inserts)에 필요해요. 둘 다 활성화하려면 인스턴스 구성에 다음을 추가하세요:
collect_pending_async_inserts:
enabled: true
collect_async_inserts:
enabled: true
2단계: 에이전트 구성
자체 호스팅 배포의 경우 Datadog Agent는 각 ClickHouse 노드에 개별적으로 연결해야 해요. 노드별로 별도의 instances 항목을 추가하세요. 하나의 에이전트가 같은 구성 파일에서 여러 인스턴스를 정의해 여러 노드를 모니터링할 수 있어요.
참고: 이 통합은 ClickHouse HTTP 인터페이스(포트 8123/8443)를 사용하며, 기본 TCP 프로토콜(포트 9000/9440)을 사용하지 않아요.
- HTTP (기본): 포트
8123 - HTTPS/TLS:
tls_verify: true와 함께 포트8443
# /etc/datadog-agent/conf.d/clickhouse.d/conf.yaml
init_config:
instances:
- dbm: true
server: clickhouse-node-01.example.com
port: 8123
username: datadog
password: <PASSWORD>
tags:
- env:production
- node:clickhouse-01
query_metrics:
enabled: true
collection_interval: 10
query_samples:
enabled: true
collection_interval: 1
query_completions:
enabled: true
collection_interval: 10
# Add an entry for each additional node
- dbm: true
server: clickhouse-node-02.example.com
port: 8123
username: datadog
password: <PASSWORD>
tags:
- env:production
- node:clickhouse-02
query_metrics:
enabled: true
collection_interval: 10
query_samples:
enabled: true
collection_interval: 1
query_completions:
enabled: true
collection_interval: 10
데이터베이스 식별자 사용자 정의하기
database_identifier 옵션은 데이터베이스 인스턴스가 DBM에 나타나는 방식을 제어해요. 기본 server:port 형식 대신 의미 있고 사람이 읽을 수 있는 식별자를 원할 때 유용해요.
instances:
- dbm: true
server: clickhouse-01
port: 8123
# ... other settings ...
database_identifier:
template: "$env-$server:$port"
tags:
- env:production
env:production, server: clickhouse-01, port: 8123을 사용하면 다음이 생성돼요:
| 템플릿 | 결과 |
|---|---|
$server:$port (기본) |
clickhouse-01:8123 |
$env-$server:$port |
production-clickhouse-01:8123 |
구성 참고 (Configuration reference)
연결 설정 (Connection settings)
| 필드 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
server |
string | Yes | - | ClickHouse 서버의 호스트명 또는 IP 주소. |
port |
integer | No | 8123 |
HTTP 포트. HTTPS/TLS에는 8443을 사용하세요. 에이전트는 기본 TCP 프로토콜(포트 9000)이 아니라 HTTP 인터페이스를 사용해요. |
username |
string | No | default |
에이전트가 인증하는 ClickHouse 사용자 계정. Datadog는 제한된 권한을 가진 전용 datadog 사용자를 권장해요. |
password |
string | No | - | 지정된 사용자의 비밀번호. |
db |
string | No | default |
연결할 데이터베이스. 대부분의 메트릭이 시스템 테이블에서 오므로 보통 default가 적절해요. |
TLS 설정
| 필드 | 유형 | 기본값 | 설명 |
|---|---|---|---|
tls_verify |
Boolean | false |
TLS 활성화. HTTPS(포트 8443)를 사용할 때 true로 설정하세요. |
verify |
Boolean | true |
서버의 SSL 인증서 검증. 프로덕션에서 false로 설정하는 것은 보안 위험이에요. |
tls_ca_cert |
string | - | 사용자 정의 CA 인증서 파일 경로. ClickHouse가 내부 또는 자체 서명 인증서로 구성된 경우 사용하세요. |
DBM 설정
| 필드 | 유형 | 기본값 | 설명 |
|---|---|---|---|
dbm |
Boolean | false |
Database Monitoring 활성화. 쿼리 메트릭, 샘플, 완료 수집에 필요해요. |
데이터베이스 식별자
| 필드 | 유형 | 기본값 | 설명 |
|---|---|---|---|
database_identifier.template |
string | $server:$port |
고유 데이터베이스 식별자에 대한 템플릿. 변수 지원: $server, $port, 그리고 모든 사용자 정의 태그 키(예: $env, $region). 환경 간에 인스턴스를 구분하려면 사용자 정의 태그를 사용하세요: $env-$server:$port. |
쿼리 메트릭
system.query_log에서 집계 쿼리 통계를 수집해요.
| 필드 | 유형 | 기본값 | 설명 |
|---|---|---|---|
query_metrics.enabled |
Boolean | true |
쿼리 메트릭 수집 활성화. dbm: true 필요. |
query_metrics.collection_interval |
number | 10 |
수집 간격(초). |
쿼리 샘플
system.processes에서 현재 실행 중인 쿼리를 수집해요.
| 필드 | 유형 | 기본값 | 설명 |
|---|---|---|---|
query_samples.enabled |
Boolean | true |
쿼리 샘플 수집 활성화. dbm: true 필요. |
query_samples.collection_interval |
number | 1 |
수집 간격(초). |
query_samples.payload_row_limit |
integer | 1000 |
스냅샷당 최대 활성 쿼리 수. |
쿼리 완료
system.query_log에서 개별 완료 쿼리 레코드를 수집해요.
| 필드 | 유형 | 기본값 | 설명 |
|---|---|---|---|
query_completions.enabled |
Boolean | true |
쿼리 완료 수집 활성화. dbm: true 필요. |
query_completions.collection_interval |
number | 10 |
수집 간격(초). |
query_completions.samples_per_hour_per_query |
number | 15 |
고유 쿼리 시그니처당 시간당 수집되는 최대 샘플 수. |
보류 중인 비동기 삽입
system.asynchronous_inserts에서 보류 중인 비동기 삽입 버퍼의 스냅샷을 수집해요. Agent 7.83 이상 필요.
| 필드 | 유형 | 기본값 | 설명 |
|---|---|---|---|
collect_pending_async_inserts.enabled |
Boolean | false |
보류 중인 비동기 삽입 버퍼 수집 활성화. dbm: true 필요. |
collect_pending_async_inserts.collection_interval |
number | 10 |
수집 간격(초). |
collect_pending_async_inserts.max_samples_per_collection |
integer | 1000 |
실행당 수집되는 최대 버퍼 수. |
비동기 삽입 플러시
system.asynchronous_insert_log에서 개별 비동기 삽입 플러시 레코드를 수집해요. Agent 7.83 이상 필요.
| 필드 | 유형 | 기본값 | 설명 |
|---|---|---|---|
collect_async_inserts.enabled |
Boolean | false |
비동기 삽입 플러시 수집 활성화. dbm: true 필요. |
collect_async_inserts.collection_interval |
number | 60 |
수집 간격(초). |
collect_async_inserts.max_samples_per_collection |
integer | 1000 |
실행당 수집되는 최대 플러시 레코드 수. |