05 벤치마크와 컷오버

학습자 레슨 05 Benchmark and cutover에 대응하는 진행자용 안내입니다.

타이밍

다섯 단계에 걸쳐 약 45분. ClickHouse 대시보드 추가(Step 1, 스크립트 임포트로 몇 분), 벤치마크 실행(Step 2, 쿼리 일곱 개 x 3회 실행 x 엔진 두 개 — 몇 분이며 대부분 자동으로 진행되지만 그냥 지켜볼 만큼 짧습니다), 컷오버 자체(Step 3, 상호작용 — 프로듀서 중단, 델타 따라잡기, dbt 리프레시, ClickHouse 프로듀서 시작, 각각이 정해진 순서의 의도적인 단계), 패리티 검증(Step 4, 빠름), 그리고 teardown(Step 5)입니다.

TODO: 랩의 자체 자료에는 이 모듈의 총 45분 외에 단계별 타이밍이 없습니다 — 리허설에서 그 배분을 확인하세요. 특히 Step 3의 --resume 따라잡기 패스가 버퍼가 필요 없을 만큼 (랩 자체 설명에 따르면 수 초에서 수 분) 안정적으로 빠른지 확인하세요.

강의 흐름

• 이 모듈이 "준비됨"을 "마이그레이션됨"으로 바꿉니다. 모듈 03과 04가 데이터와 파이프라인을 증명했고, 이 모듈은 숫자(벤치마크)를 증명하고 쓰기 경로가 실제로 이동함(컷오버)을 증명합니다.
• 컷오버 순서는 형식이 아니라 여기서의 핵심 내용입니다. Snowflake 프로듀서 중단, --resume 실행으로 간격 메우기, dbt 리프레시, 그다음 ClickHouse 프로듀서 시작. 각 단계는 그 앞 단계에 의존합니다 — 순서를 어긴 실행이 바로 조용한 패리티 실패가 일어나는 방식입니다 (흔한 실패 사례 참고).
• 모듈 03의 원래 마이그레이션은 그렇지 않았는데 여기서 --resume이 빠른 이유를 명시적으로 말하세요. 이미 ClickHouse에 있는 max(pickup_at)을 워터마크로 삼아 델타만 가져오므로, 모듈 01부터 열려 있던 간격이 또 한 번의 40-50분 대량 전송이 아니라 수 초에서 수 분 안에 닫힙니다.
• 컷오버를 모듈 04의 agg_hourly_zone_trips 빈 상태와 연결하세요. 그 필터는 살아 있는 프로듀서의 행만 일치시켰기 때문에, ClickHouse 프로듀서가 시작되는 순간 랩 전체에서 처음으로 이 테이블이 채워집니다. 파트너들이 모듈 04부터 계속 물어온 질문에 대한 보상입니다.
• 이것이 서면 평가 직전의 마지막 모듈입니다 — Step 5의 teardown이 양쪽 클라우드 환경을 모두 삭제하니 migration-plan.md와 벤치마크 CSV를 이후에도 접근 가능한 곳에 보관하도록 강의실에 알려주세요.

흔한 실패 사례

• 파트너가 add_clickhouse_connection.sh를 실행하는 대신 Superset UI를 통해 대시보드 ZIP을 수동으로 임포트합니다. 커밋된 익스포트 파일에는 ClickHouse 호스트가 your-instance.clickhouse.cloud로 마스킹되어 있습니다. 스크립트는 임포트 전에 .env에서 URI를 패치하지만, 수동 UI 임포트는 플레이스홀더 호스트를 그대로 사용하므로 연결이 되지 않습니다. 이후 연결을 편집해 실제 CLICKHOUSE_HOST와 자격 증명을 가리키도록 하세요.
• 파트너가 Step 3의 --resume 따라잡기 패스를 건너뛰고 그대로 컷오버합니다. ClickHouse는 모듈 03의 원래 마이그레이션과 프로듀서가 멈춘 순간 사이의 간격에 들어온 행을 영구히 잃습니다 — 조용한 패리티 실패입니다. Step 4의 패리티 검사가 이를 잡기 위해 있지만 실행되어야만 유효합니다. Step 4를 실행하지 않고 곧바로 벤치마크 작성으로 넘어가는 파트너는 누락된 행을 알아채지 못합니다.
• 정리하려는 마음의 파트너가 이미 모듈 01이나 02에서 Snowflake 프로듀서를 멈췄습니다. 프로듀서가 연속으로 실행되지 않았다면 컷오버가 간격을 측정할 대상이 없습니다 — 이는 이 단계만이 아니라 컷오버 시연 전체를 망칩니다. 이미 일어났다면 정직한 해결책은 프로듀서를 다시 시작해 몇 분간 쓰게 해서 실제 간격을 만들고 진행하는 것입니다. 애초에 열린 적 없는 간격을 소급해서 시연할 방법은 없습니다.
• 패리티 검사가 실패합니다(차이가 0.01%보다 큼). 따라잡기 패스를 다시 실행하고 재검사하세요: python scripts/02_migrate_trips.py --resume 다음 bash scripts/01_verify_migration.sh.
• Superset이 403 Forbidden을 표시합니다. 세션 쿠키가 만료된 것입니다 — 로그아웃하고 http://localhost:8088에서 다시 로그인한 다음 superset/add_clickhouse_connection.sh를 다시 실행하세요.
• 벤치마크가 어떤 쿼리, 대개 Q7에 대해 N/A를 표시합니다. 벤치마크 스크립트가 ClickHouse에 접속하지 못한 것입니다 — CLICKHOUSE_HOST가 설정되어 있는지(source .clickhouse_state) 그리고 서비스가 실행 중인지 확인하세요.

초기화 절차

• 패리티 검사 실패: python scripts/02_migrate_trips.py --resume을 다시 실행한 다음 bash scripts/01_verify_migration.sh.
• 컷오버를 되돌려야 하는 경우(역방향 컷오버): docker stop nyc_taxi_ch_producer를 실행한 다음, workshop_public/snowflake_migration_lab/01-setup-snowflake/superset에서 docker-compose --env-file ../.env up -d producer로 Snowflake 프로듀서를 다시 띄우세요.
• 전체 환경 초기화: workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/에서 source .env && ./teardown.sh를 실행하면 ClickHouse Cloud 서비스와 (컷오버가 일어났다면) ClickHouse 프로듀서 컨테이너가 파괴됩니다. Snowflake는 이 스크립트가 건드리지 않습니다 — workshop_public/snowflake_migration_lab/01-setup-snowflake/에서 source .env && ./teardown.sh로 별도로 정리하세요.
• 어느 쪽 teardown이든 실행하기 전에 migration-plan.md와 벤치마크 CSV (scripts/benchmark_results_<timestamp>.csv)가 접근 가능한 곳에 저장되어 있는지 확인하세요 — 이후 양쪽 클라우드 환경은 사라지며, 모듈 06은 다른 것 없이 정확히 그 두 파일만 필요합니다.