Seguimiento de excepciones

El seguimiento de excepciones es el corazón de Quiet Guard: cada error lanzado por su aplicación se captura, se agrupa y se sigue a lo largo de todo su ciclo de vida. Se llega abriendo un proyecto en el panel /app, pestaña Incidencias.

Cómo funciona la ingesta

Su cliente envía (POST) un payload de excepción a /api/v1/ingest, autenticado con la clave de proyecto. El servidor lo valida, aplica la cuota mensual de su equipo y lo pasa al ingestor. Una llamada correcta devuelve 202 Accepted con el identificador público de la issue. La forma completa del payload está documentada en la referencia de la API de ingesta.

Cada excepción aceptada se convierte en una ocurrencia. Las ocurrencias se agrupan en incidencias.

Agrupación por huella en incidencias

En lugar de almacenar miles de errores idénticos como filas separadas, Quiet Guard los agrupa. Se calcula una huella (fingerprint) determinista a partir de:

• el proyecto,
• la clase de la excepción,
• el archivo (ruta normalizada), y
• la línea.

Todas las ocurrencias que comparten una huella se agrupan en una sola issue, con un contador de ocurrencias que ningún envío simultáneo pierde, la fecha en que se vio por primera vez y la de la última.

¿Por qué normalizar la ruta? Las herramientas de despliegue suelen servir la aplicación desde un directorio con marca de tiempo (por ejemplo /releases/20260628/...). La huella elimina ese ruido, conservando la ruta a partir del primer marcador /app/, /src/ o /vendor/, para que el mismo error se agrupe de un despliegue a otro en vez de fragmentarse en cada release.

Ocurrencias

Abra una issue para ver su página de detalle: la clase y el mensaje agrupados, el lugar donde se produce, el número de veces que se ha visto, y la lista de ocurrencias individuales. Cada ocurrencia lleva su propia traza, su contexto de petición, su entorno y su release, capturados en el momento en que se produjo.

La página de detalle añade seis elementos además de la traza. Una sección Petición muestra la dirección, el método HTTP, el usuario conectado y el entorno de ejecución PHP/Laravel capturados con la última ocurrencia; para un equipo con el almacenamiento cifrado activado, muestra en su lugar un espacio reservado bloqueado, nunca la dirección ni el usuario, hasta que desbloquee el cifrado en su navegador desde la página Cifrado. Dos contadores, Últimas 24 h y Últimos 7 días, junto con las listas de Entornos y Versiones afectados en los últimos 7 días, acompañan el total de ocurrencias. Un gráfico Catorce días de ocurrencias reparte cada ocurrencia por día, para hacer coincidir un pico con un despliegue. Una línea En su código nombra la primera línea de la traza que no pertenece a una dependencia, para no tener que recorrer las líneas del framework antes de encontrar dónde falló su código. Cuando el proyecto está conectado a GitHub y su plan lo permite, una acción Historial del archivo lista los cinco commits más recientes que modificaron ese archivo, del más reciente al más antiguo. Por último, si el proyecto sigue las issues de su repositorio, dos acciones, Abrir una issue de GitHub y Vincular una issue de GitHub, asocian la incidencia a un informe del repositorio, y la vista general muestra después la issue vinculada con su estado.

La traza de llamadas

A partir de la versión 0.3 de los clientes, la sección Última traza de llamadas se lee como la propia página de error de Laravel:

• los marcos se listan a un lado, el punto de lanzamiento primero (Lanzada aquí): la línea que lanzó la excepción viaja ahora como marco cero, mientras que la traza de PHP empieza en el llamador y nunca la contuvo;
• las series de marcos de dependencias se pliegan en una sola fila con el nombre del paquete ("7 marcos de laravel/framework"), que se despliega con un clic;
• junto a la lista, el detalle del marco seleccionado: la llamada, la ruta completa y el fragmento de código alrededor de la línea que falló, con esa línea marcada;
• cuando el proyecto está conectado a GitHub, un enlace Abrir este archivo en GitHub apunta al archivo en el commit desplegado: el que resuelve la release de la ocurrencia, o si no la rama por defecto del repositorio.

El fragmento lo lee el cliente en el archivo que se ejecutó: las cinco líneas a cada lado de la línea del marco, como máximo diez marcos por informe, y nunca para una dependencia (cualquier ruta que contenga /vendor/). Una línea que nombra una clave de la lista de enmascaramiento (password, secret, token, passphrase...) o una de las palabras key, auth, credential, salt, private, dsn, bearer, sk_, pk_, y le da un valor, se sustituye entera por [scrubbed], porque el código fuente es donde vive un secreto escrito en duro: una asignación ($secret = ..., 'api_key' => ...), a partir de la versión 0.3.1 un índice nombrado entre comillas ($headers['Authorization'] = ...), una llamada cuyo primer argumento es un literal (setApiKey('...')), o una comparación con == o === cuyo nombre está a la izquierda ($token === '...'), cuyo otro miembro puede ser el propio secreto; !== y un literal a la izquierda ('...' === $token) no cuentan. Una línea que solo usa el nombre se queda (Hash::check($password, $hash), y a partir de la versión 0.3.1 Auth::user()), y un literal que no nombra ninguna viaja tal cual; la regla completa está en el enmascaramiento del núcleo. Para dejar de enviarlo: MONITOR_CODE_SNIPPETS=false con el SDK de Laravel, code_snippets: false en el bundle de Symfony, o la clave de opción code_snippets del plugin de WordPress. Un marco sin fragmento lo indica, venga de un cliente más antiguo o de una dependencia. Con el almacenamiento cifrado, los fragmentos se sellan en reposo junto con el resto de la traza.

Resolver, ignorar, reabrir

Cada issue tiene un estado:

• Abierta: activa, requiere atención (estado por defecto de una issue nueva).
• Resuelta: usted la ha corregido; sale de la lista activa.
• Ignorada: ruido que no quiere tratar; se conserva pero silenciada.

Se pasa de un estado a otro mediante las acciones de la lista de incidencias y de la página de detalle. Los filtros permiten centrarse, por ejemplo, solo en las incidencias abiertas.

Reapertura por regresión

Si una incidencia está resuelta y el mismo error vuelve a producirse, Quiet Guard lo trata como una regresión: la incidencia vuelve automáticamente al estado abierta en la siguiente ocurrencia, y se dispara una alerta issue.reopened hacia los canales de notificación suscritos. No hace falta vigilar las incidencias resueltas: si vuelven, se le avisará.

Correlación release → commit

Aquí es donde los datos de GitHub rinden. Cuando una ocurrencia lleva una release (un SHA de commit, enviado en context.release) y el proyecto está conectado a GitHub, Quiet Guard asocia esa release con el commit sincronizado exacto. Desde la issue puede saltar directamente al commit que desplegó el código defectuoso, cerrando el círculo entre el error visto en producción y el cambio que lo causó.

Tenga en cuenta: la correlación de release solo se resuelve cuando el valor de release es un SHA de commit hexadecimal y el commit correspondiente ha sido sincronizado desde GitHub.

Flujo de triaje

La pestaña Incidencias de un proyecto se abre en vista de triaje: el filtro de estado viene preajustado en Abierta, como indica la línea de filtros activos encima de las filas; los demás filtros están tras el botón del embudo y se aplican en cuanto se eligen. La columna 24 h cuenta las ocurrencias de cada incidencia durante el último día, detecte la ráfaga en curso, no la incidencia ruidosa de la semana pasada. Seleccione varias incidencias para resolverlas o ignorarlas en una sola acción.

El triaje en todos los proyectos

Una agencia responde de una cartera, no de una sola aplicación. La entrada Incidencias de la barra lateral reúne todas las incidencias de todos los proyectos del equipo, con una columna Proyecto y un filtro Proyecto, y se abre ordenada por las últimas 24 horas en lugar de por recencia: la pregunta que responde es qué está ardiendo ahora, no qué acaba de llegar. Los filtros, la asignación y la resolución o el descarte en bloque funcionan ahí exactamente como dentro de un proyecto, pero a través de los proyectos.

La pestaña de un proyecto no cambia y sigue siendo el lugar adecuado cuando ya sabe qué proyecto quiere. La entrada de la barra lateral lleva una insignia con el número de incidencias abiertas del equipo.

Asignar incidencias

Asigne una issue a un miembro del equipo desde la lista o desde su página. El filtro Asignadas a mí convierte la lista en una pila de trabajo personal, ideal para las agencias que reparten los proyectos entre desarrolladores.

Logs alrededor de un evento

Si su plan incluye los logs de aplicación, la página de una issue muestra los logs registrados en el mismo proyecto y entorno a ±5 minutos de la última ocurrencia, el "porqué" suele esconderse ahí. Cada línea lleva a la entrada completa.

Búsqueda global

Pulse ⌘K / Ctrl+K en cualquier lugar del panel para encontrar una issue por clase de excepción, mensaje o archivo, y un proyecto por nombre. Con el almacenamiento cifrado, los mensajes sellados no son buscables (por diseño): la búsqueda se apoya en los metadatos en claro.

Y a continuación

• Configure las alertas para que el equipo sea avisado de las incidencias nuevas y reabiertas.
• Añada los logs de aplicación para tener contexto alrededor de cada error.
• Active el almacenamiento cifrado si el contenido de las excepciones debe permanecer privado en reposo.