NYC 택시 데이터로 배우는 AI SRE

ClickHouse BUILD 워크숍 플레이북에 오신 것을 환영합니다. 앞으로 3시간 동안 NYC 택시 승차 호출 분석 앱(React 프런트엔드, FastAPI 백엔드, Postgres 소스 데이터베이스)을 가져와, 직접 사용하는 에이전틱 코딩 도구로 구축하면서 ClickHouse Cloud 위에서 엔드투엔드로 띄우게 됩니다. 마칠 때쯤에는 매니지드 Postgres에서 오는 실시간 변경 데이터 캡처, 데이터에 대한 대화형 BI, 완전한 옵저버빌리티, AI 지원 SRE 워크플로, 엔드투엔드로 추적되는 인앱 AI 채팅을 갖추게 되고, AI SRE와 함께 실제 장애를 진단해보는 연습까지 마치게 됩니다.

같은 워크숍이 macOS와 Windows를 모두 지원합니다. 페이지 헤더에서 사용하는 컴퓨터를 한 번 선택하면, 플레이북이 올바른 설치 절차만 계속 보여줍니다. Windows에서는 공통 워크숍 툴체인을 WSL 2의 Ubuntu 안에서 실행합니다.

워크숍을 마치면 동작하는 프로토타입과 팀에 보여줄 수 있는 이 저장소를 갖고 돌아갑니다. 매니지드 ClickHouse, Postgres, ClickPipes, Agents, ClickStack 산출물은 트라이얼 기간 동안 유지되고, Langfuse 트레이스는 Langfuse Cloud에 남습니다. 다시 돌아왔을 때는 Docker로 로컬 앱과 텔레메트리 포워더를 재시작하면 됩니다. 마칠 때쯤에는 다섯 가지를 라이브로 시연할 수 있습니다:

• ClickHouse Cloud 위의 실시간 운영 대시보드,
• 매니지드 Postgres에서 스트리밍되는 변경 데이터 캡처 파이프라인,
• ClickHouse Agents로 데이터를 다루는 대화형 BI,
• 텔레메트리 위에 AI가 만든 SRE 대시보드와 알림,
• 그리고 Langfuse에서 엔드투엔드로 추적되는 인앱 AI 채팅.

이 플레이북은 듀얼 트랙입니다. 학습자 트랙은 강의실에서 따라가는 레슨입니다. 강사 트랙은 같은 모듈에 대한 진행자용 안내서로, 타이밍, 설명 스크립트, 자주 발생하는 실패, 초기화 절차를 담고 있습니다.

학습자를 위한 안내

모듈 단위로 진행합니다. 각 모듈은 시작 체크포인트를 명시하고, 그 단계가 왜 중요한지 설명하며, 구체적인 목표를 제시하고, 번호가 붙은 절차를 안내한 뒤, 스스로 확인할 수 있는 검증으로 끝납니다. 강의실 전체 속도에 맞출 필요는 전혀 없습니다. 뒤처졌다면 각 모듈의 시작점 섹션이 무엇이 준비되어 있어야 하는지 정확히 알려주므로, 거기서부터 자신의 속도로 따라잡을 수 있습니다.

당일 필요한 것:

• 00 설치의 사전 요구사항을 충족하는 노트북.
• 직접 사용하는 에이전틱 코딩 도구(Claude Code, Cursor, Codex CLI 또는 Windsurf), 로그인된 상태이며 활성 플랜에 가입되어 있어야 합니다.
• 트라이얼 크레딧이 보이는 ClickHouse Cloud 계정(사전 작업에서 생성).
• 로컬에 클론된 워크숍 앱 저장소, 그리고 실행 중인 Docker.

자율 진행인가요? 강사 없이도 워크숍 전체를 완료할 수 있습니다 — 기본 경로는 완전히 셀프서비스입니다. 무엇이 달라지는지, 코딩 에이전트를 강사처럼 쓰는 방법은 이 워크숍을 자율 진행으로 운영하기를 보고, 테스트에서 확인된 모든 실패 사례는 트러블슈팅 참고 문서를 보세요.

강사를 위한 안내

강사 트랙은 학습자 트랙과 일대일로 대응합니다. 모든 모듈마다 타이밍 예산, 설명 스크립트, 강의실에서 실제로 발생하는 실패와 해결 방법, 참가자(또는 강의실 전체)를 정상 상태로 되돌리는 정확한 초기화 절차를 제공합니다. 강의실 수준의 진행 순서와 공유 리소스 체크리스트는 강사 트랙 랜딩 페이지를 먼저 읽으세요.

워크숍 범위

여러분이 다룰 앱

워크숍 앱은 NYC 택시 승차 호출 비즈니스를 위한 자체 완결형 "워 룸" 분석 스택입니다:

• 프런트엔드 — 두 개의 대시보드를 가진 React 단일 페이지 앱: Ops 대시보드(실시간 운영 지표)와 Historical 대시보드(넓은 범위 집계와 드릴다운). 모듈 08에서 연결하는 인앱 AI 채팅 패널도 여기에 있습니다.
• 백엔드 — 안전한 파라미터화 분석 엔드포인트를 노출하는 FastAPI 서비스.
• 소스 데이터베이스 — 운영상의 단일 진실 공급원 역할을 하는 ClickHouse 매니지드 Postgres로, ClickHouse로 들어가는 변경 데이터 캡처의 출발점입니다.
• 분석 웨어하우스 — ClickHouse Cloud. 모듈 01에서 백엔드가 이곳을 가리키게 하고, CDC와 옵저버빌리티 데이터, BI 쿼리를 받습니다.

앱을 처음부터 만들지는 않습니다. React/FastAPI 앱은 로컬에서 실행되고, 상태를 갖는 모든 데이터·제품 서비스는 처음부터 클라우드에서 호스팅됩니다.

여러분이 다룰 플랫폼

ClickHouse Cloud는 스택 전체를 아우르는 단일 플랫폼입니다 — 맨 아래의 데이터 인제스트부터, ClickHouse에서의 저장·분석, 그 위의 관측과 AI 계층까지 이어집니다. 이 워크숍은 바로 이 구성 요소들을 따라가는 가이드 투어입니다: ClickPipes로 인제스트하고, ClickHouse에서 분석하고, Managed ClickStack/HyperDX로 관측합니다. Langfuse와 OpenAI는 별도의 호스팅 서비스입니다.

아키텍처 (목표 최종 상태)

먼저 각 구성 요소를 실행 위치별로 묶어봅니다: 노트북에서 도는 무상태 앱과 도구, ClickHouse Cloud의 상태 저장 서비스, 그리고 별도의 호스팅 AI 서비스.

데이터가 흐르는 방식

이제 로컬 부하 생성기에서 시작한 하나의 실시간 운행이 매니지드 Postgres와 ClickPipes를 거쳐 default.realtime_trips로 들어가고, 마지막으로 애플리케이션 대시보드에 도달하는 과정을 따라가 봅니다.

위 다이어그램들은 workshops/build_workshop/docs/diagrams/gen_diagrams.py에서 생성됩니다 (스크립트를 수정하고 다시 실행하면 SVG가 재생성됩니다) — 아래 모듈 흐름을 참고하세요.

모듈

열 개의 핵심 모듈을 순서대로 진행합니다. 앱은 build-workshop-v1에서 이미 완성되어 있으므로 07을 제외한 모든 모듈은 모듈별 체크아웃이 필요하지 않습니다 — 앱 코드를 바꾸는 대신 서비스를 설정하고 연결합니다. 브랜치를 바꾸는 경우는 모듈 07의 결함 브랜치뿐입니다.

위 시간을 합치면 약 2시간 30분의 실습 작업이 되고, 3시간 세션의 나머지는 오프닝, 전환, 그리고 마지막 시연입니다.

진행 방법

브랜치

앱은 build-workshop-v1에서 이미 완성되어 있습니다. 이 워크숍은 애플리케이션 코드를 고치는 것이 아니라 서비스를 설정하고 연결하는 것 — 실시간 CDC, 옵저버빌리티, 에이전트, 채팅 — 에 관한 것이므로, 브랜치를 거쳐가며 쌓아 올릴 것이 없습니다:

• 모듈 00에서 앱을 한 번 클론하고 build-workshop-v1로 전환한 뒤, 모듈 07의 결함 시나리오를 실행할 때를 제외하면 계속 그 브랜치에 머무릅니다.
• 늦게 합류한 사람도 절대 낙오되지 않습니다: 매니지드 리소스는 서비스 측에 있고, 완성된 로컬 앱은 워크숍 브랜치와 .env.workshop만으로 다시 시작됩니다. 따라잡아야 할 모듈별 체크아웃이 없습니다.
• 브랜치를 바꾸는 곳은 모듈 07(고장 내고 수정하기)뿐이며, 여기서는 결함 브랜치 (fault/01-map-not-loading, fault/02-zone-stats-500, fault/03-slow-dashboard)를 사용합니다. 하나를 체크아웃해 실패를 진단하고, 수정 사항을 보존한 뒤 모듈 07의 stash 및 전환 초기화 절차로 build-workshop-v1로 돌아옵니다.

환경 변수

워크숍 설정은 앱 저장소 루트의 단일 .env.workshop 파일에 있습니다. 안전한 .env.workshop.example이 커밋되어 있으니, 복사한 뒤 여러분 것인 값만 채우세요:

cp .env.workshop.example .env.workshop

스택은 --env-file로 이 파일을 명시적으로 읽습니다:

docker compose --env-file .env.workshop -f docker-compose.workshop.yml up -d

값은 모듈 00 설치 과정에서 채우며, ClickStack 블록만 모듈 05에서 추가합니다:

• CLICKHOUSE_HOST, CLICKHOUSE_PASSWORD (그리고 CLICKHOUSE_PORT=8443, CLICKHOUSE_USER=default, CLICKHOUSE_DATABASE=nyc_tlc_data, CLICKHOUSE_SECURE=true) — 여러분의 Cloud 서비스(모듈 00). CLICKHOUSE_HOST는 스킴과 포트가 없는 순수 호스트명입니다.
• OPENAI_API_KEY, LLM_MODEL=gpt-5.4-mini, LLM_BASE_URL — 인앱 채팅용 런타임 LLM(모듈 00).
• LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL — 여러분의 Langfuse 프로젝트(모듈 00). LANGFUSE_BASE_URL은 Langfuse v4의 환경 변수 이름이며, https://us.cloud.langfuse.com(US) 또는 https://cloud.langfuse.com(EU)을 사용하세요.
• OTLP_AUTH_TOKEN, CLICKSTACK_DATABASE=otel, OTEL_SERVICE_NAME=nyc-taxi-backend — 옵저버빌리티. 같은 .env.workshop의 ClickStack 섹션에 있습니다(모듈 05).

채워 넣은 .env.workshop은 절대 커밋하지 마세요. git에서 무시되도록 설정되어 있습니다.

저장소 구조

모든 것이 하나의 저장소(ClickHouse_Demos)의 build-workshop-v1 브랜치에 있습니다. 모든 워크숍의 랩 코드는 workshops/ 아래에 있으므로 여러분이 다룰 앱은 workshops/build_workshop/이고, 지금 읽고 있는 게시된 플레이북은 저장소 루트의 공용 사이트인 site/에 있습니다. 이 사이트는 Agent Arena 워크숍과 정적 RTA 가이드도 함께 제공합니다.

site/                           # the shared Next.js + Fumadocs site (all workshops)
  content/docs/build-workshop/  # this playbook (the site you are reading)
    index.mdx                   # this overview
    learner/                    # self-paced guide, the lessons 00-setup ... 09-wrap-up,
                                #   and a troubleshooting reference
    instructor/                 # facilitator notes: 00-setup ... 09-wrap-up
  src/                          # Next.js + Fumadocs app
  README.md                     # run, build, deploy, and authoring guide

workshops/build_workshop/
  app/                         # the NYC-taxi app you build on (cloned in module 00)
    frontend/                  # React SPA (Ops + Historical dashboards, chat panel)
    backend/                   # FastAPI analytics API + AI chat
    db/cloud/001_cloud_schema.sql   # maintainer fixture; Module 01 contains the copyable SQL
    docker-compose.workshop.yml     # the workshop stack (Cloud + ClickPipes)
    docker-compose.otel.yml         # the ClickStack observability overlay (module 05)
    .env.workshop.example      # single env template (Cloud + chat + observability);
                               #   copy to .env.workshop and fill in your values

다음으로 갈 곳