05 Benchmark e virada

Material de apoio ao instrutor para a aula do participante 05 Benchmark e virada.

Duração

Cerca de 45 minutos distribuídos em cinco etapas: adicionar os dashboards do ClickHouse (etapa 1, alguns minutos com a importação por script), executar o benchmark (etapa 2, sete consultas vezes três execuções vezes dois mecanismos — alguns minutos, quase todos autônomos, mas curtos o bastante para acompanhar), realizar a virada (etapa 3, interativa: interromper o produtor, atualizar a diferença, executar o dbt, iniciar o produtor do ClickHouse, cada ação deliberadamente nessa ordem), verificar a paridade (etapa 4, rápida) e desmontar (etapa 5).

PENDENTE: o material do laboratório não apresenta a duração de cada etapa além do total de 45 minutos do módulo. Confirme a distribuição durante o ensaio, principalmente se a passagem de atualização com --resume da etapa 3 é rápida o bastante de modo consistente (segundos a minutos, segundo a própria descrição do laboratório) para dispensar uma margem adicional.

Roteiro

• Este é o módulo que transforma “preparado” em “migrado”. Os módulos 03 e 04 validaram os dados e o pipeline; este valida um número (o benchmark) e prova que o caminho de gravação realmente muda (a virada).
• A ordem da virada é o conteúdo deste módulo, não uma formalidade: interrompa o produtor do Snowflake, execute --resume para fechar a lacuna, atualize o dbt e só então inicie o produtor do ClickHouse. Cada etapa depende da anterior. Executá-las fora de ordem é exatamente como se produz uma falha silenciosa de paridade (consulte Falhas comuns).
• Explique por que --resume é rápido aqui, ao contrário da migração original do módulo 03: ele usa como marca d'água o max(pickup_at) já presente no ClickHouse e busca apenas a diferença; assim, uma lacuna aberta desde o módulo 01 é fechada em segundos ou minutos, e não em outra transferência em massa de 40 a 50 minutos.
• Relacione a virada ao estado vazio de agg_hourly_zone_trips no módulo 04: ela é preenchida pela primeira vez em todo o laboratório quando o produtor do ClickHouse começa, pois seu filtro só corresponde a linhas do produtor em tempo real. Esta é a resposta à pergunta que os parceiros fazem desde o módulo 04.
• Este é o último módulo antes da avaliação escrita. Lembre a turma de guardar o migration-plan.md e o CSV do benchmark em um local acessível, pois a desmontagem da etapa 5 exclui os dois ambientes de nuvem.

Falhas comuns

• Um parceiro importa manualmente o ZIP do dashboard pela interface do Superset em vez de executar add_clickhouse_connection.sh. O host do ClickHouse foi ocultado como your-instance.clickhouse.cloud no arquivo de exportação versionado. O script substitui a URI a partir de .env antes da importação, mas uma importação manual pela interface usa o host fictício sem alterações e a conexão falhará. Peça que o parceiro edite a conexão depois para apontar ao CLICKHOUSE_HOST real e usar as credenciais corretas.
• Um parceiro pula a passagem de atualização --resume na etapa 3 e realiza a virada mesmo assim. O ClickHouse perde definitivamente todas as linhas gravadas no intervalo entre a migração original do módulo 03 e a interrupção do produtor: uma falha silenciosa de paridade. A verificação da etapa 4 foi criada para detectá-la, mas somente se for executada. Um parceiro que pula diretamente para o relatório do benchmark sem executar a etapa 4 não perceberá as linhas perdidas.
• O produtor do Snowflake já tinha sido interrompido no módulo 01 ou 02 por um parceiro que quis “organizar” o ambiente. A virada não tem uma lacuna para medir se o produtor nunca funcionou continuamente. Isso compromete toda a demonstração da virada, não apenas esta etapa. Se ocorreu, a correção honesta é reiniciar o produtor, deixá-lo gravar por alguns minutos para criar uma lacuna real e então prosseguir; não é possível demonstrar retroativamente uma lacuna que nunca existiu.
• A verificação de paridade falha (diferença superior a 0,01%). Execute novamente a atualização e verifique outra vez: python scripts/02_migrate_trips.py --resume e depois bash scripts/01_verify_migration.sh.
• O Superset mostra 403 Forbidden. O cookie da sessão expirou. Saia, entre novamente em http://localhost:8088 e execute superset/add_clickhouse_connection.sh outra vez.
• O benchmark mostra N/A para uma consulta, geralmente a Q7. O script de benchmark não conseguiu se conectar ao ClickHouse. Confirme que CLICKHOUSE_HOST está definido (source .clickhouse_state) e que o serviço está em execução.

Etapas de redefinição

• Se a verificação de paridade falhar: execute novamente python scripts/02_migrate_trips.py --resume e depois bash scripts/01_verify_migration.sh.
• Se for preciso desfazer a virada: execute docker stop nyc_taxi_ch_producer e então reative o produtor do Snowflake em workshop_public/snowflake_migration_lab/01-setup-snowflake/superset com docker-compose --env-file ../.env up -d producer.
• Para uma redefinição completa do ambiente: execute source .env && ./teardown.sh em workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ para destruir o serviço ClickHouse Cloud e o contêiner do produtor do ClickHouse (caso a virada tenha ocorrido). Esse script não afeta o Snowflake; desmonte-o separadamente com source .env && ./teardown.sh em workshop_public/snowflake_migration_lab/01-setup-snowflake/.
• Antes de executar qualquer desmontagem, confirme que migration-plan.md e o CSV do benchmark (scripts/benchmark_results_<timestamp>.csv) estão salvos em um local acessível. Depois disso, os dois ambientes de nuvem desaparecem, e o módulo 06 precisa exatamente desses dois arquivos, sem mais nada.