05 Benchmark et bascule

Complément formateur du module participant 05 Benchmark et bascule.

Durée

Environ 45 minutes réparties en cinq étapes : ajout des tableaux de bord ClickHouse (étape 1, quelques minutes avec l’import scripté), exécution du benchmark (étape 2, sept requêtes multipliées par trois exécutions sur deux moteurs — quelques minutes, presque entièrement autonomes mais assez courtes pour les observer), bascule elle-même (étape 3, interactive : arrêter le producteur, rattraper le delta, actualiser dbt, démarrer le producteur ClickHouse, chaque action étant volontairement ordonnée), vérification de la parité (étape 4, rapide) et suppression des environnements (étape 5).

À FAIRE : la documentation du laboratoire ne précise pas la durée de chaque étape au-delà du total de 45 minutes. Confirmez la répartition pendant la répétition, en particulier que le passage de rattrapage --resume de l’étape 3 reste systématiquement assez rapide (de quelques secondes à quelques minutes, selon le laboratoire) pour ne pas nécessiter de marge supplémentaire.

Fil conducteur

• C’est le module qui transforme « préparé » en « migré ». Les modules 03 et 04 ont validé les données et le pipeline ; celui-ci valide un chiffre (le benchmark) et démontre le déplacement effectif du chemin d’écriture (la bascule).
• L’ordre de la bascule constitue le contenu du module, pas une formalité : arrêtez le producteur Snowflake, exécutez --resume pour refermer l’écart, actualisez dbt, puis démarrez le producteur ClickHouse. Chaque étape dépend de la précédente ; les exécuter dans le désordre produit précisément une erreur de parité silencieuse (voir Erreurs courantes).
• Expliquez pourquoi --resume est rapide ici alors que la migration initiale du module 03 ne l’était pas : le script part du max(pickup_at) déjà présent dans ClickHouse et ne récupère que le delta. Un écart ouvert depuis le module 01 se referme donc en quelques secondes ou minutes, et non par un nouveau transfert de 40 à 50 minutes.
• Reliez la bascule à l’état vide de agg_hourly_zone_trips au module 04 : elle est remplie pour la première fois lorsque le producteur ClickHouse démarre, car son filtre n’a jamais correspondu qu’aux lignes d’un producteur actif. C’est la réponse à la question que posent les partenaires depuis le module 04.
• C’est le dernier module avant l’évaluation écrite. Rappelez au groupe de conserver migration-plan.md et le CSV du benchmark dans un endroit accessible, car la suppression de l’étape 5 élimine les deux environnements cloud.

Erreurs courantes

• Un partenaire importe manuellement le ZIP des tableaux de bord dans l’interface Superset au lieu d’exécuter add_clickhouse_connection.sh. L’hôte ClickHouse de l’export enregistré a été remplacé par your-instance.clickhouse.cloud. Le script corrige l’URI à partir de .env avant l’import, tandis qu’un import manuel conserve l’hôte fictif et la connexion échoue. Demandez au partenaire de modifier ensuite la connexion afin d’utiliser le véritable CLICKHOUSE_HOST et les bons identifiants.
• Un partenaire saute le passage de rattrapage --resume à l’étape 3 et effectue tout de même la bascule. ClickHouse perd définitivement toutes les lignes arrivées entre la migration initiale du module 03 et l’arrêt du producteur : une erreur de parité silencieuse. La vérification de l’étape 4 est conçue pour la détecter, à condition d’être exécutée ; un partenaire qui passe directement au compte rendu du benchmark ne remarquera pas les lignes perdues.
• Le producteur Snowflake a déjà été arrêté dans le module 01 ou 02 par un partenaire soucieux de « ranger ». La bascule n’a aucun écart à mesurer si le producteur n’a pas tourné en continu ; cela invalide toute la démonstration, pas seulement cette étape. La correction honnête consiste à redémarrer le producteur, à le laisser écrire quelques minutes pour créer un écart réel, puis à poursuivre. Il est impossible de démontrer rétroactivement un écart qui n’a jamais existé.
• La vérification de parité échoue (écart supérieur à 0,01 %). Relancez le rattrapage puis la vérification : python scripts/02_migrate_trips.py --resume, puis bash scripts/01_verify_migration.sh.
• Superset affiche 403 Forbidden. Le cookie de session a expiré : déconnectez-vous, reconnectez-vous sur http://localhost:8088, puis relancez superset/add_clickhouse_connection.sh.
• Le benchmark affiche N/A pour une requête, le plus souvent Q7. Le script n’a pas réussi à se connecter à ClickHouse. Vérifiez que CLICKHOUSE_HOST est défini (source .clickhouse_state) et que le service fonctionne.

Étapes de réinitialisation

• Échec de la vérification de parité : relancez python scripts/02_migrate_trips.py --resume, puis bash scripts/01_verify_migration.sh.
• Annulation de la bascule (bascule inverse) : exécutez docker stop nyc_taxi_ch_producer, puis redémarrez le producteur Snowflake depuis workshop_public/snowflake_migration_lab/01-setup-snowflake/superset avec docker-compose --env-file ../.env up -d producer.
• Réinitialisation complète : source .env && ./teardown.sh depuis workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ détruit le service ClickHouse Cloud et le conteneur du producteur ClickHouse (si la bascule a eu lieu). Snowflake n’est pas touché par ce script : supprimez-le séparément avec source .env && ./teardown.sh depuis workshop_public/snowflake_migration_lab/01-setup-snowflake/.
• Avant toute suppression, vérifiez que migration-plan.md et le CSV du benchmark (scripts/benchmark_results_<timestamp>.csv) sont enregistrés dans un endroit accessible. Les deux environnements cloud disparaissent ensuite, et le module 06 a précisément besoin de ces deux fichiers, sans rien d’autre.