AI SRE dengan Data NYC Taxi

Selamat datang di playbook ClickHouse BUILD Workshop. Selama tiga jam Anda akan mengambil sebuah aplikasi analitik ride-hailing NYC-taxi (front end React, back end FastAPI, database sumber Postgres) dan menjalankannya dari ujung ke ujung di ClickHouse Cloud, menggunakan agentic coding tool Anda sendiri untuk membangunnya. Pada akhirnya Anda akan punya change data capture real-time dari Postgres terkelola, BI konversasional di atas data Anda, observability penuh, alur kerja SRE yang dibantu AI, dan chat AI dalam aplikasi yang di-trace dari ujung ke ujung, serta Anda sudah berlatih mendiagnosis insiden nyata bersama AI SRE.

Workshop yang sama mendukung macOS dan Windows. Pilih komputer Anda di header halaman satu kali; playbook akan menjaga setup yang benar tetap terlihat di mana pun. Windows menjalankan toolchain workshop bersama di dalam Ubuntu pada WSL 2.

Anda pulang dengan prototipe yang berjalan dan repo ini untuk ditunjukkan kepada tim Anda. Artefak ClickHouse terkelola, Postgres, ClickPipes, Agents, dan ClickStack bertahan selama masa trial; trace Langfuse bertahan di Langfuse Cloud. Jalankan ulang aplikasi lokal dan telemetry forwarder dengan Docker saat Anda kembali. Pada akhirnya Anda dapat mendemokan lima hal secara langsung:

• dashboard operasional real-time di ClickHouse Cloud,
• pipeline change-data-capture yang mengalir dari Postgres terkelola,
• BI konversasional di atas data Anda dengan ClickHouse Agents,
• dashboard dan alert SRE yang dibangun AI di atas telemetri Anda,
• serta chat AI dalam aplikasi yang di-trace dari ujung ke ujung di Langfuse.

Playbook ini punya dua jalur. Jalur Learner adalah materi yang Anda ikuti di ruang kelas. Jalur Instructor adalah pendamping fasilitator untuk modul yang sama: waktu, alur bicara, kegagalan yang umum, dan langkah reset.

Untuk learner

Anda akan bekerja modul demi modul. Setiap modul menyebutkan checkpoint awal, menjelaskan mengapa langkah itu penting, menyatakan tujuan yang konkret, memandu Anda lewat langkah bernomor, dan diakhiri dengan verifikasi yang bisa Anda periksa sendiri. Anda tidak harus selalu seirama dengan seluruh ruangan: jika Anda tertinggal, bagian Titik awal pada setiap modul menyatakan tepat apa yang perlu sudah tersedia, sehingga Anda bisa menyusul dari sana dengan kecepatan sendiri.

Yang Anda butuhkan pada hari itu:

• Laptop yang memenuhi prasyarat di 00 Setup.
• Agentic coding tool Anda sendiri (Claude Code, Cursor, Codex CLI, atau Windsurf), sudah masuk dan berada pada paket aktif.
• Akun ClickHouse Cloud dengan kredit trial yang terlihat (dibuat saat prework).
• Repositori aplikasi workshop yang sudah di-clone secara lokal, dengan Docker berjalan.

Belajar mandiri? Anda dapat menyelesaikan seluruh workshop tanpa instruktur - jalur utamanya sepenuhnya self-serve. Lihat Menjalankan workshop ini secara mandiri untuk apa yang berubah, cara memakai coding agent Anda sebagai instruktur, dan rujukan Troubleshooting untuk setiap kegagalan yang terlihat saat pengujian.

Untuk instruktur

Jalur Instructor mencerminkan jalur Learner satu per satu. Untuk setiap modul Anda mendapat anggaran waktu, alur bicara, kegagalan yang benar-benar terjadi di ruangan beserta cara mengatasinya, dan langkah reset yang tepat untuk membawa seorang peserta (atau seluruh ruangan) kembali ke kondisi yang diketahui baik. Baca halaman utama jalur Instructor lebih dahulu untuk run of show tingkat ruangan dan checklist sumber daya bersama.

Cakupan workshop

Aplikasi yang Anda kembangkan

Aplikasi workshop ini adalah tumpukan analitik "war room" mandiri untuk bisnis ride-hailing NYC-taxi:

• Front end — sebuah single-page app React dengan dua dashboard: dashboard Ops (metrik operasional langsung) dan dashboard Historical (agregasi rentang besar dan drilldown). Ia juga memuat panel chat AI dalam aplikasi yang Anda hubungkan di modul 08.
• Back end — layanan FastAPI yang mengekspos endpoint analitik yang aman dan terparameter.
• Database sumber — Postgres terkelola ClickHouse sebagai sumber kebenaran operasional, asal dari change data capture ke ClickHouse.
• Gudang analitik — ClickHouse Cloud, yang Anda arahkan back end ke sana di modul 01 dan yang menerima CDC, data observability, serta kueri BI.

Anda tidak membangun aplikasi dari nol. Aplikasi React/FastAPI berjalan secara lokal, sementara setiap layanan data atau produk yang stateful dihosting di cloud sejak awal.

Platform yang Anda kembangkan

ClickHouse Cloud adalah satu platform yang menjangkau seluruh tumpukan — dari mengonsumsi data di bagian bawah, menyimpan dan menganalisisnya di ClickHouse, hingga mengamatinya dan melapisi AI di atasnya. Workshop ini adalah tur terpandu melalui persis bagian-bagian tersebut: Anda melakukan ingest dengan ClickPipes, analisis di ClickHouse, dan observasi dengan Managed ClickStack/HyperDX. Langfuse dan OpenAI adalah layanan terhosting yang terpisah.

Arsitektur (kondisi akhir yang dituju)

Pertama, kelompokkan bagian-bagiannya berdasarkan tempat ia berjalan: aplikasi dan alat yang stateless di laptop Anda, layanan stateful di ClickHouse Cloud, dan layanan AI terhosting yang terpisah.

Bagaimana data mengalir

Sekarang ikuti satu perjalanan langsung dari load generator lokal melalui Postgres terkelola dan ClickPipes, masuk ke default.realtime_trips, dan akhirnya ke dashboard aplikasi.

Diagram di atas dihasilkan dari workshops/build_workshop/docs/diagrams/gen_diagrams.py (ubah skripnya dan jalankan ulang untuk membuat SVG-nya lagi) — lihat alur modul di bawah.

Modul

Sepuluh modul inti, berurutan. Aplikasi sudah lengkap di build-workshop-v1, jadi setiap modul kecuali 07 tidak perlu checkout per modul — Anda mengonfigurasi dan menghubungkan layanan, bukan mengubah kode aplikasi. Satu-satunya perpindahan branch adalah branch fault di modul 07.

Total waktunya sekitar 2 jam 30 menit kerja praktik; sisa dari sesi tiga jam adalah pembukaan, transisi, dan demo penutup.

Cara mengerjakannya

Branch

Aplikasi sudah lengkap di build-workshop-v1. Workshop ini tentang mengonfigurasi dan menghubungkan layanan — CDC real-time, observability, agent, chat — bukan mengedit kode aplikasi, jadi tidak ada yang perlu dibangun bertahap branch demi branch:

• Clone aplikasi sekali di modul 00, pindah ke build-workshop-v1, dan tetap di sana kecuali saat menjalankan skenario fault di modul 07.
• Peserta yang datang terlambat tidak pernah terlantar: sumber daya terkelola berada di sisi layanan, dan aplikasi lokal yang lengkap dijalankan ulang dari branch workshop ditambah .env.workshop. Tidak ada checkout per modul yang harus disusul.
• Satu-satunya perpindahan branch ada di modul 07 (Break and fix), yang memakai branch fault (fault/01-map-not-loading, fault/02-zone-stats-500, fault/03-slow-dashboard). Anda melakukan checkout salah satunya, mendiagnosis kegagalan, lalu mempertahankan perbaikan dan kembali ke build-workshop-v1 dengan reset stash-and-switch modul 07.

Variabel lingkungan

Konfigurasi workshop berada dalam satu file .env.workshop di root repositori aplikasi. Sebuah .env.workshop.example yang aman sudah di-commit; salin file itu dan isi hanya nilai-nilai yang menjadi milik Anda:

cp .env.workshop.example .env.workshop

Tumpukan ini membacanya secara eksplisit lewat --env-file:

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

Anda mengisi nilainya saat setup modul 00, kecuali blok ClickStack, yang Anda tambahkan di modul 05:

• CLICKHOUSE_HOST, CLICKHOUSE_PASSWORD (ditambah CLICKHOUSE_PORT=8443, CLICKHOUSE_USER=default, CLICKHOUSE_DATABASE=nyc_tlc_data, CLICKHOUSE_SECURE=true) — layanan Cloud Anda (modul 00). CLICKHOUSE_HOST adalah hostname murni, tanpa skema dan tanpa port.
• OPENAI_API_KEY, LLM_MODEL=gpt-5.4-mini, LLM_BASE_URL — LLM runtime untuk chat dalam aplikasi (modul 00).
• LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL — proyek Langfuse Anda (modul 00). LANGFUSE_BASE_URL adalah nama env Langfuse v4; gunakan https://us.cloud.langfuse.com (US) atau https://cloud.langfuse.com (EU).
• OTLP_AUTH_TOKEN, CLICKSTACK_DATABASE=otel, OTEL_SERVICE_NAME=nyc-taxi-backend — observability, di bagian ClickStack pada .env.workshop yang sama (modul 05).

Jangan pernah meng-commit .env.workshop yang sudah Anda isi; file itu di-ignore oleh git.

Tata letak repositori

Semuanya berada dalam satu repositori (ClickHouse_Demos), pada branch build-workshop-v1. Kode lab setiap workshop berada di bawah workshops/, jadi aplikasi yang Anda kembangkan adalah workshops/build_workshop/; playbook terpublikasi yang Anda baca berada di situs bersama pada root repositori, site/, yang juga melayani workshop Agent Arena dan panduan RTA statis.

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

Ke mana selanjutnya