05 ClickStack

학습자 레슨 05 ClickStack에 대응하는 진행자용 안내서입니다.

타이밍

약 15분. 모듈 07의 장애 실습 전에 텔레메트리가 쌓여 있어야 하므로, 이 모듈에서 가능한 한 빨리 컬렉터를 시작하고 계속 실행 상태로 두세요.

토크 트랙

• 매니지드 ClickStack은 텔레메트리를 ClickHouse Cloud에 저장하고, HyperDX가 호스팅되는 UI입니다. 로컬 컬렉터는 데이터를 전달할 뿐입니다. 엔드투엔드 요청 트레이스와 Log 소스의 새로운 DEBUG ... ClickHouse query ok 레코드를 모두 보여주세요.
• 학습자가 2단계에서 매니지드 ClickStack을 실행하기 전에 1단계에서 컬렉터를 시작하게 하세요. 그러면 텔레메트리가 도착할 시간이 생겨 호스팅 UI의 첫 화면이 유용해집니다.
• 프로젝터로 엔드투엔드 요청 트레이스 하나를 보여주세요.

흔한 실패 사례

• OTLP 호스트 포트 4317/4318이 이미 사용 중인 경우: .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를 실행하게 하세요. 백엔드는 네트워크 내부에서 컬렉터에 접근하므로 포트 변경은 안전합니다.
• 컬렉터 오버레이를 시작하지 않아서(두 번째 -f docker-compose.otel.yml을 빠뜨림) HyperDX에 아무것도 도착하지 않음.
• OTLP_AUTH_TOKEN 불일치, 또는 .env.workshop에 CLICKHOUSE_*가 없음(컬렉터는 Cloud 서비스에 접근하기 위해 CLICKHOUSE_HOST/PORT/USER/PASSWORD를 재사용합니다).
• 아직 트래픽이 발생하지 않은 경우. 두 대시보드를 클릭해 돌아다니게 하세요.
• Docker Desktop에서는 선택 사항인 --profile container-logs 스크레이퍼가 호스트 로그 경로를 마운트할 수 없습니다(데몬이 VM 안에 있음). 예상된 동작입니다. 백엔드 로그는 여전히 OTLP로 전달됩니다. HyperDX가 비어 있을 때 포워더를 진단하는 용도로만 docker compose ... logs를 쓰세요.
• 오버레이가 백엔드를 재생성한 뒤 앱이 예전에는 502를 반환했습니다(프런트엔드 nginx가 예전 백엔드 IP를 캐시함). 이제 프런트엔드가 요청마다 다시 이름을 해석하므로 약 10초 안에 스스로 복구되며 수동 재시작이 필요하지 않습니다. 리허설에서 수정이 확인됨.
• 리허설 기준값: 텔레메트리 파이프라인이 엔드투엔드로 검증되었습니다 — nyc-taxi-backend 트레이스에 db.statement / db.elapsed_ms / db.rows_returned를 담은 clickhouse.query 자식 스팬이 붙습니다. 2026-07 클린룸 리허설에서 확인됨.

초기화 절차

• 두 compose 파일로 재시작하세요: docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build.
• Cloud 콘솔에서 서비스를 열고 ClickStack을 선택한 뒤, SSO 세션이 만료되었다면 호스팅 UI를 다시 실행하세요.