05 ClickStack

Chuyển tiếp telemetry bằng một collector không trạng thái chạy local, bật Managed ClickStack, và kiểm tra nó trong HyperDX host trên cloud.

Điểm khởi đầu

Bạn đang ở build-workshop-v1 — không cần checkout. Hãy dự trù khoảng 15 phút. Ứng dụng đã được instrument cho OpenTelemetry sẵn; trong module này bạn bật nó lên bằng overlay collector.

Yêu cầu tiên quyết: service Cloud của bạn đang chạy (module 01).

Để chẩn đoán ứng dụng về sau, trước tiên bạn cần thấy được nó. ClickStack (stack quan sát của ClickHouse, với HyperDX làm UI) lưu các trace và log OpenTelemetry trong ClickHouse. Trong module này bạn bật collector lên để mọi request đi qua ứng dụng đều sinh ra telemetry mà bạn có thể truy vấn.

Mục tiêu

Các trace của ứng dụng và log truy vấn của back end chảy vào ClickStack, với ít nhất một trace request từ đầu đến cuối và một luồng bản ghi truy vấn thành công thấy được.

Bước 1 — Chạy overlay collector OpenTelemetry

HyperDX, phần lưu trữ, và phần tính toán truy vấn vẫn được quản lý trong ClickHouse Cloud. Thành phần local duy nhất ở đây là một collector OpenTelemetry không trạng thái đặt cạnh ứng dụng local; nó chuyển tiếp telemetry và không phải là một bản triển khai ClickStack hay HyperDX cục bộ.

Kiểm tra các port của collector trước

Collector công bố OTLP trên các port 4317 và 4318 của host, và các port này thường đã bị chiếm dụng. Nếu ./preflight.sh trong ClickHouse_Demos/workshops/build_workshop/app đã WARN về chúng ở module 00, hãy đặt OTEL_GRPC_HOST_PORT và OTEL_HTTP_HOST_PORT trong .env.workshop thành các giá trị mà preflight đề xuất (ví dụ 24317 / 24318) trước khi khởi động overlay. Back end kết nối tới collector trong cùng network, nên việc đổi port của host là an toàn. Từ bất cứ đâu bên trong repository đã clone, hãy chạy lại cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh để xác nhận các port đã thông.

`.env.workshop` và `docker-compose.otel.yml`

Các biến này nằm trong phần quan sát ClickStack của .env.workshop.example; hãy điền chúng trong file .env.workshop của bạn:

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

Đừng source file này vào shell của bạn. Câu lệnh Compose bên dưới đọc nó trực tiếp, điều này giữ các password và API key của nó khỏi các biến shell đã export và bảo đảm những lần sửa file sau đó có hiệu lực.

Giờ hãy khởi động stack cùng với overlay. Overlay đặt OTEL_ENABLED=true trên back end, thêm service otel-collector (clickhouse/clickstack-otel-collector), và build lại front end với các thiết lập telemetry cho browser:

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

Collector dùng lại CLICKHOUSE_HOST / CLICKHOUSE_PORT / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD từ .env.workshop; back end export OTLP tới http://otel-collector:4318 (HTTP/protobuf). Để đồng thời thu cả stdout thô của container trên một host Linux, hãy thêm --profile container-logs.

Bước 2 — Bật Managed ClickStack trên service của bạn

Workshop dùng Managed ClickStack (HyperDX) bên trong chính service ClickHouse Cloud của bạn: collector ghi các bảng otel_* vào service của bạn và UI HyperDX hiển thị chúng ở đó. Hãy bật nó trong console:

Console - service của bạn -> ClickStack -> Start Ingestion -> bỏ qua bước collector (collector của ứng dụng đã chạy từ Bước 1) -> Launch ClickStack

Việc đó đăng nhập một lần cho bạn vào HyperDX. Telemetry đã bắt đầu chảy, nên UI được host có thể hiện dữ liệu ngay khi nó mở ra.

Managed ClickStack: điều gì khác so với thiết lập cổ điển

Back end dùng OpenTelemetry thuần, không dùng package tiện lợi hyperdx-opentelemetry như tài liệu ClickStack đề xuất. Package đó ghim cứng opentelemetry-api==1.30.0, xung đột với SDK Langfuse v4 mà tính năng chat sử dụng (cần opentelemetry-api>=1.33.1) — hai thứ này không thể dùng chung một môi trường. Collector ClickStack nạp OTLP tiêu chuẩn, nên bản distro thuần hoạt động y hệt; workshop chỉ tự đặt các biến môi trường của exporter.
Telemetry của ClickStack nằm trong một database riêng trên service của bạn (CLICKSTACK_DATABASE=otel), tách biệt với database dữ liệu của ứng dụng (CLICKHOUSE_DATABASE=nyc_tlc_data).
Các trace và log Python của back end chảy qua OTLP từ back end đã được auto-instrument. Collector tùy chọn --profile container-logs chỉ dành cho các service không được instrument như bộ ghi chuyến xe; đường dẫn log Docker trên Linux của nó có thể không khả dụng trên Docker Desktop.

Bước 3 — Sinh lưu lượng và tìm nó trong ClickStack

Hãy mở dashboard Ops và để nguyên interval mặc định 1m cùng auto-refresh 5s chạy khoảng 30 giây. Sau đó mở ClickStack:

Trong Traces, hãy theo dấu một request từ đầu đến cuối (front end -> back end -> ClickHouse).
Trong Logs, hãy chọn nyc-taxi-backend và tìm các bản ghi ClickHouse query ok lặp lại. Timestamp của chúng phải tiến lên sau mỗi lần refresh.
Hãy giữ mức severity có ý nghĩa: các truy vấn thành công là DEBUG; các lần retry do idle-wake thực sự và các lỗi thật hiện ra dưới dạng WARNING hoặc ERROR.

Bạn sẽ thấy một service tên nyc-taxi-backend xuất hiện trong HyperDX, với các request /api/... hiển thị dưới dạng trace, mỗi trace mang một span con clickhouse.query.

Khung nhìn Search của HyperDX hiển thị các trace nyc-taxi-backend — một danh sách trực tiếp các span GET /api/health và POST với các cột timestamp, service, và duration

HyperDX đang hiển thị các trace của ứng dụng: service nyc-taxi-backend cùng các span request /api/... của nó.

Cách kiểm chứng bạn đã hoàn thành

Một service tên nyc-taxi-backend xuất hiện trong HyperDX.
Các request tới /api/... hiển thị dưới dạng trace, mỗi trace có một span con clickhouse.query mang db.statement, db.elapsed_ms, và db.rows_returned.
Log source hiển thị các bản ghi DEBUG ... ClickHouse query ok mới trong khi dashboard Ops vẫn đang mở.
Bạn sẽ chưa thấy lỗi truy vấn ở đây: một ứng dụng khỏe mạnh, đã có dữ liệu, không kích hoạt các ngưỡng an toàn, và các request 4xx không bao giờ đến được ClickHouse. Ở module 07, lỗi được tiêm vào sẽ làm một span clickhouse.query bị lỗi (kèm error.category) trở nên quan sát được.

Tổng kết

Ứng dụng giờ đã quan sát được: các trace và log truy vấn của back end được ghi lại trong ClickHouse và có thể khám phá trong ClickStack. Profile container-logs tùy chọn bổ sung stdout từ bộ ghi chuyến xe trên các host Linux tương thích. Telemetry đó là nền tảng cho phần công việc AI SRE tiếp theo.

Trạng thái kết thúc

Telemetry đang chảy vào ClickStack. Tiếp tục tới 06 AI SRE để agent của bạn xây dựng lên trên nó.