본문 바로가기
WIKI 기술 지식 베이스

ClickHouse Cloud용 Database Monitoring 설정하기

원문 보기 위키 갱신

이 기능은 프리뷰(preview) 상태이며 Datadog Agent v7.78 이상이 필요해요. Datadog Database Monitoring for ClickHouse 프리뷰에 참여하는 고객은 프리뷰 기간 동안 발생한 사용량에 대해 요금이 부과되지 않아요. 추가 활성화는 필요하지 않으며, 아래 설정 지침을 따라 시작하세요.

출처: 문서

본문

ClickHouse용 Datadog Database Monitoring (DBM)은 쿼리 메트릭, 실시간 쿼리 샘플, 완료된 쿼리 레코드를 수집해 ClickHouse Cloud 서비스에 대한 깊은 가시성을 제공해요. 이를 통해 플릿 전체의 문제를 해결하고 쿼리 성능을 최적화할 수 있어요.

시작하기 전에

지원되는 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 SHOW 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 권한은 파츠와 병합(스토리지 상태) 수집에 필요해요. SHOW 권한은 데이터베이스 이름, 테이블 이름, 컬럼, 뷰 같은 메타데이터를 자동으로 발견하는 데 필요해요. 나머지 권한은 핵심 ClickHouse 인프라 메트릭 수집을 가능하게 해요.

크로스-복제본 쿼리를 허용하도록 REMOTE 권한을 부여하세요:

GRANT REMOTE ON *.* TO datadog;

REMOTE 권한은 에이전트가 ClickHouse의 clusterAllReplicas() 테이블 함수를 사용해 단일 엔드포인트를 통해 ClickHouse Cloud 서비스의 모든 복제본에 걸쳐 데이터를 집계하기 때문에 필요해요. 이 권한은 크로스-노드 쿼리 실행을 가능하게 해요 — 위에서 명시적으로 부여한 것 외의 추가 데이터베이스나 테이블에 대한 접근을 부여하지는 않아요. ON *.* 구문은 이 권한 유형에 대한 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단계: 에이전트 구성

ClickHouse Cloud의 경우 에이전트는 서비스 엔드포인트에 직접 연결해요. 데이터는 개별 노드가 아니라 서비스 수준(모든 복제본에 걸쳐 집계)에서 수집돼요.

자동 일시 중단(auto-suspend)이 활성화된 서버리스 ClickHouse 배포에서는 DBM 수집 활동이 유휴 시간 동안 클러스터가 일시 중단되는 것을 막아 청구에 영향을 줄 수 있어요.

이 통합은 ClickHouse HTTP 인터페이스(포트 8443)를 사용하며, 기본 TCP 프로토콜(포트 9440)을 사용하지 않아요.

# /etc/datadog-agent/conf.d/clickhouse.d/conf.yaml

init_config:

instances:
  - dbm: true
    server: xyz.us-east-2.aws.clickhouse.cloud
    port: 8443
    username: datadog
    password: <PASSWORD>

    # Required for ClickHouse Cloud
    tls_verify: true
    verify: true
    single_endpoint_mode: true

    tags:
      - env:production
      - deployment:cloud

    query_metrics:
      enabled: true
      collection_interval: 10

    query_samples:
      enabled: true
      collection_interval: 1

    query_completions:
      enabled: true
      collection_interval: 10

single_endpoint_mode: true는 ClickHouse Cloud에 필요해요. 단일 엔드포인트 뒤의 모든 노드에 걸쳐 데이터를 수집하는 clusterAllReplicas() 쿼리를 활성화해요.

활성화하면 에이저트는 clusterAllReplicas()를 사용해 엔드포인트 뒤의 모든 노드에서 시스템 테이블 메트릭(system.events, system.metrics, system.asynchronous_metrics, system.errors)을 쿼리해요. 각 결과 시리즈는 clickhouse_node로 태그되어 노드별 데이터를 구분할 수 있어요. 이 노드별 수집은 Agent 버전 7.83.0 이상이 필요해요.

이 설정이 없으면 에이전트는 각 수집 주기에 다른 노드에 도달할 수 있어요. clickhouse.query.failed.count 같은 누적 노드별 카운터의 경우 그 불일치로 인해 카운터가 매번 같은 소스에서 읽히지 않아 부정확한 값이 생성돼요.

데이터베이스 식별자 사용자 정의하기

database_identifier 옵션은 데이터베이스 인스턴스가 DBM에 나타나는 방식을 제어해요. Datadog는 식별과 그룹화를 위해 서비스 이름을 사용자 정의 태그로 사용할 것을 권장해요.

instances:
  - dbm: true
    server: xyz.us-east-2.aws.clickhouse.cloud
    port: 8443
    # ... other settings ...

    database_identifier:
      template: "$env-$server:$port"

    tags:
      - env:production
      - service_name:user-service

env:production, server: xyz.us-east-2.aws.clickhouse.cloud, port: 8443을 사용하면 다음이 생성돼요:

템플릿 결과
$server:$port (기본) xyz.us-east-2.aws.clickhouse.cloud:8443
$env-$server:$port production-xyz.us-east-2.aws.clickhouse.cloud:8443

구성 참고 (Configuration reference)

연결 설정 (Connection settings)

필드 유형 필수 기본값 설명
server string Yes - ClickHouse Cloud 서비스 호스트명 (예: xyz.us-east-2.aws.clickhouse.cloud).
port integer No 8123 HTTP 포트. ClickHouse Cloud에는 8443(HTTPS)을 사용하세요.
username string No default 에이전트가 인증하는 ClickHouse 사용자 계정. Datadog는 제한된 권한을 가진 전용 datadog 사용자를 권장해요.
password string No - 지정된 사용자의 비밀번호.
db string No default 연결할 데이터베이스. 대부분의 메트릭이 시스템 테이블에서 오므로 보통 default가 적절해요.

TLS 설정

필드 유형 기본값 설명
tls_verify Boolean false TLS 활성화. ClickHouse Cloud에 필요해요.
verify Boolean true 서버의 SSL 인증서 검증. 프로덕션에서 false로 설정하는 것은 보안 위험이에요.
tls_ca_cert string - 사용자 정의 CA 인증서 파일 경로. 공용 CA의 인증서를 사용하는 ClickHouse Cloud에는 필요하지 않아요.

DBM 설정

필드 유형 기본값 설명
dbm Boolean false Database Monitoring 활성화. 쿼리 메트릭, 샘플, 완료 수집에 필요해요.
single_endpoint_mode Boolean false ClickHouse Cloud에 필요해요. 단일 엔드포인트 뒤의 모든 노드에 걸쳐 데이터를 수집하는 clusterAllReplicas() 쿼리를 활성화해요. 또한 표준 시스템 테이블 메트릭을 노드별(재 clickhouse_node 태그)로 수집해 누적 카운터가 정확한 노드별 값을 보고하도록 해요. 노드별 수집은 Agent 버전 7.83.0 이상이 필요해요.

데이터베이스 식별자

필드 유형 기본값 설명
database_identifier.template string $server:$port 고유 데이터베이스 식별자에 대한 템플릿. 변수 지원: $server, $port, 그리고 모든 사용자 정의 태그 키(예: $env, $service_name).

쿼리 메트릭

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 실행당 수집되는 최대 플러시 레코드 수.

더 알아보기 (Learn more)