05 Benchmark và cutover

Tài liệu đồng hành của người hướng dẫn cho bài học của học viên 05 Benchmark và cutover.

Thời lượng

Khoảng 45 phút cho năm bước: thêm các dashboard ClickHouse (Bước 1, khoảng vài phút qua script import), chạy benchmark (Bước 2, bảy câu truy vấn nhân ba lần chạy nhân hai engine — vài phút, phần lớn tự chạy nhưng ngắn đủ để chỉ cần ngồi xem), bản thân việc cutover (Bước 3, có tương tác — dừng producer, bù phần delta, refresh dbt, khởi động producer ClickHouse, mỗi việc là một bước có chủ đích theo đúng trình tự), kiểm tra parity (Bước 4, nhanh), và teardown (Bước 5).

TODO: tài liệu của chính lab không cho thời lượng theo từng bước, chỉ có tổng 45 phút cho module — hãy xác nhận cách chia trong buổi tổng duyệt, đặc biệt là liệu lượt bù bằng --resume ở Bước 3 có nhanh một cách đáng tin cậy (vài giây tới vài phút, theo mô tả của chính lab) đến mức không cần thời gian đệm nào hay không.

Nội dung trình bày

• Đây là module biến "đã chuẩn bị" thành "đã migrate." Module 03 và 04 đã chứng minh dữ liệu và pipeline; module này chứng minh một con số (benchmark) và chứng minh đường ghi dữ liệu thực sự chuyển được (cutover).
• Trình tự cutover chính là nội dung ở đây, không phải một thủ tục hình thức: dừng producer trên Snowflake, chạy --resume để đóng khoảng chênh lệch, refresh dbt, rồi khởi động producer ClickHouse. Mỗi bước phụ thuộc vào bước trước — chạy sai thứ tự chính là cách một lỗi parity âm thầm xảy ra (xem Các lỗi thường gặp).
• Hãy nói rõ vì sao --resume nhanh ở đây trong khi lần migration ban đầu ở module 03 thì không: nó watermark theo max(pickup_at) hiện có trong ClickHouse và chỉ lấy phần delta, nên một khoảng chênh lệch đã mở từ module 01 sẽ được đóng lại trong vài giây tới vài phút, không phải thêm một lần truyền hàng loạt 40-50 phút nữa.
• Nối việc cutover trở lại với trạng thái rỗng của agg_hourly_zone_trips từ module 04: nó được điền dữ liệu lần đầu tiên trong cả lab ngay khi producer ClickHouse khởi động, bởi vì bộ lọc của nó chỉ khớp với các dòng do producer đang chạy sinh ra. Đây là phần thưởng cho câu hỏi mà các đối tác đã hỏi từ module 04.
• Đây là module cuối trước bài đánh giá viết — hãy nhắc lớp giữ migration-plan.md và tệp CSV của benchmark ở một nơi còn truy cập được sau khi teardown ở Bước 5 xóa cả hai môi trường cloud.

Các lỗi thường gặp

• Một đối tác import tệp ZIP dashboard thủ công qua Superset UI thay vì chạy add_clickhouse_connection.sh. Bản export được commit đã ẩn host ClickHouse thành your-instance.clickhouse.cloud; script sẽ vá lại URI từ .env trước khi import, nhưng một lần import thủ công qua UI sẽ dùng nguyên host giữ chỗ đó và kết nối sẽ không kết nối được. Hãy cho họ sửa lại kết nối sau đó để trỏ tới CLICKHOUSE_HOST thật cùng thông tin đăng nhập.
• Một đối tác bỏ qua lượt bù --resume ở Bước 3 và vẫn cutover. ClickHouse sẽ mất vĩnh viễn mọi dòng đã rơi vào khoảng chênh lệch giữa lần migration ban đầu ở module 03 và thời điểm producer dừng — một lỗi parity âm thầm. Bước 4 có phần kiểm tra parity được thiết kế để bắt lỗi này, nhưng chỉ khi nó được chạy; một đối tác nhảy thẳng sang phần viết kết quả benchmark mà không chạy Bước 4 sẽ không nhận ra những dòng bị mất.
• Producer trên Snowflake đã bị dừng từ trước, ở module 01 hoặc 02, bởi một đối tác thích dọn dẹp cho gọn. Cutover sẽ không có gì để đo khoảng chênh lệch nếu producer chưa từng chạy liên tục — điều này phá vỡ toàn bộ phần trình diễn cutover, không chỉ riêng bước này. Nếu chuyện đó đã xảy ra, cách sửa trung thực là khởi động lại producer, để nó ghi vài phút để tạo ra một khoảng chênh lệch thật, rồi tiếp tục; không có cách nào trình diễn hồi tố một khoảng chênh lệch chưa từng được mở ra.
• Kiểm tra parity thất bại (khác biệt lớn hơn 0.01%). Chạy lại lượt bù rồi kiểm tra lại: python scripts/02_migrate_trips.py --resume rồi bash scripts/01_verify_migration.sh.
• Superset báo 403 Forbidden. Cookie phiên đã hết hạn — hãy đăng xuất, đăng nhập lại tại http://localhost:8088, rồi chạy lại superset/add_clickhouse_connection.sh.
• Benchmark hiển thị N/A cho một câu truy vấn, thường nhất là Q7. Script benchmark không kết nối được tới ClickHouse — hãy xác nhận CLICKHOUSE_HOST đã được đặt (source .clickhouse_state) và service đang chạy.

Các bước reset

• Kiểm tra parity thất bại: chạy lại python scripts/02_migrate_trips.py --resume rồi bash scripts/01_verify_migration.sh.
• Cần hoàn tác cutover (cutover ngược): docker stop nyc_taxi_ch_producer, sau đó đưa producer trên Snowflake trở lại từ workshop_public/snowflake_migration_lab/01-setup-snowflake/superset bằng docker-compose --env-file ../.env up -d producer.
• Reset toàn bộ môi trường: source .env && ./teardown.sh từ workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ phá hủy service ClickHouse Cloud và container producer ClickHouse (nếu cutover đã diễn ra); script này không ảnh hưởng tới Snowflake — hãy teardown phía đó riêng bằng source .env && ./teardown.sh từ workshop_public/snowflake_migration_lab/01-setup-snowflake/.
• Trước khi chạy bất kỳ teardown nào, hãy xác nhận migration-plan.md và tệp CSV của benchmark (scripts/benchmark_results_<timestamp>.csv) đã được lưu ở một nơi còn truy cập được — cả hai môi trường cloud sẽ biến mất sau bước này, và module 06 cần đúng hai tệp đó và không cần gì khác.