HyperDX / ClickStack 소개

ClickStack의 오픈데모는 아래에서 바로 사용해보실 수 있습니다.

HyperDX

play-clickstack.clickhouse.com

• 1. HyperDX 개요
• 2. 주요 특징
• 3. 로드맵
• 4. 아키텍처
• 5. OpenTelemetry Collector 상세
• 6. 스키마 구성의 이해
• 7. 사용 방법
• 8. 정리

1. HyperDX 개요

HyperDX는 ClickHouse와 OpenTelemetry를 기반으로 구축된 오픈소스 옵저버빌리티(Observability) 플랫폼입니다. 로그, 메트릭, 트레이스, 세션 리플레이, 에러를 단일 플랫폼에서 통합하여 관리할 수 있으며, 프로덕션 환경의 문제를 신속하게 진단하고 해결할 수 있도록 설계되었습니다.

HyperDX의 공동 창업자인 Michael Shi는 이전에 LogDNA(현 Mezmo)에서 개발자 경험 리드로 근무한 경력이 있으며, Y Combinator의 지원을 받아 2023년에 프로젝트를 시작했습니다.

HyperDX의 핵심 철학은 "모든 옵저버빌리티 데이터는 정보가 풍부한 Wide Event로 수집되어야 한다"는 것입니다. 이를 통해 로그, 트레이스, 메트릭, 세션 데이터를 데이터베이스 레벨에서 완전히 쿼리하고 상호 연관 분석할 수 있습니다.

HyperDX에서 ClickStack으로:

2025년 3월, ClickHouse가 HyperDX를 인수하면서 중요한 전환점을 맞이했습니다. 이후 HyperDX는 ClickStack이라는 통합 옵저버빌리티 스택의 핵심 UI 컴포넌트로 재포지셔닝되었습니다.

인수 배경: ClickHouse는 내부 옵저버빌리티 플랫폼 LogHouse(100+ 페타바이트 규모)를 운영하면서 Datadog에서 자체 솔루션으로 전환했습니다. 이 과정에서 HyperDX를 발견하고, 기존 ClickHouse 배포를 완전한 옵저버빌리티 플랫폼으로 쉽게 전환할 수 있음을 확인했습니다.

현재 명칭 정리:

• ClickStack: ClickHouse + OpenTelemetry Collector + HyperDX UI + MongoDB를 포함하는 전체 옵저버빌리티 스택
• HyperDX: ClickStack의 시각화/UI 레이어 (브랜드명은 유지)
• ClickStack OpenTelemetry Collector: ClickHouse 인제스트에 최적화된 커스텀 OTel Collector 배포판

2. 주요 특징

2.1 통합 옵저버빌리티

• 로그, 메트릭, 세션 리플레이, 트레이스를 한 곳에서 상관관계 분석 및 검색
• 브라우저 세션 리플레이부터 백엔드 로그와 트레이스까지 자동 연결
• 툴 간 이동 없이 엔드투엔드 문제 추적 가능

2.2 ClickHouse 최적화

• ClickHouse의 컬럼형 아키텍처와 네이티브 JSON 지원 활용
• 테라바이트 규모 이벤트를 초 단위로 검색
• 높은 카디널리티 워크로드의 효율적 처리
• 대규모 데이터셋에 대한 서브초 지연 시간 쿼리 제공

2.3 사용자 친화적 인터페이스

• 직관적인 전문 검색 및 속성 검색 구문 지원 (예: level:err)
• Lucene 스타일과 SQL 쿼리 모두 지원
• 복잡한 쿼리 언어 없이 고카디널리티 이벤트 대시보드 생성

2.4 스키마 독립적 설계

• 기존 ClickHouse 스키마 위에서 동작
• 사전 정의 없이 스키마 유연하게 진화 가능
• 커스텀 스키마에 UI 변경 없이 대응

2.5 OpenTelemetry 네이티브

• CNCF가 지원하는 벤더 중립 계측 표준 지원
• Python, Node.js, Go, Java 등 다양한 언어 지원
• 표준 기반 데이터 수집으로 벤더 종속성 방지

2.6 고급 분석 기능

• Log Patterns: 유사한 로그를 자동으로 클러스터링하여 트렌드 분석
• Event Deltas: 이상 징후 및 성능 회귀 식별을 위한 이벤트 차이 분석
• APM: HTTP 요청부터 DB 쿼리까지 건전성 및 성능 모니터링
• 실시간 테일: 항상 최신 이벤트를 확인할 수 있는 로그/트레이스 라이브 테일

3. 로드맵

3.1 ClickHouse 인수 이후 방향성

핵심 원칙:

• 표준 기반 데이터 수집: OpenTelemetry에 대한 공동 투자 (ClickHouse가 OpenTelemetry Exporter 유지보수)
• 오픈소스 우선: 강력한 옵저버빌리티 스택을 누구나 사용할 수 있도록
• 유연한 데이터 접근: 옵저버빌리티 데이터에 대한 직접 접근과 다양한 분석 방법 제공

지속적 개발:

• HyperDX Cloud 서비스 계속 운영 및 신규 고객 온보딩
• 오픈소스 프로젝트 활발히 유지보수 및 개발
• 엔지니어를 위한 더욱 강력한 옵저버빌리티 도구 확대

3.2 주요 업데이트 (2025년)

3.3 향후 예정 기능

• Exponential Histogram 메트릭 UI 지원
• 더 많은 SDK 통합
• 고급 알림 및 이상 탐지

4. 아키텍처

4.1 전체 아키텍처

4.2 핵심 컴포넌트

5. OpenTelemetry Collector 상세

5.1 배포 패턴

OpenTelemetry Collector는 두 가지 주요 역할로 배포됩니다:

Agent 역할

• 서버 또는 Kubernetes 노드의 엣지에서 데이터 수집
• 애플리케이션과 함께 실행 (Sidecar 또는 DaemonSet)
• 최소한의 처리만 수행 (타임스탬프 설정, 필터링, 로컬 enrichment)
• 권장: 공식 otelcol-contrib 배포판 사용

Gateway 역할

• 클러스터/데이터센터/리전 당 하나의 독립 서비스
• 여러 Agent로부터 데이터를 OTLP 엔드포인트로 수신
• 배치 처리, 변환, ClickHouse 최적화 인제스트 담당
• 권장: ClickStack 배포판 사용

5.2 ClickStack OTel Collector 특징

ClickStack은 ClickHouse 인제스트에 최적화된 커스텀 OTel Collector 배포판을 제공합니다:

주요 특징:

• ClickHouse Exporter 내장
• OpAMP(Open Agent Management Protocol) 지원으로 보안 설정 관리
• HyperDX 앱에서 생성된 Ingestion API 키로 인증
• 최적화된 배치 삽입

리소스 요구사항 (벤치마크 기준):

• Gateway 인스턴스 (3코어, 12GB RAM): 약 60,000 이벤트/초 처리 가능
• 최소 처리 파이프라인 기준 (필드 이름 변경, 정규식 미사용)

5.3 Collector 파이프라인 구조

5.4 커스텀 Collector 설정

2025년 9월부터 ClickStack은 OTel Collector 설정 확장을 지원합니다:

# /etc/otelcol-contrib/custom.config.yaml
receivers:
  hostmetrics:
    collection_interval: 60s
    scrapers:
      cpu:
      memory:
      disk:
      network:

  filelog:
    include:
      - /var/log/*.log
    start_at: beginning

service:
  pipelines:
    metrics:
      receivers: [hostmetrics]
    logs:
      receivers: [filelog]

컨테이너에 마운트하여 사용:

docker run \
  -v "$(pwd)/custom.config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one

5.5 고가용성 아키텍처

대규모 환경에서는 Agent-Gateway 패턴과 함께 Kafka를 활용할 수 있습니다:

Kafka 활용 이점:

• 높은 전송 보장
• 데이터 리플레이 가능 (여러 대상으로)
• Gateway 장애 시 데이터 손실 방지

6. 스키마 구성의 이해

6.1 테이블 구조 개요

ClickStack OTel Collector는 데이터 유형별로 최적화된 테이블을 생성합니다:

6.2 로그 테이블 스키마 (otel_logs)

6.3 스키마 설계 핵심 포인트

Map 타입과 성능

Materialized Column 예시:

-- host.name을 루트 컬럼으로 Materialize
ALTER TABLE otel_traces
  ADD COLUMN HostName String MATERIALIZED ResourceAttributes['host.name'];
ALTER TABLE otel_traces MATERIALIZE COLUMN HostName;

Bloom Filter 인덱스

압축 코덱

6.4 JSON 스키마 vs Map 스키마

ClickStack은 두 가지 스키마 모드를 지원합니다:

JSON 스키마 활성화:

# Collector 환경 변수
OTEL_AGENT_FEATURE_GATE_ARG="--feature-gates=clickhouse.json"

# HyperDX 환경 변수
BETA_CH_OTEL_JSON_SCHEMA_ENABLED="true"

7. 사용 방법

7.1 오픈소스 (Self-Hosted)

빠른 시작:

docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one

포트 설명:

• 8080: HyperDX UI
• 4317: OpenTelemetry gRPC
• 4318: OpenTelemetry HTTP

애플리케이션 계측 (환경 변수):

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_SERVICE_NAME=my-service

7.2 ClickHouse Cloud

ClickHouse Cloud에서 HyperDX(ClickStack)를 사용하면:

• 인프라 관리 불필요
• ClickHouse Cloud 인증과 통합
• 단일 클릭 시작
• 스토리지/컴퓨트 완전 분리
• 자동 백업

활성화: 현재 Private Preview (조직 수준 활성화 필요)

8. 정리

8.1 핵심 가치

8.2 시작하기

리소스:

• 공식 문서: https://clickhouse.com/docs/use-cases/observability/clickstack
• GitHub: https://github.com/hyperdxio/hyperdx
• 라이브 데모: https://play.hyperdx.io
• Discord: HyperDX 커뮤니티

8.3 라이선스

• HyperDX UI: MIT License
• ClickHouse: Apache 2.0
• OpenTelemetry Collector: Apache 2.0