O que fazer quando quebra

Selo de estado: Preview (teto atual do produto) · Curso ACD-260 — Arquitetura de solução · Aula 8 de 8 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai conduzir um incidente ponta a ponta com escopo de recuperação e comunicação honesta — e vai saber por que a primeira ação não é reexecutar.

Vídeo#

Identificador: acd-260-08-o-que-fazer-quando-quebra · Duração-alvo: 10 min · Tela: /dags.

Roteiro (capítulos):

1. 0:00–1:20 — 8h da manhã, o diretor abre o painel (/dashboards) — a Bronze de vendas falhou às 05:00 UTC (02:00 BRT).
2. 1:20–3:00 — O que o produto já fez por você (/dags) — a porta de dependência: a Silver não rodou, e isso é a boa notícia.
3. 3:00–4:30 — Comunicar antes de consertar (/dashboards) — o rótulo de frescor e a frase honesta sobre dado velho.
4. 4:30–6:30 — Diagnosticar e escolher o escopo (/dags) — os quatro escopos e a prévia que corresponde ao efeito.
5. 6:30–8:20 — Reprocessar período sem duplicar (/dags) — UTC, concorrência, recarga da tabela inteira, append.
6. 8:20–10:00 — Impacto antes de mexer, e contenção (/linhagem) — o que quebra se você renomear a coluna; kill switch e as três camadas ortogonais.

Conteúdo#

O incidente

A Comércio Aurora tem a agenda diária às 05:00 UTC (02:00 BRT). Hoje a Bronze de vendas falhou: a credencial do ERP expirou. Às 8h da manhã (BRT) o diretor abre o painel "Comercial — Aurora" para a reunião de 8h30.

Essa é a hora em que uma arquitetura mostra o que vale. A pergunta não é "como eu rodo de novo" — é "o que o diretor está vendo neste momento, e ele sabe o que está vendo?"

O que o produto já fez por você

Uma execução não é uma lista de tarefas: é um grafo. A Bronze lê a fonte, a Silver lê a Bronze, a Gold lê a Silver. E existe uma porta de dependência:

A camada seguinte NÃO roda quando a origem falhou. Se a Bronze de vendas falhou nesta execução, a Silver que depende dela não executa — mesmo que a tabela Bronze exista no datalake com a carga de ontem. Ela aparece como bloqueada por dependência, com o motivo.

Isso parece uma perda e é uma proteção: antes dessa regra, a Silver "passava" lendo dado velho e reportava um número que não correspondia à carga do dia. A regra mora num único módulo e vale igual na execução agendada e na manual.

Consequência de desenho: o painel do diretor mostra o dado de ontem, com o rótulo de frescor — não um número novo e errado. Um pipeline sem dependência declarada não tem essa proteção; por isso declarar depende de pela tabela de destino da tarefa anterior (não pelo nome do arquivo) é parte do desenho, não detalhe de implementação. Quando o apelido casa duas Bronzes (clientes.csv e clientes.json), o produto não escolhe: bloqueia se qualquer uma falhou e registra a ambiguidade.

Primeira ação: comunicar, não consertar

A tentação é abrir o pipeline e clicar em reexecutar. A ordem correta inverte isso, porque a reunião é às 8h30 e o conserto pode levar mais que isso:

1. Avise quem decide, com a frase honesta. "O painel está com o dado de ontem: a carga das 2h falhou por credencial expirada do ERP. O número de ontem está correto e é o que está na tela; o de hoje sai depois que a conexão for corrigida. Eu aviso quando atualizar." Isso é melhor que silêncio e infinitamente melhor que um número novo e errado.
2. Mostre onde está escrito. O rótulo de frescor do painel diz a última atualização; em Import, o painel reflete o último refresh agendado, não o estado atual da base.
3. Só então diagnostique.

Diagnosticar antes de reexecutar

Não reexecute antes de entender a causa. Uma credencial expirada não se resolve repetindo a tarefa: corrija a conexão primeiro. Leia a tentativa correta (execução → tarefa → tentativa → log) antes de escolher qualquer coisa.

E saiba o que a recuperação não faz: marcar uma tarefa como bem-sucedida muda o estado da execução, não o conteúdo do destino. Use isso só quando souber que o dado já está correto por outro caminho — nunca como forma de "resolver" uma carga que não aconteceu.

Escolher o escopo

Na tela da execução, Recuperar… mostra, antes de confirmar, exatamente o que vai rodar. Se a prévia mostra uma tarefa, ela roda; se não mostra, ela não roda.

Reprocessar período tem regras que você precisa saber antes de prometer prazo: exige Do dia e Até o dia, inclusive, em UTC — o produto não inventa "últimos N dias" a partir da agenda, e sem intervalo a ação fica indisponível com o motivo à vista. O motor recusa reprocessar enquanto houver execução em andamento no mesmo pipeline. E há dois casos que exigem reconhecimento explícito:

• Pipeline que não sabe recortar o período: o reprocessamento vira recarga da tabela inteira, e a tela exige uma caixa de reconhecimento antes de executar. Quando o pipeline sabe recortar, a escrita apaga só as linhas do período antes de acrescentar (idempotente dentro da janela).
• Tarefa de carga append no recorte: como a operação é INSERT e não há chave para deduplicar, a tela pede confirmação separada de que você aceita duplicar linhas.

Por isso o modo de carga entra na conversa de incidente: ele decide se reprocessar substitui ou acrescenta. Não existe "mesclar".

Antes de mexer na estrutura

Metade dos incidentes não nasce de falha de carga: nasce de alguém renomeando uma coluna. Antes de qualquer mudança estrutural, use linhagem e impacto: escolha a tabela e veja o efeito reverso — painéis afetados, relatórios afetados, tabelas derivadas e pipelines a revisar. O mapa é montado do SQL de cada visual, então é o que está rodando de verdade, não um desenho mantido à mão. Na Aurora, selecionar aurora_silver.vendas mostra quem depende dela antes de a terça-feira revelar.

O produto também detecta schema drift: coluna/tabela nova é info (aditivo, não quebra); coluna removida ou tipo mudado é atencao — e o mart que a lê é marcado como "quebra" em vez de produzir número errado em silêncio.

Kill switch: três camadas ortogonais

Quando o incidente é de exposição, não de carga, o instrumento é outro. Três verificações independentes decidem se algo acontece:

O desligamento permite conter sem derrubar: matar api.v1 ou o painel público e embed corta a exposição externa sem tocar no dado interno — os painéis internos seguem no ar. A ordem de decisão é kill global, kill por capacidade, config versionada (rollout %, allowlist, override, validade) e, por último, o desligamento de emergência, que sempre vence, inclusive sobre config custom, e tem efeito imediato, sem redeploy. Config ilegível ⇒ a capacidade fecha — nunca "abre no escuro".

Duas honestidades para o desenho: o acionamento é operacional/de plataforma, não é um botão self-service por workspace hoje; e o padrão efetivo é "exposta" — nenhuma capacidade do catálogo nasce desligada, o controle acontece pelo desligamento e pelos limites. Quem quer postura conservadora precisa pedir, não assumir.

Erros comuns de condução

• Reexecutar antes de diagnosticar. Repetir não conserta credencial expirada.
• Consertar antes de comunicar. Quem decide prefere dado velho rotulado a surpresa na reunião.
• Confundir "marcar sucesso" com produzir dado. Muda o estado, não o destino.
• Reprocessar período sem olhar o modo de carga. append sem chave duplica por definição.
• Esquecer que o período é UTC e inclusive. Três horas de diferença é um dia inteiro errado.
• Renomear coluna sem análise de impacto. O painel do cliente para na terça.
• Tratar kill switch como inadimplência. São camadas ortogonais; o diagnóstico é diferente.

Faça você mesmo#

O produto desta aula é um artefato de decisão: um plano de incidente de uma página — não um clique. Use /dags, /linhagem e /dashboards no workspace de treino para localizar cada tela que o plano cita.

1. Escreva a lista de avisos: quem é avisado, por qual canal e em quanto tempo, quando a carga da madrugada falha.
2. Escreva a frase de comunicação honesta sobre dado velho — a que você mandaria às 7h30, com o que está correto, o que está velho e quando atualiza.
3. Monte a tabela sintoma → escopo, com as quatro opções de recuperação e um exemplo de cada.
4. Escreva o pré-requisito de reprocessar período: os dois campos em UTC, a recusa por concorrência e os dois reconhecimentos explícitos (tabela inteira; append).
5. Escreva a regra de diagnóstico antes de reexecutar com dois exemplos de causa que repetir não resolve.
6. Abra /linhagem, rode a análise de impacto de uma tabela Silver e cole no plano a lista do que depende dela.
7. Escreva a seção de contenção: o que se desliga (exposição externa) sem derrubar o BI interno, e quem aciona — lembrando que hoje o acionamento é operacional.
8. Feche com a revisão pós-incidente: a dependência que faltava declarar, o depende de corrigido pela tabela de destino, e o que muda na agenda.

Você terminou quando: a página responde, sem consultar ninguém, "quem eu aviso", "o que eu digo", "qual escopo eu uso" e "o que eu desligo" — e inclui a frase que você diria ao diretor às 7h30.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

• orquestracao/recuperar-uma-falha
• orquestracao/dependencias-entre-pipelines
• orquestracao/agenda-e-fuso
• administracao/capacidades-kill-switch
• administracao/linhagem-e-impacto

Capacidades ensinadas#

C01.4 · C01.6 · C11.5 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".