ClickStack 셀프호스팅 구조 잡기 — 작게 시작해서 복구 가능한 구성으로

ClickStack을 직접 운영하려고 하면 ClickHouse를 몇 대 둘지부터 고민하게 된다.

그보다 먼저 정할 것은 수집이 멈춰도 되는 시간과 잃어도 되는 데이터의 범위다.

홈랩에서 몇 시간 로그를 못 보는 것과, 서비스 장애 중에 원인 분석에 필요한 로그를 잃는 것은 부담이 다르다.

이 글은 소규모로 시작하는 구성과 장애에 대비한 확장안을 정리한 설계 글이다.

특정 처리량이나 무중단 동작을 실측한 구성으로 보장하는 글은 아니며, 서비스의 실제 수집량과 복구 요구에 맞춰 검증해야 한다.

작은 구성은 어디까지 줄일 수 있을까

기능을 확인하거나 중단을 감수할 수 있는 환경이라면 다음처럼 시작할 수 있다.

복제하지 않는 MergeTree 테이블을 쓰는 구성이라면 Keeper를 생략할 수 있다.

다만 선택한 배포 도구가 기본으로 복제 테이블을 만드는지는 확인해야 한다.

ReplicatedMergeTree를 사용하는데 서버가 한 대라는 이유만으로 Keeper를 끄는 것은 다른 문제다. 테이블 복제와 Keeper 의존성 

서비스별 저장 볼륨을 분리해도 모두 같은 물리 서버에 있다면 서버 장애는 함께 맞는다.

그래도 ClickHouse와 MongoDB의 데이터 위치, 백업 방법, 재시작 후 상태를 먼저 익히기에는 이해하기 쉬운 구성이다.

평가용 All-in-One 이미지와 서비스별로 분리하는 Docker Compose·Kubernetes 배포 방식은 공식 배포 문서에서 구분한다. ClickStack 배포 방식 

이미 Kubernetes를 운영하고 있다면 그 환경을 활용할 수 있다.

관측성 도구 하나를 올리기 위해 새 클러스터까지 운영해야 한다면, VM에서 서비스를 분리하는 구성의 비용도 함께 비교할 만하다.

장애 중에도 수집하려면

운영 데이터로 넓힐 때는 저장소 복제와 수집 경로를 함께 본다.

아래는 ClickHouse 1 shard · 2 replicas를 출발점으로 잡은 구성도다.

Shard는 데이터가 나뉘는 단위이고, replica는 같은 shard의 데이터 사본이다.

두 replica를 둔다고 저장할 수 있는 고유 데이터가 두 배가 되지는 않는다.

각 replica가 같은 데이터를 보관하므로 필요한 저장 공간도 사본 수에 맞춰 늘어난다. ClickHouse 복제 

Collector는 두 서버에 같은 데이터를 각각 보내는 대신, 정상 replica 중 하나로 전송하도록 연결 경로를 구성한다.

HyperDX의 조회도 장애가 난 replica를 피할 수 있도록 연결과 재시도를 검증해야 한다.

두 ClickHouse 서버는 서로 다른 노드에 두고, AZ 장애까지 고려한다면 AZ도 나눈다.

Keeper는 세 멤버를 서로 다른 장애 영역에 배치해 한 멤버가 빠져도 과반을 유지하도록 설계한다.

Keeper는 복제 진행과 메타데이터를 조정한다.

실제 로그 본문을 대신 저장하거나 Collector의 미전송 데이터를 보관하는 큐는 아니다. ClickHouse Keeper 

사본 두 벌이면 쓰기도 안전할까

복제는 기본적으로 비동기다.

한 서버가 쓰기에 성공했다고 응답한 시점에 다른 replica까지 같은 데이터가 도착했다고 단정할 수 없다.

insert_quorum을 사용하면 지정한 수의 replica에 기록되는 것을 기다리게 할 수 있다. insert_quorum 

두 replica에서 quorum을 2로 요구하면 하나가 멈췄을 때 새 쓰기가 성공할 수 없다.

한 replica 장애 중에도 두 사본 기록을 요구하려면 3 replicas · quorum 2 같은 구성을 검토하게 된다.

이 역시 실제 Collector의 INSERT 방식과 확인 응답 설정까지 맞춰야 하며, 단순히 replica 수만 바꿔서 수집 전체의 무손실을 보장할 수는 없다.

ClickHouse 앞에서 데이터가 사라지지 않게

ClickHouse를 복제해도 아직 ClickHouse에 도착하지 않은 데이터는 보호되지 않는다.

Collector가 메모리 큐만 사용하면 재시작할 때 미전송 데이터가 사라질 수 있다.

지속성이 필요한 경로에는 사용하는 exporter의 지원을 확인해 file_storage 기반 영속 큐와 영속 볼륨을 구성한다. OpenTelemetry Collector 복원력 

영속 큐도 무한하지 않다.

예를 들어 평균 수집량이 초당 2 MiB이고 저장소가 30분 멈출 수 있다면, 그 시간의 데이터만 약 3.5 GiB다.

이 값은 단순히 수집량과 시간을 곱한 가상 예제이며, 실제 큐 파일 크기에는 직렬화 방식과 여유 공간이 더 영향을 준다.

복구 후에는 평소 유입량보다 더 빠르게 전송할 수 있어야 쌓인 큐가 줄어든다.

더 긴 버퍼나 재처리가 필요하면 Kafka 같은 중간 저장소를 검토할 수 있지만, 작은 구성부터 반드시 추가할 요소는 아니다.

우선은 수신 실패, 큐 사용량, exporter 재시도, 최종 저장 지연을 함께 관찰하는 편이 낫다.

저장소는 단순하게 시작하기

이 글의 시작안은 ClickHouse 데이터를 영속 블록 볼륨에 두고, 보관 기간을 짧게 잡는 방식이다.

자주 조회하지 않는 데이터의 비중이 커졌을 때 S3 티어링을 추가로 검토한다.

S3로 오래된 데이터를 옮길 수 있어도, 읽기 지연과 요청 비용을 함께 봐야 한다.

그리고 티어링은 백업이 아니다.

테이블 삭제나 잘못된 TTL 정책에서 복구하려면 운영 데이터와 별도로 복원 가능한 백업이 필요하다. 스토리지 정책 , ClickHouse 백업 

Kubernetes의 PVC 역시 데이터 내구성을 자동으로 보장하지 않는다.

AWS EBS는 AZ에 묶이고, local PV는 해당 노드에 묶인다.

파드를 다른 노드에 다시 띄우는 것과 데이터가 그 노드에서 바로 사용 가능해지는 것은 구분해야 한다. Kubernetes 볼륨 , EBS 볼륨과 AZ 

로컬 NVMe를 선택한다면 노드와 디스크를 잃었을 때 다른 replica나 백업에서 데이터를 다시 채우는 시간까지 감당할 수 있어야 한다.

운영 가능한지 확인할 마지막 부분

ClickHouse가 살아 있어도 MongoDB 장애로 설정을 읽지 못하면 HyperDX 사용에 문제가 생긴다.

앱의 가용성도 필요하다면 지원되는 HyperDX 다중 인스턴스 구성과 MongoDB replica set, 접근 경로까지 함께 검증한다.

Collector도 여러 개를 띄우는 데서 끝나지 않는다.

수신 트래픽 분산, 인스턴스별 영속 큐, 메트릭 처리의 중복 여부를 사용하는 파이프라인 기준으로 확인해야 한다. Collector 확장 

UI와 수집 엔드포인트는 접근 경로를 나누고, ClickHouse·MongoDB·Keeper는 내부 네트워크에서만 접근하도록 구성한다.

브라우저 수집을 열어야 한다면 SDK에 들어가는 키를 관리자 비밀키처럼 취급할 수 없으므로, 수집 전용 권한과 요청량 제한을 따로 둔다.

설치할 때는 차트와 operator, ClickHouse 버전을 함께 고정한다.

2026-09-15의 공식 Helm 문서는 operator 설치와 ClickStack 설치를 나누는 v2.x 구성을 설명하므로, 이전 조사 자료의 values를 그대로 가져오기 전에 배포 세대부터 확인해야 한다.

같은 문서는 프로덕션에서 ClickHouse와 Collector를 별도로 관리하는 구성을 권장한다.

저장소와 수집기를 앱과 독립적으로 확장하고 변경할 수 있게 하려는 구성이다. 현재 Helm 배포 문서 

작게 시작할 때의 목표는 구성요소를 적게 유지하면서 데이터의 위치와 복구 방법을 아는 것이다.

그다음 잃을 수 없는 데이터와 견딜 수 있어야 하는 장애를 기준으로, 수집 큐와 복제·백업을 하나씩 보강하면 된다.