Breadcrumbs de Sentry: el rastro antes de un error
Breadcrumbs de Sentry
Breadcrumbs de Sentry: addBreadcrumb, filtros y límites | We.Inc
Cómo funcionan los breadcrumbs de Sentry en el SDK de JavaScript: breadcrumbs automáticos y manuales, el filtro beforeBreadcrumb, el valor por defecto de 100 en maxBreadcrumbs y la limpieza de datos.
Los breadcrumbs de Sentry son pequeños registros de lo que ocurrió justo antes de un error: clics, peticiones de red, mensajes de consola y cambios de página. El SDK recoge muchos automáticamente, tú añades los tuyos con Sentry.addBreadcrumb() y se adjuntan al siguiente evento de error. Por defecto, el SDK de JavaScript conserva los 100 más recientes.
Ajustes de breadcrumbs de un vistazo
Ajuste o llamada
Qué hace
Valor por defecto
maxBreadcrumbs
Cuántos breadcrumbs se conservan
beforeBreadcrumb
Edita o descarta cada breadcrumb antes de guardarlo
Sin definir
Sentry.addBreadcrumb()
Registra un breadcrumb propio
No aplica
fatal, error, warning, log, info o debug
Sin definir
Cuando un cliente se encuentra con un error en tu sitio, la traza de la pila dice dónde falló el código, pero no qué hizo antes. Los breadcrumbs cubren ese hueco. Esta guía trata el SDK de JavaScript para navegador; los demás SDK de Sentry siguen la misma idea con sus propios valores por defecto.
El SDK escucha clics y pulsaciones de teclas, peticiones fetch y XHR, llamadas a la consola y cambios de ubicación, y convierte cada uno en un breadcrumb.
Tu propio código puede añadir más con Sentry.addBreadcrumb(), por ejemplo tras un inicio de sesión o al aplicar un cupón.
Cada breadcrumb nuevo pasa primero por beforeBreadcrumb si lo has definido. Devolver null lo descarta.
El rastro conservado está limitado por maxBreadcrumbs; el SDK recorta los más antiguos cuando la lista supera el límite.
Cuando se captura un error, el rastro actual se adjunta a ese evento y se muestra en la página del issue.
Usa una categoría corta y estable, como auth, cart o payment, para poder filtrar el rastro en la página del issue.
Pon los detalles en data, no en el mensaje, para que aparezcan como campos.
Nunca pongas contraseñas, números de tarjeta ni direcciones completas en un breadcrumb. La propia guía de Sentry dice que no registres datos personales cuando los logs de consola se convierten en breadcrumbs.
Si la consola es ruidosa, descarta los breadcrumbs de consola en beforeBreadcrumb en lugar de bajar maxBreadcrumbs para todo.
Poner maxBreadcrumbs a 0 desactiva los breadcrumbs; el SDK sale antes con valores de 0 o menos.
Preguntas frecuentes
¿Cuál es el valor por defecto de maxBreadcrumbs?
100. La documentación de Sentry indica 100 por defecto para el SDK de JavaScript, y el código fuente del SDK usa el mismo número cuando la opción no está definida.
¿Qué breadcrumbs se registran automáticamente?
En el SDK de navegador: clics y pulsaciones de teclas en elementos del DOM, peticiones XHR y fetch, llamadas a la API de consola y todos los cambios de ubicación.
¿Qué claves puede tener un breadcrumb?
type, category, message, level, timestamp y data. La documentación dice que las demás claves se descartan durante el procesamiento.
¿Cómo evito que se registre un breadcrumb?
Define beforeBreadcrumb en Sentry.init. Recibe cada breadcrumb y una pista opcional, y puede devolver un breadcrumb modificado o null para descartarlo.
¿Los breadcrumbs se envían por separado?
No. Se guardan en memoria y se adjuntan al siguiente evento que envíe el SDK, como un error.
Breadcrumbs manuales que vale la pena añadir
Los breadcrumbs automáticos te dicen qué hizo el navegador. Los manuales te dicen qué hizo el flujo del negocio: un cliente eligió envío urgente, se aplicó un código de descuento, se eligió una fecha de reserva.
Son los momentos por los que primero pregunta alguien de soporte, así que registrarlos ahorra una ronda de preguntas.
Mantener fuera los datos personales
Los breadcrumbs a menudo recogen texto que no querías guardar: un correo en una línea de consola, una búsqueda en una URL. Límpialos en beforeBreadcrumb antes de que se guarden, y usa beforeSend para el resto del evento.
Sentry también ofrece limpieza de datos en el servidor configurable desde su interfaz, que actúa como segunda red.
Ejemplos de código
Añadir un breadcrumb manual
Registra un paso del negocio con una categoría, un mensaje corto, un nivel y campos extra en data.
Filtrar y limpiar breadcrumbs
Descarta el ruido de la consola, enmascara las direcciones de correo y deja escrito el límite por defecto para que sea fácil cambiarlo.
Simulador del rastro de breadcrumbs
Registra algunos eventos, ajusta las opciones y lanza un error para ver qué breadcrumbs viajarían con él. Es una simulación en tu navegador; no se envía nada a Sentry.