ClickStack: Clickhouse 기반 APM

Clickhouse는 근래 가장 핫한 데이터베이스 시스템 중 하나다.
요즘 APM 환경으로도 각광받고 있는데, 특히 대기업에서 많이 쓰더라.

Clickhouse는 다음과 같은 특장점이 있다.

1. 매우 높은 스토리지 저장 효율: 압축을 빡세게 하기 때문

2. 매우 높은 성능의 쿼리 성능: 대신 동시 쿼리 처리량이 적지만, APM 자체의 특성 때문에 상쇄됨

3. 나쁘지 않은 성능의 INSERT 처리량: 카산드라 같은 고성능 KV에 비할 바는 아니지만, async insert 등 버퍼링 기능을 사용하면 꽤 처리량이 좋음

4. 컬럼형 저장구조

5. 시계열 데이터에 유리함: 파티션키를 타임스탬프 기반으로 설계하면 효율적인 형태로 적재/조회가 가능

6. 단일 소스로 관리포인트 통일 가능 (Loki, Prometheus, Tempo 3개를 동시에 띄워서 관리해야하는 광기에서 벗어날 수 있음)

아키텍쳐

기본 구성요소는 심플한 편이다.
Clickhouse를 단일 스토리지로 사용하고, Otel 에이전트로 로그를 쏘고, HyperDX라는 대시보드로 로그를 보는 식이다.

매우 높은 처리량을 감당하기 위해서 앞단에 카프카 같은걸 붙이기도 하고, 스토리지 기반의 계층화 구성을 하기도 한다. 하지만 일단 가볍게 시작하기에는 이 정도로도 충분하다.

대시보드의 오피셜 선택지는 HyperDX인데, HyperDX 외에도 Grafana, Signoz를 대안으로 사용할 수 있다. 취향에 맞춰서 고르면 된다.
HyperDX는 clickhouse에서 인수해서 관리하는 중이고, Signoz는 평이 그렇게 좋진 못한 것 같더라. Grafana는 Clickhouse용 플러그인을 설치하면 붙일 수 있지만, 아주 특화되어있진 않다.
그래서 Grafana + HyperDx를 병행으로 사용하는 사례가 많은 것 같다.

참고로 HyperDX는 기본적으로 상태/설정 관리에 MongoDB를 쓰는 것이 기본값이다.

그리고 매우 높은 처리량과 비용 효율성을 원한다면, 이런 식으로 확장할 수 있다.

1. 쓰기 처리량 가드 계층: 카프카 같은 고성능 스토리지를 중간에 둬서 일단 clickhouse에 가해지는 순간 부하를 완화하고, batch insert를 효율적으로 할 수 있도록 한다.

2. 스토리지 효율성 계층: 오래된 로그를 S3 같은 저렴한 스토리지로 export하되, 이 또한 clickhouse를 통해서 조회할 수 있도록 한다. 읽을 때만 S3 비용이 나오고, 저장비용은 디스크에 비해 상대적으로 저렴하다.

Docker로 시작해보기 (단일 이미지)

가장 빠르게 시작하는 방법은 Clickhouse 조직에서 만들어놓은 단일 이미지를 사용하는 것이다.
하나의 이미지에 clickhouse, otel collector, hyperdx, mongodb를 다 말아놓은 구성이다.

그냥 빠르게 시작하길 원한다면 docker cli로 바로 시작하면 되고

docker run --name clickstack -p 8123:8123 -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest clickstack

조금 더 영속적으로, 커스텀하며 관리하길 원한다면 compose를 쓰면 된다.

services:
  clickstack:
    image: ${CLICKSTACK_IMAGE}
    container_name: clickstack
    restart: unless-stopped
    mem_limit: 12g # total memory ceiling for the all-in-one container
    environment:
      # Absolute base for post-login redirects. MUST match the external origin
      # users reach the UI on (scheme://host:port), e.g. behind a tunnel/proxy.
      # If unset it defaults to http://localhost:8080, which breaks login for
      # anyone not browsing from the host itself.
      - FRONTEND_URL=${FRONTEND_URL}
      - CLICKHOUSE_DEFAULT_PASSWORD=${CLICKHOUSE_DEFAULT_PASSWORD}
      - CLICKHOUSE_API_PASSWORD=${CLICKHOUSE_API_PASSWORD}
      - CLICKHOUSE_WORKER_PASSWORD=${CLICKHOUSE_WORKER_PASSWORD}
    ports:
      - "${HYPERDX_PORT}:8080" # HyperDX UI
      - "${OTLP_GRPC_PORT}:4317" # OTLP gRPC
      - "${OTLP_HTTP_PORT}:4318" # OTLP HTTP
      - "8123:8123" # ClickHouse HTTP
    volumes:
      - ch_data:/var/lib/clickhouse
      - ch_logs:/var/log/clickhouse-server
      - mongo_data:/data/db
      - ./clickhouse/config.d:/etc/clickhouse-server/config.d:ro
      - ./clickhouse/users.xml:/etc/clickhouse-server/users.xml:ro
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 60s

volumes:
  ch_data:
  ch_logs:
  mongo_data:

에러 없이 실행되면 잘 된 것이다.

Kubernetes로 시작하기 (v2)

쿠버를 쓴다면 좀 더 제대로 된 구성을 비교적 간편하게 세팅할 수 있다.
얘들 helm chart 버전 관리나 공식 문서 관리가 개판이라 그냥 따라서 latest로 받으면 터지는 상황이다. 항상 버전을 명시해야 한다.

# cert manager가 없다면 설치
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.20.3/cert-manager.yaml

# helm 초기화
helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts
helm repo add mongodb https://mongodb.github.io/helm-charts
helm repo update

# mongodb 설치 (hyperDX 상태 관리)
helm install mongodb-kubernetes-operator mongodb/mongodb-kubernetes \
    --set operator.watchNamespace=clickstack

# operator 설치
helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
   --create-namespace \
   -n clickhouse-operator-system \
    --version v0.0.6

operator가 잘 실행된다면, clickstack을 본격적으로 깔면 된다.

helm install my-clickstack clickstack/clickstack --version 2.1.1 -n clickstack --create-namespace

배포하고 나서 조금만 기다리면

이렇게 다 뜰 것이다.

그러면 이제 개별 service를 열거나 포트포워딩해서 붙여볼 수 있다.
대시보드가 app이라는 service이고, 로그 수집 엔드포인트는 otel-collector라는 service를 쓰면 된다.

kubectl port-forward -n clickstack svc/my-clickstack-app 3000:3000

상세한 것들은 스킵한다.

사용해보기

만약 Clickstack 프리셋을 통해 구성했다면, clickhouse에는 다음과 같은 기본 테이블이 구성될 것이다.

뭐가 많다.

그리고 HyperDX에 접속하면, 최초 회원가입 화면이 뜬다.

여기서 루트계정 만들면 된다.

만들고 로그인해서 들어가면 바로 그럴듯하게 꾸며진 화면이 뜰 것이다.

수집용 API Key도 여기서 볼 수 있다.

이걸 들고 Otel Collector에 쏘면 된다.

그리고 이런 식으로 메트릭과 Trace들이 가시화된다.
Grafana보단 Elastic APM(Kibana)에 가까운 스타일이다. 사전 구성이 그럴듯하게 되어있고, Grafana처럼 정신없이 조합하는 스타일은 아니다.

에이전트를 붙이는 것 자체는 표준 Otel 프로토콜을 따르면 된다. 결국 수집 계층이 Otel로 추상화되어있기 때문에, Grafana 스택을 쓰는 것과 큰 차이는 없다.
차이가 벌어지는 부분은 clickhouse에 대한 운영 스킬일 것이다.

로그 & 트레이스 수집

간단하게 수집을 해보려면 INGESTION Key를 들고 Otel Collector에 찔러보는 것이 빠르다.
이건 Trace를 하나. 쌓는다.

KEY=키값

curl -s -w '\nHTTP=%{http_code}\n' -X POST http://localhost:4318/v1/traces \
  -H "authorization: $KEY" -H 'content-type: application/json' \
  -d "{\"resourceSpans\":[{\"resource\":{\"attributes\":[{\"key\":\"service.name\",\"value\":{\"stringValue\":\"probe-real\"}}]},\"scopeSpans\":[{\"spans\":[{\"traceId\":\
"5b8efff798038103d269b633813fc60c\",\"spanId\":\"eee19b7ec3c1b174\",\"name\":\"probe\",\"kind\":1,\"startTimeUnixNano\":\"${NOW}\",\"endTimeUnixNano\":\"${END}\"}]}]}]}"

그럼 이런 식으로 쌓이고 가시화가 된다.

이후에는 Otel 환경을 사용해서 언어에 맞게 에이전트를 구현하면 된다.

로그도 수집하면 이런 식으로 쌓인다.

대시보드 깎기

원한다면 Grafana처럼 Tile을 하나하나 붙여서 커스텀 대시보드를 만들 수 있다.
사용법은 대충 비슷하다.

대시보드에 Tile들을 정의해서 넣고, 레이아웃을 원하는대로 배치할 수 있다.

로그는 이런 식으로 간단하게 붙일 수 있다. Search Tile이 가장 적절한 것 같다. 시계열로 보여준다.

로그 베이스로 로그 레벨별 카운트를 보여주고 싶다면, 이런 식으로 구성할 수 있다.
group by 절만 대응되는 것으로 넣어주면 된다.

메트릭은 적재되어있는 지표 중에 적절히 골라서 차트로 넣으면 된다. 대체로 Average가 부합한다.

커스텀 필터도 적용 가능하다. 만약 'environment'라는 커스텀 속성을 추가했고, 이를 기반으로 한 필터 버튼이 필요하다면 이렇게 추가하면 된다.

그럼 이렇게 잘 걸릴 것이다.

꾸미기

Tile의 Display 세팅을 건드리면 이런저런 조정이 가능하다.
대표적인 것은 숫자 단위 표기다.

숫자를 표시할 때 어떤 단위로 표시할지를 정할 수 있다.

예를 들어 Data로 하면

바이트 단위계로 변환해준다. 아마 이걸 제일 자주 쓰지 않을까 싶다.

그리고 그룹을 사용하면 Tile들을 묶어서 깔끔하게 관리해줄 수 있다.

TTL 기반의 로그 만료 설정

원한다면 이것도 TTL 기반으로 로그를 제거하거나, 스토리지 계층으로 옮길 수 있다.
로그를 오래 보관할 필요가 없다면 TTL 제거만으로도 충분할 것이다.

-- 30-day retention for ClickStack telemetry.
-- ttl_only_drop_parts drops whole expired parts (lower merge overhead).
ALTER TABLE default.otel_logs   MODIFY SETTING ttl_only_drop_parts = 1;
ALTER TABLE default.otel_logs   MODIFY TTL Timestamp + toIntervalDay(30);

ALTER TABLE default.otel_traces MODIFY SETTING ttl_only_drop_parts = 1;
ALTER TABLE default.otel_traces MODIFY TTL Timestamp + toIntervalDay(30);

ALTER TABLE default.otel_metrics_gauge                 MODIFY TTL TimeUnix + toIntervalDay(30);
ALTER TABLE default.otel_metrics_sum                   MODIFY TTL TimeUnix + toIntervalDay(30);
ALTER TABLE default.otel_metrics_histogram             MODIFY TTL TimeUnix + toIntervalDay(30);
ALTER TABLE default.otel_metrics_exponential_histogram MODIFY TTL TimeUnix + toIntervalDay(30);
ALTER TABLE default.otel_metrics_summary               MODIFY TTL TimeUnix + toIntervalDay(30);

그럴때는 이런 쿼리만 날려줘도 충분하다. clickhouse 내에서 30일까지만 보관하고 지운다.

다만, 디스크 크기 기준으로 rotation을 돌리는 것은 직접적으로 지원되지는 않는다.
그건 직접 구현해서 백그라운드로 돌려야 한다.

아쉬운 점들

당연하지만 모든 기술에는 맹점이 있고, 이 스택도 마찬가지다.

(오픈소스를 쓴다면) helm을 비롯한 패키징 수준이 그렇게 좋진 못하다. 열심히 만들고 있는 것 같긴 한데, 뭔가 좀 꼬름하다. 제대로 서비스 환경에서 쓰려면 결국 직접 깎아야하는 부분이 생길듯

대시보드 커스텀이 꽤 잘 되지만, Grafana처럼 대시보드를 라이브러리처럼 공유하고 다운받는 환경이 존재하진 않는다. 대신 기본적인 사용 흐름은 Kibana(Elastic APM)처럼 어느 정도 정의해서 제공한다.

Continuos Profiling에 대한 고려가 없다. 필요하다면 pyroscope 같은 데다 따로 저장하고 그걸 Grafana나 pyroscope 자체 대시보드로 시각화해야 한다.

참조
https://clickhouse.com/docs/use-cases/observability/clickstack/getting-started/oss?loc=clickstack-oss
https://github.com/ClickHouse/ClickStack-helm-charts
https://clickhouse.com/docs/use-cases/observability/clickstack/deployment/helm-v1
https://tech.kakaopay.com/post/pallas-v2-log-platform/
https://github.com/ClickHouse/clickhouse-operator