셀프 호스팅 Langfuse, SigNoz, ClickStack의 ClickHouse®를 위한 읽기 전용 디스크 점검

디스크는 가득 차는데, 실제로 저장한 데이터는 많지 않습니다. 대개 공간을 차지하는 것은 ClickHouse 자체의 시스템 로그 테이블(system log tables)이며, 이 테이블에는 기본적으로 크기 제한이 없습니다. diskvet은 디스크를 무엇이 차지하고 있는지 보여 주고, 해결에 필요한 정확한 명령을 출력합니다. 자동으로 실행되는 것은 없으며, 명령은 모두 직접 실행합니다.

빠른 시작 직접 해결하기: 가이드 GitHub

무료이며 Apache-2.0 라이선스로 제공되고, 가입도 필요 없습니다. 짧은 파일 두 개뿐이라 실행하기 전에 내용을 읽어 볼 수 있습니다. 스크립트는 사용 중인 ClickHouse와만 통신하며, 다른 곳으로는 아무것도 보내지 않습니다.

흔히 겪는 사례

  • system.trace_log는 66.86 GiB인데 Langfuse 테이블은 약 51 MiB인 경우(langfuse#13123)
  • 시스템 로그 테이블은 80 GB가 넘는데 텔레메트리 데이터는 500 MB도 안 되는 경우(SigNoz#12050)
  • 10 Gi 볼륨이 10일 만에 가득 찬 경우(ClickStack-helm-charts#275)

주요 해결 방법은 이미 알려져 있습니다. 시스템 로그 테이블을 TRUNCATE하고 TTL을 설정하는 것입니다. 보고서는 이 방법을 실제로 적용할 때 빠지기 쉬운 함정도 함께 다룹니다. TRUNCATE의 50 GB 제한, 재시작 후 남는 오래된 *_log_N 사본, opentelemetry_span_log의 특수한 설정, 로테이션되지 않는 Docker 로그, 삭제된 뒤에도 공간을 계속 차지하는 행입니다.

빠른 시작: docker compose로 실행하는 Langfuse(30초)

Langfuse를 docker-compose.yml로 운영하는 머신에서 다음 명령을 실행합니다.

cd langfuse                     # Langfuse의 docker-compose.yml이 있는 폴더
curl -fsSLO https://github.com/Protemir/diskvet/releases/latest/download/diskvet.sh
curl -fsSLO https://github.com/Protemir/diskvet/releases/latest/download/checks.sql
curl -fsSLO https://github.com/Protemir/diskvet/releases/latest/download/SHA256SUMS
sha256sum -c SHA256SUMS         # 선택 사항: 두 파일이 릴리스와 일치하는지 확인
less checks.sql                 # 먼저 읽어 보기: system.*에 대한 SELECT만 있음

sh diskvet.sh report --docker auto > report.md

--docker auto는 ClickHouse 컨테이너를 자동으로 찾아 그 안에서 clickhouse-client를 실행합니다. 따라서 호스트에 클라이언트를 설치할 필요도, 포트를 열 필요도 없습니다. --user를 지정하지 않으면 컨테이너 자체의 CLICKHOUSE_USER / CLICKHOUSE_PASSWORD를 사용하므로, 비밀번호가 컨테이너 밖으로 나가지 않습니다.

그 밖의 연결 방법:

sh diskvet.sh report --docker signoz-clickhouse                          # 이름으로 컨테이너 지정
sh diskvet.sh report --host 127.0.0.1 --user diskvet --password '...'   # 로컬 clickhouse-client

POSIX sh, awk, sed, od, date와 함께 docker 또는 clickhouse-client가 필요합니다. jq나 Python은 필요 없습니다. 스크립트가 출력하는 보고서는 영어입니다. 최신 릴리스는 GitHub Releases에서 받을 수 있습니다.

점검 항목

#점검조회 대상보고서에 나오는 대표적인 해결 방법
1TTL이 없는 시스템 로그 테이블system.tables, system.partsTRUNCATE(50 GB를 넘으면 일회용 플래그 파일과 함께 사용), 보고서가 생성하는 config.d용 TTL 설정 파일, 삭제할 오래된 *_log_N 사본
2ClickHouse 테이블 파트(part) 밖의 디스크 사용량system.disks와 전체 파트 비교Docker 로그 로테이션과 그 밖에 확인할 곳
3디스크 사용량과 대략적인 예측system.disks, system.asynchronous_metric_log우선 정리할 대상
4일일 증가량system.part_log24시간 동안 가장 많은 데이터를 쓴 테이블
5파트가 너무 많음system.parts, system.merge_tree_settings, system.events테이블의 삽입 제한까지 남은 여유
6비활성 파트(inactive part)와 분리된 파트(detached part)system.parts, system.detached_parts정리되지 않고 남은 파트, DROP DETACHED PART
7삭제된 행과 멈춘 뮤테이션(mutation)system.parts, system.mutations해당 파티션을 지정한 APPLY DELETED MASK, KILL MUTATION

각 점검 결과는 OK, INFO, WARN, CRITICAL 중 하나로 표시되며, 임계값은 README에 있습니다. 모든 해결 방법에는 안전성 수준과 재시작 필요 여부가 함께 표시됩니다. 쿼리가 실패한 점검은 이유와 함께 NOT_RUN으로 표시되며, 나머지 점검은 그대로 실행됩니다.

읽는 것과 절대 읽지 않는 것

읽는 것

  • 다음 시스템 테이블의 메타데이터: system.tables, system.parts, system.disks, system.detached_parts, system.merge_tree_settings, system.mutations, system.part_log, system.asynchronous_metric_log, system.asynchronous_metrics, system.events
  • 권한이 있으면 system.server_settings(max_table_size_to_drop만)
  • 세션이 읽기 전용인지 확인하는 쿼리 SELECT getSetting('readonly') 1회

절대 읽지 않는 것

  • 사용자 테이블의 행: 이 테이블을 FROM이나 JOIN으로 조회하지 않으며, 테이블 함수와 dictGet도 사용하지 않습니다. 테스트 스위트로 이를 검증합니다.
  • system.query_log, 쿼리 텍스트, 뮤테이션 명령, 오류 메시지

로컬 보고서에는 실제 데이터베이스 이름과 테이블 이름이 표시됩니다. 수정 명령을 실행하려면 이 이름이 필요하기 때문입니다. 보고서는 사용자의 머신 밖으로 나가지 않습니다.

안전하게 실행하는 두 가지 방법

  • 기존 사용자로 실행. 쿼리는 readonly=2와 제한(30초, 10,000행, 스레드 2개, 500 MB)을 적용한 상태로 실행됩니다. 서버가 이 사용자에게 읽기 전용 모드를 허용하지 않으면, 스크립트는 아무것도 실행하지 않고 멈춥니다.
  • 전용 사용자로 실행. 보안 검토가 필요한 경우에 적합합니다. 위의 시스템 테이블에만 최소한의 권한을 주고, 제품 데이터에는 접근할 수 없게 합니다. 정확한 SQL은 README에 있습니다.

공식 기본 이미지 clickhouse/clickhouse-server 24.1, 24.8, 25.12, 26.9에서 Langfuse 및 SigNoz와 비슷한 구성으로 테스트했습니다. 아직 테스트하지 않은 환경: 복제 클러스터, Kubernetes, 객체 스토리지 위의 디스크, macOS.

직접 해결하고 싶다면

셀프 호스팅 Langfuse와 SigNoz에서 ClickHouse 디스크가 가득 차는 이유와 해결 방법

문제를 확인하는 읽기 전용 쿼리 하나, 지금 바로 공간을 확보하는 방법, 알려진 함정을 피하면서 재발을 막는 방법을 정리했습니다. 가이드의 모든 명령은 ClickHouse 24.8, 25.12, 26.9에서 실제로 실행해 확인했습니다. 가이드를 따라 하는 데 diskvet은 필요 없습니다.

매시간 점검: 10월 무료 베타

스크립트는 무료이며 앞으로도 무료입니다. 하지만 한 번 실행한 결과만으로는 디스크가 실제로 언제 가득 찰지 알 수 없습니다. 그래서 지금 이 부분을 만들고 있습니다.

  • 매시간 스냅샷: sh diskvet.sh --print-payload가 출력하는 JSON 그대로이며, 그 밖의 내용은 포함하지 않습니다.
  • 디스크가 가득 차기 전에 보내는 이메일(상태가 바뀔 때만)
  • 스냅샷이 더 이상 도착하지 않을 때 보내는 알림
  • 매주 월요일에 보내는 짧은 보고서

사용자 측에서 무언가를 호스팅할 필요도, 포트를 열 필요도 없습니다. 서버가 서명된 작은 스냅샷을 밖으로 보낼 뿐, 외부에서 서버로 접속하는 일은 없습니다. 호스트 이름, IP 주소, 사용자 이름, 쿼리 텍스트, 오류는 절대 전송하지 않습니다. 사용자 테이블의 이름은 솔트를 적용한 해시로만 서버 밖으로 나갑니다.

참여하고 싶다면 “Early access” 스레드(토론 #1)에 ClickHouse를 어떤 환경에서 운영하는지와 디스크 크기가 대략 얼마인지 댓글로 남겨 주십시오. 한국어로 작성하셔도 되지만, 답변은 영어로 드릴 수도 있습니다. 베타가 열리면 그 스레드에서 답변을 드립니다. 공개 스레드이므로 회사 이름이나 호스트 이름은 적지 말아 주십시오.

베타는 30일 동안 진행됩니다. 이후 매시간 점검은 유료 플랜으로 바뀌지만, 스크립트는 계속 무료 오픈 소스로 유지됩니다. 카자흐스탄에 있는 서버는 당분간 로컬 보고서만 사용할 수 있습니다.

스크립트가 놓치는 문제나 잘못된 해결 방법을 발견했다면 이슈를 등록해 주십시오. 무엇보다 큰 도움이 됩니다. 한국어로 작성하셔도 되지만, 답변은 영어로 드릴 수도 있습니다.