05 ClickStack

Tài liệu đồng hành của người điều phối cho bài học 05 ClickStack.

Thời lượng

Khoảng 15 phút. Telemetry phải tích luỹ trước phòng lab sự cố ở module 07, nên hãy khởi động collector sớm nhất mà module này cho phép và để nó chạy liên tục.

Nội dung dẫn giảng

• Managed ClickStack lưu telemetry trong ClickHouse Cloud; HyperDX là giao diện được host. Collector cục bộ chỉ chuyển tiếp dữ liệu. Hãy cho xem cả một trace request đầu-cuối và một bản ghi DEBUG ... ClickHouse query ok mới trong Log source.
• Hãy để học viên khởi động collector ở Bước 1 trước khi họ mở Managed ClickStack ở Bước 2. Việc này cho telemetry thời gian để đến và làm cho lần xem đầu tiên trên giao diện được host trở nên hữu ích.
• Trình chiếu một trace request đầu-cuối.

Lỗi thường gặp

• Cổng host OTLP 4317/4318 đã bị chiếm: hãy để họ đặt OTEL_GRPC_HOST_PORT / OTEL_HTTP_HOST_PORT trong .env.workshop (preflight gợi ý giá trị, ví dụ 24317/24318) rồi, từ bất kỳ vị trí nào bên trong repository đã clone, chạy cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh; back end tiếp cận collector trong cùng mạng nội bộ, nên việc đổi cổng là an toàn.
• Chưa khởi động overlay của collector (quên tham số -f docker-compose.otel.yml thứ hai), nên không có gì đến HyperDX.
• OTLP_AUTH_TOKEN không khớp, hoặc thiếu các biến CLICKHOUSE_* trong .env.workshop (collector dùng lại CLICKHOUSE_HOST/PORT/USER/PASSWORD để kết nối tới Cloud service).
• Chưa sinh ra lưu lượng nào; hãy để họ click qua cả hai dashboard.
• Trên Docker Desktop, bộ scraper tuỳ chọn --profile container-logs không mount được đường dẫn log của host (daemon nằm trong một VM); điều này là dự kiến. Log của backend vẫn đi qua OTLP. Chỉ dùng docker compose ... logs để chẩn đoán bộ chuyển tiếp nếu HyperDX trống.
• Sau khi overlay tạo lại backend, ứng dụng trước đây trả về 502 (nginx ở frontend cache IP cũ của backend). Frontend giờ phân giải lại theo từng request, nên nó tự lành trong khoảng 10 giây và không cần khởi động lại thủ công. Đã xác nhận đã sửa trong buổi tổng duyệt.
• Tham chiếu từ buổi tổng duyệt: pipeline telemetry đã được kiểm chứng đầu-cuối — các trace nyc-taxi-backend với các child span clickhouse.query mang theo db.statement / db.elapsed_ms / db.rows_returned. Đã xác nhận trong buổi tổng duyệt phòng sạch 2026-07.

Các bước khôi phục

• Khởi động lại với cả hai file compose: docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build.
• Trong Cloud console, mở service, chọn ClickStack, và mở lại giao diện được host nếu phiên SSO đã hết hạn.