Breadcrumbs do Sentry: addBreadcrumb, filtros e limites | We.Inc
Como funcionam os breadcrumbs do Sentry no SDK JavaScript: breadcrumbs automáticos e manuais, filtro com beforeBreadcrumb, o padrão de 100 do maxBreadcrumbs e limpeza de dados.
Breadcrumbs no Sentry são pequenos registros do que aconteceu logo antes de um erro: cliques, requisições de rede, mensagens do console e mudanças de página. O SDK coleta muitos deles automaticamente, você adiciona os seus com Sentry.addBreadcrumb(), e eles são anexados ao próximo evento de erro. Por padrão o SDK JavaScript guarda os 100 mais recentes.
Configurações de breadcrumbs em resumo
Configuração ou chamada
O que faz
Padrão
maxBreadcrumbs
Quantos breadcrumbs são guardados
beforeBreadcrumb
Edita ou descarta cada breadcrumb antes de ele ser guardado
Não definido
Sentry.addBreadcrumb()
Registra o seu próprio breadcrumb
Não se aplica
fatal, error, warning, log, info ou debug
Não definido
Quando um cliente encontra um erro no seu site, o stack trace diz onde o código quebrou, mas não o que ele fez antes. Os breadcrumbs preenchem essa lacuna. Este guia cobre o SDK JavaScript para navegador; os outros SDKs do Sentry seguem a mesma ideia com os próprios padrões.
O SDK escuta cliques e teclas, requisições fetch e XHR, chamadas ao console e mudanças de endereço, e transforma cada uma em um breadcrumb.
O seu código pode adicionar mais com Sentry.addBreadcrumb(), por exemplo depois de um login ou da aplicação de um cupom.
Cada novo breadcrumb passa primeiro pelo beforeBreadcrumb, se você o definiu. Retornar null o descarta.
O rastro guardado tem o limite de maxBreadcrumbs; o SDK corta os mais antigos quando a lista passa do limite.
Quando um erro é capturado, o rastro atual é anexado a esse evento e aparece na página da issue.
Use uma categoria curta e estável, como auth, cart ou payment, para poder filtrar o rastro na página da issue.
Coloque os detalhes em data, não na mensagem, para eles aparecerem como campos.
Nunca coloque senhas, números de cartão ou endereços completos em um breadcrumb. A própria orientação do Sentry diz para não registrar dados pessoais quando os logs do console viram breadcrumbs.
Se o console é barulhento, descarte os breadcrumbs de console no beforeBreadcrumb em vez de reduzir o maxBreadcrumbs para tudo.
Definir maxBreadcrumbs como 0 desliga os breadcrumbs; o SDK retorna antes para valores iguais ou menores que 0.
Perguntas frequentes
Qual é o padrão do maxBreadcrumbs?
100. A documentação do Sentry indica o padrão de 100 para o SDK JavaScript, e o código-fonte do SDK usa o mesmo número quando a opção não é definida.
Quais breadcrumbs são registrados automaticamente?
No SDK para navegador: cliques e teclas em elementos do DOM, requisições XHR e fetch, chamadas à API do console e todas as mudanças de endereço.
Quais chaves um breadcrumb pode ter?
type, category, message, level, timestamp e data. A documentação diz que outras chaves são descartadas durante o processamento.
Como impeço que um breadcrumb seja registrado?
Defina beforeBreadcrumb no Sentry.init. Ele recebe cada breadcrumb e um hint opcional, e pode retornar um breadcrumb alterado ou null para descartá-lo.
Os breadcrumbs são enviados sozinhos?
Não. Eles ficam na memória e são anexados ao próximo evento que o SDK envia, como um erro.
Breadcrumbs manuais que vale adicionar
Os breadcrumbs automáticos contam o que o navegador fez. Os manuais contam o que o fluxo do negócio fez: um cliente escolheu frete expresso, um código de desconto foi aplicado, uma data de reserva foi escolhida.
Esses são os momentos sobre os quais o suporte pergunta primeiro, então registrá-los economiza uma rodada de perguntas.
Como manter os dados pessoais de fora
Os breadcrumbs costumam capturar textos que você não queria guardar: um e-mail em uma linha do console, uma busca em uma URL. Limpe-os no beforeBreadcrumb antes de serem guardados e use o beforeSend para o restante do evento.
O Sentry também oferece limpeza de dados no servidor, configurada na interface dele, que funciona como uma segunda rede de proteção.
Exemplos de código
Adicionar um breadcrumb manual
Registre uma etapa do negócio com uma categoria, uma mensagem curta, um nível e campos extras em data.
Filtrar e limpar breadcrumbs
Descarte o ruído do console, mascare endereços de e-mail e deixe o limite padrão escrito para ficar fácil de mudar.
Simulador de rastro de breadcrumbs
Registre alguns eventos, defina as opções e depois dispare um erro para ver quais breadcrumbs iriam junto com ele. É uma simulação no seu navegador; nada é enviado ao Sentry.