05 ClickStack

로컬 무상태 컬렉터로 텔레메트리를 전달하고, Managed ClickStack을 활성화한 뒤 클라우드 호스팅 HyperDX에서 확인합니다.

시작점

여러분은 build-workshop-v1에 있습니다 — 체크아웃은 필요하지 않습니다. 약 15분을 예상하세요. 앱은 이미 OpenTelemetry용으로 계측되어 있으며, 이 모듈에서는 컬렉터 오버레이로 그것을 켭니다.

사전 조건: Cloud 서비스가 실행 중(모듈 01).

왜

나중에 앱을 진단하려면 먼저 앱을 볼 수 있어야 합니다. ClickStack(ClickHouse의 옵저버빌리티 스택으로, UI는 HyperDX)은 OpenTelemetry 트레이스와 로그를 ClickHouse에 저장합니다. 이 모듈에서는 컬렉터를 켜서, 앱을 지나는 모든 요청이 쿼리 가능한 텔레메트리를 만들게 합니다.

목표

앱 트레이스와 백엔드 쿼리 로그가 ClickStack으로 흘러 들어가고, 최소한 하나의 엔드투엔드 요청 트레이스와 성공한 쿼리 기록의 흐름이 보이는 것.

Step 1 — OpenTelemetry 컬렉터 오버레이 실행

HyperDX, 스토리지, 쿼리 컴퓨트는 ClickHouse Cloud에서 관리되는 상태로 유지됩니다. 여기서 유일한 로컬 구성 요소는 로컬 앱 옆의 무상태 OpenTelemetry 컬렉터이며, 텔레메트리를 전달할 뿐 로컬 ClickStack이나 HyperDX 배포가 아닙니다.

먼저 컬렉터 포트를 확인하세요

컬렉터는 호스트 포트 4317과 4318에 OTLP를 노출하는데, 이 포트는 이미 사용 중인 경우가 흔합니다. 모듈 00에서 ClickHouse_Demos/workshops/build_workshop/app의 ./preflight.sh가 이 포트에 대해 WARN을 냈다면, 오버레이를 시작하기 전에 .env.workshop의 OTEL_GRPC_HOST_PORT와 OTEL_HTTP_HOST_PORT를 preflight가 제안한 값(예 24317 / 24318)으로 설정하세요. 백엔드는 네트워크 내부에서 컬렉터에 접근하므로 호스트 포트를 다시 매핑해도 안전합니다. 클론한 저장소 안 어디에서든 cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh를 다시 실행해 포트가 비어 있는지 확인하세요.

`.env.workshop`과 `docker-compose.otel.yml`

이 값들은 .env.workshop.example의 ClickStack 옵저버빌리티 섹션에 있습니다. 여러분의 .env.workshop에 채우세요:

OTLP_AUTH_TOKEN=change-me-workshop-token   # shared secret securing OTLP ingest
CLICKSTACK_DATABASE=otel                   # ClickStack's own otel_* tables
OTEL_SERVICE_NAME=nyc-taxi-backend         # the service name shown in HyperDX
LOG_LEVEL=DEBUG                            # show successful queries in Log source

이 파일을 셸에 source하지 마세요. 아래 Compose 명령이 파일을 직접 읽으므로, 비밀번호와 API 키가 export된 셸 변수로 나가지 않고 이후 파일 수정도 반영됩니다.

이제 오버레이와 함께 스택을 띄우세요. 오버레이는 백엔드에 OTEL_ENABLED=true를 설정하고, otel-collector 서비스(clickhouse/clickstack-otel-collector)를 추가하며, 브라우저 텔레메트리 설정으로 프런트엔드를 다시 빌드합니다:

docker compose --env-file .env.workshop \
  -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build

컬렉터는 .env.workshop의 CLICKHOUSE_HOST / CLICKHOUSE_PORT / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD를 재사용하며, 백엔드는 OTLP를 http://otel-collector:4318 (HTTP/protobuf)로 내보냅니다. Linux 호스트에서 컨테이너의 raw stdout까지 수집하려면 --profile container-logs를 추가하세요.

Step 2 — 서비스에서 Managed ClickStack 활성화

이 워크숍은 여러분의 ClickHouse Cloud 서비스 안에서 **Managed ClickStack (HyperDX)**을 사용합니다: 컬렉터가 otel_* 테이블을 여러분의 서비스에 쓰고, HyperDX UI가 그것을 그대로 렌더링합니다. 콘솔에서 활성화하세요:

콘솔 - 여러분의 서비스 -> ClickStack -> Start Ingestion -> 컬렉터 단계 건너뛰기(앱 컬렉터가 Step 1에서 이미 실행 중) -> Launch ClickStack

그러면 HyperDX로 싱글 사인온됩니다. 텔레메트리는 이미 흐르기 시작했으므로, 호스팅 UI는 열리는 즉시 데이터를 채울 수 있습니다.

Managed ClickStack: 기존 방식과 다른 점

백엔드는 ClickStack 문서가 권하는 편의 패키지 hyperdx-opentelemetry가 아니라 순수 OpenTelemetry를 사용합니다. 그 패키지는 opentelemetry-api==1.30.0을 고정하는데, 이는 채팅 기능이 사용하는 Langfuse v4 SDK(opentelemetry-api>=1.33.1 필요)와 충돌합니다 — 두 패키지는 한 환경을 공유할 수 없습니다. ClickStack 컬렉터는 표준 OTLP를 수집하므로 순수 배포판도 동일하게 동작하며, 워크숍은 exporter 환경 변수만 직접 설정합니다.
ClickStack의 텔레메트리는 여러분의 서비스에서 별도 데이터베이스 (CLICKSTACK_DATABASE=otel)에 저장되며, 앱의 데이터 데이터베이스 (CLICKHOUSE_DATABASE=nyc_tlc_data)와 구분됩니다.
트레이스와 백엔드 Python 로그는 자동 계측된 백엔드에서 OTLP로 흐릅니다. 선택적인 --profile container-logs 컬렉터는 trip writer처럼 계측되지 않은 서비스만을 위한 것이며, 그 Linux Docker 로그 경로는 Docker Desktop에서는 사용할 수 없을 수 있습니다.

Step 3 — 트래픽을 만들고 ClickStack에서 찾기

Ops 대시보드를 열고 기본값인 1m 간격과 5s 자동 새로고침 상태로 약 30초 동안 두세요. 그다음 ClickStack을 여세요:

Traces에서 하나의 요청을 엔드투엔드로 따라가세요(프런트엔드 -> 백엔드 -> ClickHouse).
Logs에서 nyc-taxi-backend를 선택하고 반복되는 ClickHouse query ok 기록을 찾으세요. 새로고침마다 타임스탬프가 앞으로 나아가야 합니다.
심각도를 의미 있게 유지하세요: 성공한 쿼리는 DEBUG이고, 실제 idle 상태 복귀 재시도와 실패는 WARNING 또는 ERROR로 나타납니다.

HyperDX에 nyc-taxi-backend라는 서비스가 나타나고, /api/... 요청이 트레이스로 표시되며, 각 트레이스가 자식 clickhouse.query 스팬을 갖고 있어야 합니다.

nyc-taxi-backend 트레이스를 보여주는 HyperDX Search 뷰 — 타임스탬프, 서비스, 소요 시간 컬럼과 함께 GET /api/health와 POST 스팬이 실시간 목록으로 표시됨

앱의 트레이스를 렌더링하는 HyperDX: nyc-taxi-backend 서비스와 그 /api/... 요청 스팬.

완료 확인 방법

HyperDX에 nyc-taxi-backend라는 서비스가 나타납니다.
/api/...로의 요청이 트레이스로 표시되며, 각각 db.statement, db.elapsed_ms, db.rows_returned를 담은 자식 clickhouse.query 스팬을 갖습니다.
Ops 대시보드를 열어둔 동안 Log 소스에 새로운 DEBUG ... ClickHouse query ok 기록이 보입니다.
아직 여기서 쿼리 오류는 보이지 않습니다: 정상적으로 시드된 앱은 안전 한도를 건드리지 않고, 4xx 요청은 ClickHouse에 도달하지 않습니다. 모듈 07에서 주입되는 결함이 오류가 난 clickhouse.query 스팬(error.category 포함)을 관측 가능하게 만듭니다.

마무리

앱이 이제 관측 가능해졌습니다: 트레이스와 백엔드 쿼리 로그가 ClickHouse에 기록되고 ClickStack에서 탐색할 수 있습니다. 선택적인 container-logs 프로필은 호환되는 Linux 호스트에서 trip writer의 stdout을 추가합니다. 그 텔레메트리가 다음 AI SRE 작업의 기반입니다.

최종 상태

텔레메트리가 ClickStack으로 흐르고 있습니다. 에이전트가 그 위에 무언가를 만들게 하려면 06 AI SRE로 계속하세요.

시작점

왜

목표