HyperDX

HyperDX

HyperDX는 ClickHouse 위에서 동작하는 오픈소스 관측성(observability) 플랫폼이에요. 로그(logs)와 트레이싱(traces), 세션 리플레이(session replays), 메트릭(metrics)을 한 곳에서 검색하고 시각화할 수 있게 해 줘서, "프로덕션이 왜 고장 났는지"를 빠르게 파악할 수 있게 도와줘요. ClickHouse 용 Kibana 같은 느낌이라고 생각하면 돼요. OpenTelemetry를 기본 지원하고, ClickStack의 핵심 컴포넌트로 동작하며, 기존 ClickHouse 스키마 위에서도 스키마에 얽매이지 않고 동작해요. HyperDX는 익명화된 사용 데이터를 수집하는데, USAGE_STATS_ENABLED 환경변수를 false로 설정하면 수집을 끌 수 있어요.

출처: 문서

본문

주요 기능

HyperDX는 한 곳에서 여러 관측성 데이터를 연결해서 볼 수 있도록 설계됐어요.

  • 🕵️ 로그, 메트릭, 세션 리플레이, 트레이스를 한 곳에서 상호 연관(상관)해서 검색해요
  • 📝 스키마에 얽매이지 않아서, 기존 ClickHouse 스키마 위에서도 바로 동작해요
  • 🔥 ClickHouse에 최적화된 초고속 검색과 시각화를 제공해요
  • 🔍 직관적인 전체 텍스트 검색과 속성 검색 문법을 지원해요 (예: level:err), SQL은 선택 사항이에요
  • 📊 이벤트 델타로 이상 징후의 추세를 분석해요
  • 🔔 몇 번의 클릭만으로 알림(alert)을 설정할 수 있어요
  • 📈 복잡한 쿼리 언어 없이 고카디널리티 이벤트를 대시보드로 만들 수 있어요
  • { 네이티브 JSON 문자열 쿼리를 지원해요
  • ⚡ 로그와 트레이스를 라이브 테일(live tail)로 보면서 가장 최신 이벤트를 항상 확인할 수 있어요
  • 🔭 OpenTelemetry를 기본 지원해요
  • ⏱️ HTTP 요청부터 DB 쿼리까지 성능과 상태를 모니터링할 수 있어요 (APM)

이 모든 데이터는 OpenTelemetry Collector를 통해 수집되고, ClickHouse에 저장돼요.

설치 (Spinning Up HyperDX)

HyperDX는 ClickHouse, HyperDX, OpenTelemetry Collector, MongoDB를 포함하는 ClickStack의 일부로 배포할 수 있어요. 가장 간단한 올인원 컨테이너 방식은 아래와 같아요.

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

실행 후에는 http://localhost:8080 에 접속해서 HyperDX UI를 사용할 수 있어요.

이미 존재하는 ClickHouse 인스턴스가 있거나, 로컬에서 단일 컨테이너를 쓰고 싶거나, 프로덕션 배포 방법이 궁금하다면 배포 문서에서 다양한 배포 옵션을 확인할 수 있어요.

방화벽 뒤에 서버를 두고 있다면, UI, API, OTel collector를 위해 각각 포트 8080, 8000, 4318을 열거나 포워딩해야 해요.

테스트 환경에는 최소 4GB RAM과 2코어를 권장해요.

Hosted ClickHouse Cloud

ClickHouse Cloud로도 HyperDX를 배포할 수 있어요. 무료로 가입하면 몇 분 안에 시작할 수 있어요.

앱 계측 (Instrumenting Your App)

로그, 메트릭, 트레이스, 세션 리플레이 데이터를 HyperDX로 보내려면 앱을 계측해서 텔레메트리 데이터를 HyperDX 인스턴스로 전송해야 해요. 브라우저, Node.js, Python용 SDK와 통합 옵션을 제공하고, 전체 목록은 공식 문서에서 확인할 수 있어요.

OpenTelemetry

HyperDX는 CNCF가 후원하는 벤더 중립 표준인 OpenTelemetry와 호환돼요. 지원되는 언어/플랫폼은 다음과 같아요.

  • Kubernetes
  • Javascript
  • Python
  • Java
  • Go
  • Ruby
  • PHP
  • .NET
  • Elixir
  • Rust

(전체 목록은 여기에서 확인할 수 있어요)

HyperDX가 실행되면, OpenTelemetry SDK를 http://localhost:4318 에서 실행되는 OpenTelemetry collector로 지정하면 돼요.

HyperDX CLI

터미널을 더 선호한다면, @hyperdx/cli가 대화형 TUI와 CLI(hdx)를 제공해서 셸을 벗어나지 않고도 HyperDX 데이터를 다룰 수 있게 해 줘요.

npm install -g @hyperdx/cli
hdx auth login
hdx tui
  • 🖥️ 대화형 TUI — vim 스타일 키바인딩으로 검색, 라이브 테일, 트레이스 워터폴을 사용할 수 있어요
  • 📊 대시보드 타일과 임시 차트를 터미널에 ANSI 출력으로 렌더링해요
  • 🤖 에이전트 친화적 — 스크립트와 AI 에이전트를 위한 raw SQL 쿼리, NDJSON 출력, Drain 로그 패턴 마이닝을 지원해요

Motivation (왜 만들었는가)

HyperDX의 미션은 엔지니어가 안정적인 소프트웨어를 출시하도록 돕는 것이에요. 기존 도구들이 몇 가지 측면에서 부족하다고 느꼈기 때문이에요.

  1. 비싸요 — TB 단위 텔레메트리가 일반화되면서 가격이 따라가지 못해, 팀들이 수집 데이터를 줄일 수밖에 없었어요
  2. 쓰기 어려워요 — 풀타임 SRE가 구축해야 하고, 도메인 전문가가 아니면 자신 있게 쓰기 힘들어요
  3. 도구가 분산돼 있어요 — 로그, 세션 리플레이, APM, 예외 처리 등을 각각 다른 도구로 넘나들며 단서를 직접 조합해야 했어요

더 알아보기 (Learn more)