Uso

Una vez instalado el bundle y definidos url + key, el reporte de excepciones funciona sin ningún código adicional. La transmisión de logs y el reporte manual requieren cada uno un paso más.

Captura automática de excepciones

El bundle registra monitor.exception_subscriber, un event subscriber que escucha el evento kernel.exception de Symfony con una prioridad de -64 (baja, para que los listeners del framework se ejecuten primero, el bundle solo observa). Para cada throwable no gestionado:

1. compara los environments configurados con kernel.environment y se abstiene si el entorno actual no está autorizado;
2. construye una carga útil a partir del throwable (clase, mensaje, archivo, línea y la pila de llamadas, completa por defecto);
3. adjunta el contexto de la petición, el método y la URL HTTP, así como el entorno y la release;
4. enmascara las claves sensibles y envía el resultado mediante POST a /api/v1/ingest.

Las excepciones HTTP con un código de estado inferior a 500 (NotFoundHttpException y otros errores de cliente esperados, como los sondeos de bots que terminan en 404) se omiten: nunca se reportan y nunca cuentan para su cuota de eventos. Las excepciones HTTP de código 500 o superior se reportan como cualquier otro throwable.

Es aditivo: nunca modifica la respuesta, nunca interrumpe la propagación y nunca lanza errores. Si el servidor no está disponible, el envío falla silenciosamente.

El subscriber reporta los throwables que llegan al kernel. Las excepciones que usted captura y gestiona por su cuenta no son, por definición, "no gestionadas", repórtelas manualmente (más abajo).

Transmitir los logs

Establezca logs.enabled: true para activar la transmisión de logs. El servicio handler de Monolog monitor.log_handler siempre está registrado mientras el bundle está activado; con logs.enabled: false simplemente descarta todos los registros, de modo que un monolog.yaml que lo referencie sigue compilando. El handler:

• almacena en un búfer los registros de nivel logs.level o superior;
• respeta la lista environments exactamente igual que el subscriber de excepciones: fuera de los entornos autorizados, ningún registro sale de su aplicación;
• ignora los registros que llevan una exception en su contexto: esos ya están cubiertos por el pipeline de excepciones;
• vacía el búfer hacia /api/v1/logs en lotes de logs.max_batch, y de nuevo cuando el handler se cierra al final de la petición.

Registrar el servicio no basta por sí solo, debe adjuntarlo a Monolog como servicio handler:

# config/packages/monitor.yaml
monitor:
    logs:
        enabled: true
        level: warning
        max_batch: 200

# config/packages/prod/monolog.yaml
monolog:
    handlers:
        monitor:
            type: service
            id: monitor.log_handler

Los registros que pasan por Monolog (nivel warning y superior por defecto) se agrupan ahora en lotes y se envían a su dashboard. Esto requiere monolog/monolog ^3.0 en su aplicación.

Reportar manualmente

El Reporter compartido está registrado con el identificador de servicio monitor.reporter. Como es un servicio privado sin alias sobre su nombre de clase, el autowiring por tipo (Reporter $reporter) no lo resuelve, conéctelo explícitamente.

Con el atributo #[Autowire] sobre un argumento del constructor:

use QuietGuard\Monitor\Reporter;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

class CheckoutService
{
    public function __construct(
        #[Autowire(service: 'monitor.reporter')]
        private readonly Reporter $monitor,
    ) {}

    public function settle(Order $order): void
    {
        try {
            // ...
        } catch (\Throwable $e) {
            $this->monitor->reportException($e, ['order_id' => $order->getId()]);

            throw $e;
        }
    }
}

O enlazándolo en services.yaml:

# config/services.yaml
services:
    App\Service\CheckoutService:
        arguments:
            $monitor: '@monitor.reporter'

El Reporter expone:

• reportException(Throwable $e, array $context = []): bool: POST /api/v1/ingest;
• sendLogs(array $logs): bool: POST /api/v1/logs;
• sendDependencies(array $packages): bool: POST /api/v1/dependencies.

Cada una devuelve false (y nunca lanza errores) cuando el cliente no está configurado o el envío falla.

Enmascarar los datos sensibles

Antes de que nada salga de su aplicación, las claves scrub configuradas se enmascaran recursivamente en el array de contexto con [scrubbed]. La coincidencia es una búsqueda de subcadena en el nombre de la clave, sin distinguir mayúsculas y minúsculas: una clave password configurada también enmascara user_password. Los valores por defecto cubren password, passphrase, token, secret, authorization, cookie, referer, referrer y api_key. Añada sus propias claves mediante la opción scrub, vea la Configuración.

El núcleo añade una segunda pasada que el bundle no configura: los valores con forma de dirección de correo, IBAN, número de tarjeta, número de seguridad social o teléfono franceses se enmascaran estén donde estén, texto del mensaje y segmentos de URL incluidos, y la máscara nombra lo que oculta ([redacted:email]). Viene activa y hoy no se desactiva desde el árbol monitor. Vea la página de enmascarado del núcleo.

Análisis de dependencias

El bundle no incluye un comando de consola para capturar su composer.lock (a diferencia del SDK de Laravel). El método subyacente Reporter::sendDependencies() existe, y el endpoint del servidor /api/v1/dependencies es agnóstico de plataforma: puede por tanto crear su propio comando de consola o paso de CI que lea composer.lock y envíe la lista de paquetes con su clave de proyecto. Un comando dedicado podría llegar en una futura versión del bundle.