O Caminho para o Erro: A Importância dos 'Breadcrumbs' no Monitoramento Frontend

Olá a todos. Neste artigo, exploraremos como o rastreador de erros open-source Hawk pode ser utilizado para reconstruir a cadeia de eventos que antecedem um erro, permitindo uma compreensão mais rápida do que exatamente levou a uma falha na aplicação.

Imagine uma situação comum: um usuário entra em contato com o suporte relatando que, ao clicar em "Pagar", nada acontece. O sistema de monitoramento registra um erro. Sabemos onde ocorreu no código, vemos o URL da página, o navegador, o dispositivo e o ambiente. No entanto, a questão fundamental permanece: o que exatamente o usuário estava fazendo antes do erro? Ele clicou em "Pagar" imediatamente? Antes disso, ele alterou o método de entrega? Atualizou a página? Clicou no botão várias vezes? Houve alguma requisição falha à API antes do erro? Sem essa sequência, a investigação frequentemente se transforma em um jogo de adivinhação: o erro existe, mas o caminho para ele é invisível.

O Problema da Investigação Convencional

Enquanto o stack trace responde à pergunta "onde o erro ocorreu", os 'breadcrumbs' respondem a "como a aplicação chegou até ele". É essa informação que ajuda a encontrar e corrigir as causas das falhas mais rapidamente. Por exemplo, um evento pode exibir:

• Página: /checkout
• Erro no handler de pagamento
• Navegador do usuário
• Hora do erro

No entanto, pode ser obscuro:

• De qual página o usuário veio?
• Houve uma requisição anterior para calcular o custo?
• O endereço de entrega foi salvo com sucesso?
• Qual cenário específico levou à falha?

Isso resulta em uma situação onde vemos o erro em si, mas não o caminho que levou a ele. É exatamente este problema que os 'breadcrumbs' (ou "migalhas de pão") resolvem.

O Que São 'Breadcrumbs'?

'Breadcrumbs' são uma cadeia de eventos que ocorreram antes de um erro. Eles podem incluir:

• Transições entre páginas
• Cliques do usuário
• Requisições de rede
• Respostas de API
• Eventos de lógica de negócio
• Estados importantes da interface do usuário

Em vez de uma única mensagem como "algo quebrou no checkout", a equipe recebe uma sequência de ações que levaram a esse ponto.

Como Isso Funciona na Prática

Consideremos o cenário de pagamento. Um usuário abre o carrinho, navega para o checkout, seleciona o endereço de entrega, clica em "Pagar", e então a aplicação envia requisições para salvar o endereço e criar o pagamento. Em seguida, ocorre um erro.

navigation: /cart → /checkout
200 GET /api/checkout/order
ui: click "Salvar endereço"
400 POST /api/checkout/address
ui: click "Pagar"
logic: payment step submitted
logic: payment create skipped — address not saved
error: Payment failed

Os eventos na cadeia são dispostos de baixo para cima: do primeiro ao subsequente. Aqui reside a causa do problema: o pedido foi carregado normalmente, mas ao salvar o endereço de entrega, ocorreu um erro 400, e a interface não bloqueou o botão "Pagar". O usuário chegou à etapa de pagamento com um pedido incompleto, o que levou a um erro no handler de pagamento. A raiz do problema não está no botão "Pagar", mas sim antes: o endereço de entrega não foi salvo, e a UI não reagiu ao erro da API. Os 'breadcrumbs' mostram onde o cenário deu errado – antes mesmo do erro final.

O Que é Coletado Automaticamente

Eventos do navegador que são registrados nos 'breadcrumbs' incluem:

• Transições entre páginas
• Cliques em elementos
• Requisições fetch/XHR
• Informações básicas sobre o navegador e o ambiente

Esses eventos já fornecem um contexto útil. Se houve uma requisição à API antes do erro, ela pode ser vista na cadeia. Se o usuário clicou várias vezes no mesmo botão, isso também será visível.

O Que Deve Ser Adicionado Manualmente

O monitoramento pode registrar um clique em um botão, mas não sabe que, para o seu sistema, esse clique significa a transição para o pagamento, a confirmação da entrega ou o envio de um formulário. Portanto, em locais importantes, vale a pena adicionar seus próprios 'breadcrumbs':

• Transição entre etapas de um formulário
• Envio de um pedido
• Seleção de uma tarifa
• Aplicação de um código promocional
• Salvamento bem-sucedido de um endereço
• Início do processo de pagamento
• Recebimento de uma resposta do serviço de pagamento

Por exemplo:

javascript
hawk.breadcrumbs.add({
  timestamp: Date.now(),
  type: "logic",
  category: "checkout.step",
  level: "info",
  message: "Usuário avançou para o pagamento",
  data: {
    step: "payment",
    orderId: order.id,
  },
});

Ou para uma requisição:

javascript
hawk.breadcrumbs.add({
  timestamp: Date.now(),
  type: "request",
  category: "fetch",
  level: "error",
  message: "POST /api/checkout/address 400",
  data: {
    method: "POST",
    url: "/api/checkout/address",
    status: 400,
    reason: "address_validation_failed",
  },
});

Esses eventos tornam a investigação mais clara: a equipe vê não apenas uma cadeia técnica, mas um cenário significativo.

'Breadcrumbs' no Backend

Os 'breadcrumbs' também ajudam a mostrar a sequência de operações no lado do servidor. Por exemplo:

• Chamadas de métodos de API
• Requisições ao banco de dados
• Chamadas a serviços externos
• Interações com o nível de domínio
• Parsing e processamento de dados
• Lógica customizada

Geralmente, fragmentos de 'breadcrumbs' no backend são definidos manualmente usando o método breadcrumbs.add().

Conclusão

Os 'breadcrumbs' não substituem as informações de erro, mas adicionam contexto a elas. O erro em si responde à pergunta: "onde algo quebrou?". Os 'breadcrumbs' ajudam a responder a outra pergunta: "como o usuário chegou até aqui?". Para a equipe, isso significa menos suposições, menos reprodução manual e um caminho mais curto do alerta à correção do bug. Os 'breadcrumbs' ajudam a identificar e entender as causas dos erros mais rapidamente, reduzindo tanto o MTTD (Mean Time to Detect) quanto o MTTR (Mean Time to Resolve) — métricas chave para a eficiência do processo de tratamento de incidentes. Os desenvolvedores percebem o problema mais cedo, encontram sua origem mais rapidamente e lançam correções mais depressa.