05 ClickStack

Teruskan telemetri dengan collector stateless lokal, aktifkan Managed ClickStack, dan periksa di HyperDX yang dihosting di cloud.

Titik awal

Anda berada di build-workshop-v1 — tidak perlu checkout. Siapkan sekitar 15 menit. Aplikasinya sudah diinstrumentasi untuk OpenTelemetry; di modul ini Anda menyalakannya dengan overlay collector.

Prasyarat: layanan Cloud Anda berjalan (modul 01).

Mengapa

Untuk mendiagnosis aplikasi nanti, Anda pertama-tama perlu melihatnya. ClickStack (tumpukan observability milik ClickHouse, dengan HyperDX sebagai UI-nya) menyimpan trace dan log OpenTelemetry di ClickHouse. Di modul ini Anda menyalakan collector-nya sehingga setiap permintaan melalui aplikasi menghasilkan telemetri yang bisa Anda query.

Tujuan

Trace aplikasi dan log kueri backend mengalir ke ClickStack, dengan setidaknya satu trace permintaan dari ujung ke ujung dan aliran catatan kueri sukses yang terlihat.

Langkah 1 — Jalankan overlay collector OpenTelemetry

HyperDX, penyimpanan, dan compute kueri tetap terkelola di ClickHouse Cloud. Satu-satunya komponen lokal di sini adalah collector OpenTelemetry stateless di samping aplikasi lokal; ia meneruskan telemetri dan bukan deployment ClickStack atau HyperDX lokal.

Periksa port collector lebih dahulu

Collector mempublikasikan OTLP pada port host 4317 dan 4318, yang umumnya sudah terpakai. Jika ./preflight.sh di ClickHouse_Demos/workshops/build_workshop/app memberi WARN pada port itu di modul 00, atur OTEL_GRPC_HOST_PORT dan OTEL_HTTP_HOST_PORT di .env.workshop ke nilai yang disarankan preflight (misalnya 24317 / 24318) sebelum menjalankan overlay-nya. Back end menjangkau collector di dalam jaringan, jadi memetakan ulang port host itu aman. Dari mana pun di dalam repositori yang di-clone, jalankan ulang cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh untuk memastikan port-nya bebas.

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

Nilai-nilai ini berada di bagian observability ClickStack pada .env.workshop.example; isilah di .env.workshop Anda:

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

Jangan meng-source berkas ini ke shell Anda. Perintah Compose di bawah membacanya secara langsung, yang menjaga kata sandi dan kunci API-nya tidak masuk variabel shell yang di-export dan memastikan suntingan berkas berikutnya tetap berlaku.

Sekarang jalankan tumpukannya dengan overlay tersebut. Overlay ini menetapkan OTEL_ENABLED=true pada back end, menambahkan layanan otel-collector (clickhouse/clickstack-otel-collector), dan membangun ulang front end dengan pengaturan telemetri browser:

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

Collector memakai ulang CLICKHOUSE_HOST / CLICKHOUSE_PORT / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD dari .env.workshop; back end meng-export OTLP ke http://otel-collector:4318 (HTTP/protobuf). Untuk juga mengambil stdout kontainer mentah pada host Linux, tambahkan --profile container-logs.

Langkah 2 — Aktifkan Managed ClickStack di layanan Anda

Workshop ini memakai Managed ClickStack (HyperDX) di dalam layanan ClickHouse Cloud Anda sendiri: collector menulis tabel otel_* ke layanan Anda dan UI HyperDX menampilkannya dari sana. Aktifkan di konsol:

Console - layanan Anda -> ClickStack -> Start Ingestion -> lewati langkah collector (collector aplikasi sudah berjalan dari Langkah 1) -> Launch ClickStack

Itu akan memasukkan Anda ke HyperDX dengan single sign-on. Telemetri sudah mulai mengalir, jadi UI terhosting itu dapat langsung terisi begitu terbuka.

Managed ClickStack: apa yang berbeda dari setup klasik

Back end memakai OpenTelemetry murni, bukan paket praktis hyperdx-opentelemetry yang disarankan dokumentasi ClickStack. Paket itu mematok keras opentelemetry-api==1.30.0, yang berkonflik dengan SDK Langfuse v4 yang dipakai fitur chat (memerlukan opentelemetry-api>=1.33.1) — keduanya tidak bisa berbagi satu lingkungan. Collector ClickStack meng-ingest OTLP standar, jadi distro murni itu berperilaku sama; workshop ini hanya mengatur variabel env exporter-nya sendiri.
Telemetri ClickStack berada di database terpisah pada layanan Anda (CLICKSTACK_DATABASE=otel), berbeda dari database data aplikasi (CLICKHOUSE_DATABASE=nyc_tlc_data).
Trace dan log Python backend mengalir lewat OTLP dari back end yang ter-instrumentasi otomatis. Collector opsional --profile container-logs hanya untuk layanan yang tidak ter-instrumentasi seperti penulis perjalanan; jalur log Docker Linux-nya mungkin tidak tersedia di Docker Desktop.

Langkah 3 — Hasilkan dan temukan lalu lintas di ClickStack

Buka dashboard Ops dan biarkan interval default 1m serta auto-refresh 5s berjalan sekitar 30 detik. Lalu buka ClickStack:

Di Traces, ikuti satu permintaan dari ujung ke ujung (front end -> back end -> ClickHouse).
Di Logs, pilih nyc-taxi-backend dan temukan catatan ClickHouse query ok yang berulang. Timestamp-nya seharusnya maju setiap refresh.
Jaga tingkat keparahan tetap bermakna: kueri yang sukses adalah DEBUG; percobaan ulang bangun-dari-idle dan kegagalan yang nyata muncul sebagai WARNING atau ERROR.

Anda seharusnya melihat sebuah layanan bernama nyc-taxi-backend muncul di HyperDX, dengan permintaan /api/... tampil sebagai trace, masing-masing membawa span anak clickhouse.query.

Tampilan Search HyperDX yang menampilkan trace nyc-taxi-backend — daftar langsung span GET /api/health dan POST dengan kolom timestamp, service, dan durasi

HyperDX menampilkan trace aplikasi: layanan nyc-taxi-backend dengan span permintaan /api/...-nya.

Cara memverifikasi Anda sudah selesai

Sebuah layanan bernama nyc-taxi-backend muncul di HyperDX.
Permintaan ke /api/... tampil sebagai trace, masing-masing dengan span anak clickhouse.query yang membawa db.statement, db.elapsed_ms, dan db.rows_returned.
Sumber Log menampilkan catatan DEBUG ... ClickHouse query ok yang segar selagi dashboard Ops tetap terbuka.
Anda belum akan melihat error kueri di sini: aplikasi yang sehat dan sudah terisi tidak menyentuh batas keamanan, dan permintaan 4xx tidak pernah mencapai ClickHouse. Di modul 07 fault yang disuntikkan membuat span clickhouse.query yang error (dengan error.category) menjadi teramati.

Penutup

Aplikasi sekarang dapat diamati: trace dan log kueri backend dicatat di ClickHouse dan dapat dijelajahi di ClickStack. Profil container-logs yang opsional menambahkan stdout dari penulis perjalanan pada host Linux yang kompatibel. Telemetri itu adalah substrat untuk pekerjaan AI SRE berikutnya.

Kondisi akhir

Telemetri mengalir ke ClickStack. Lanjutkan ke 06 AI SRE agar agent Anda membangun di atasnya.