Reporte de excepciones

El reporte de excepciones es el corazón del SDK. Una vez configurado, cada excepción que Laravel reporta se transmite a su dashboard.

Captura automática

Al arrancar, el SDK registra un callback reportable() aditivo en el handler de excepciones de la aplicación:

$handler->reportable(function (Throwable $e): void {
    app(Monitor::class)->report($e);
});

Como el callback es aditivo, no sustituye ni elimina su logging existente ni los demás handlers reportable: se limita a transmitir una copia a Quiet Guard. Toda excepción que llega al handler (excepciones no capturadas, o cualquier cosa que pase a report()) queda capturada, excepto la que se produce al servir una petición que coincide con ignore_paths: consulte Configuración.

La captura es fail-safe: un fallo de red, una mala configuración o un error de servidor dentro del SDK se absorbe en silencio y nunca se propaga a la aplicación anfitriona.

Reporte manual

Utilice la fachada Monitor para reportar explícitamente una excepción gestionada:

use QuietGuard\LaravelMonitor\Facades\Monitor;

try {
    $this->chargeCustomer($order);
} catch (\Throwable $e) {
    Monitor::report($e);

    // Relance o recupere como prefiera.
    throw $e;
}

Monitor::report() nunca lanza excepciones. No hace nada, silenciosamente, cuando el reporte está desactivado, cuando falta la URL o la clave del servidor, o cuando el entorno actual no figura en la lista blanca.

Puede resolver el mismo objeto desde el contenedor:

app(\QuietGuard\LaravelMonitor\Monitor::class)->report($e);

Qué se envía

Cada reporte se envía mediante POST al endpoint /api/v1/ingest del servidor y contiene:

La excepción

• clase, mensaje, código, archivo y línea;
• la pila de llamadas completa por defecto (MONITOR_TRACE_LIMIT=0): todos los frames, para que los errores profundos conserven su origen; fije un número de frames para aligerar los payloads. Cada frame se reduce a file, line, function, class y type (los argumentos no se envían nunca, pueden contener secretos).

El contexto

• environment, release (desde MONITOR_RELEASE), php_version, laravel_version, occurred_at (ISO 8601);
• source: console en CLI/cola, o http para las peticiones web.

Para las peticiones HTTP, el contexto incluye además:

• url y method;
• request: cabeceras, query string y cuerpo, con el password / password_confirmation del cuerpo eliminados y el conjunto pasado por el enmascaramiento;
• user: únicamente el identificador del usuario autenticado (id), nunca sus atributos.

Enmascaramiento

Antes de que cualquier payload salga de la aplicación, los datos de petición y de contexto se enmascaran de forma recursiva: toda clave cuyo nombre contenga uno de los términos configurados (sin distinción de mayúsculas y minúsculas) ve su valor sustituido por [scrubbed].

Los términos por defecto son:

password, password_confirmation, passphrase, token, secret,
authorization, cookie, php_auth_pw, api_key, access_token,
referer, referrer, x-forwarded-for, x-real-ip, cf-connecting-ip,
true-client-ip, x-client-ip, forwarded

Para añadir los suyos, publique la configuración (php artisan vendor:publish --tag=monitor-config) y amplíe el array scrub en config/monitor.php:

'scrub' => [
    ...config('monitor.scrub'),
    // los suyos:
    'credit_card',
    'iban',
],

Conserve cada término entregado, salvo que quiera quitarlo. Reescribir el array a mano es como passphrase y las cabeceras de IP del visitante salen de la lista sin ruido.

La correspondencia se hace por subcadena: api_key enmascara por tanto también stripe_api_key, y token enmascara csrf_token.

Enmascarado por la forma del valor

La lista scrub anterior mira el nombre del campo. No ve una dirección escrita en mitad de un mensaje de error, en un segmento de URL, ni en un campo que alguien llamó reference.

La lista redact mira el valor en sí, en su servidor, antes de cualquier envío:

'redact' => ['email', 'iban', 'nir', 'card', 'phone'],

Las formas que llevan dígito de control se verifican en lugar de solo reconocerse: una referencia de pedido de dieciséis dígitos no se toma por un número de tarjeta, y un IBAN debe pasar el módulo 97. Cada valor enmascarado indica qué se ocultó, por ejemplo Usuario [redacted:email] no encontrado, de modo que el mensaje sigue siendo legible.

Elimine los patrones que produzcan falsos positivos con sus datos, o ponga 'redact' => [] para desactivarlo. Para sus propias formas:

'redact_custom' => ['customer_ref' => '/CUST-\d{6}/'],

Envío en segundo plano

Cuando MONITOR_QUEUE está definido, las excepciones se despachan como job en cola SendExceptionToMonitor (2 intentos) en lugar de enviarse en línea. Esto saca el reporte del camino crítico de la petición. Consulte Configuración.

Agrupación en el lado del servidor

El SDK se limita a enviar los datos; el servidor agrupa las ocurrencias en incidencias por huella (fingerprint), reabre las regresiones y correlaciona las releases con los commits. Consulte la documentación del servidor para ver cómo se muestran y gestionan las incidencias.