Logs de aplicación

Más allá de las excepciones, el SDK puede transmitir los mensajes de log de su aplicación a Quiet Guard. Es opt-in y añade como máximo una llamada HTTP por petición.

Activación

La transmisión de logs está desactivada por defecto. Actívela y elija un nivel mínimo:

MONITOR_LOGS_ENABLED=true
MONITOR_LOG_LEVEL=warning
MONITOR_LOGS_MAX_BATCH=200

El hook de logs solo se activa si se cumplen todas estas condiciones: el SDK está activado (MONITOR_ENABLED=true), los logs están activados (MONITOR_LOGS_ENABLED=true), la clave del proyecto está definida (MONITOR_KEY) y el entorno actual está en la lista blanca (MONITOR_ENVIRONMENTS). En caso contrario, el listener no se registra nunca y no hay ningún coste adicional. A partir de la versión 0.3.1, una MONITOR_URL vacía no desactiva los logs: equivale al servicio alojado, y ahí es adonde van. Para desactivarlos, use MONITOR_LOGS_ENABLED=false.

Funcionamiento

El SDK escucha el evento MessageLogged de Laravel. Cada mensaje en el nivel configurado o superior se almacena en un búfer en memoria durante la petición y luego se envía una sola vez, en un único batch, al endpoint /api/v1/logs del servidor.

El envío (flush) tiene lugar al final de la unidad de trabajo:

• en la terminación de la aplicación para las peticiones HTTP y los comandos de consola;
• después de cada job en cola (JobProcessed y JobFailed), porque los workers de cola de larga duración nunca terminan entre dos jobs.

Si el búfer alcanza MONITOR_LOGS_MAX_BATCH entradas (200 por defecto) durante la petición, se vacía de forma anticipada para que nada se pierda silenciosamente.

MONITOR_LOGS_MAX_BATCH está limitado a 500, el mayor lote que acepta el servidor. Un valor superior lo aceptaba antes el cliente y lo rechazaba el servidor en cada envío: nunca salía nada, y nada lo decía.

Niveles

El nivel mínimo es un nivel PSR-3 estándar. Todo lo que esté en ese nivel o por encima (en severidad) se captura:

debug < info < notice < warning < error < critical < alert < emergency

Con el valor por defecto MONITOR_LOG_LEVEL=warning, las entradas warning, error, critical, alert y emergency se transmiten; debug, info y notice se ignoran. Un valor de nivel no reconocido falla de forma segura (captura menos, no más).

Qué se captura, y qué no

Cada entrada transmitida contiene: level, message, context enmascarado, environment, release y logged_at (ISO 8601).

Dos tipos de entradas se ignoran deliberadamente:

• Las entradas de log que llevan una excepción (un context['exception']): ya las cubre el pipeline de excepciones; transmitirlas también como logs crearía duplicados.
• Los logs de fallo internos del SDK: marcados con una bandera interna para que un error de transporte nunca pueda reinyectarse en el búfer de logs (sin bucle de retroalimentación).

Los valores de contexto pasan por el mismo enmascaramiento que las excepciones, y los valores de contexto no escalares se normalizan a una forma serializable en JSON antes del envío.

Una línea nunca le cuesta el lote

El servidor valida cada entrada de un lote y rechaza el lote entero en cuanto una de ellas está mal formada: una sola línea defectuosa se llevaba por delante las doscientas que la acompañaban. Se aplican dos protecciones en el momento en que cada entrada entra en el búfer:

• un mensaje de más de 8192 caracteres se recorta, marcando el corte con … [truncated], contando caracteres y no bytes;
• un mensaje vacío, que el servidor exige presente, se sustituye por (empty log message) en lugar de hundir su lote.

Envío en segundo plano

Cuando MONITOR_QUEUE está definido, el batch se despacha como job en cola SendLogsToMonitor (2 intentos) en lugar de enviarse en línea. Consulte Configuración.

Igual que los payloads de excepción, un lote se enmascara antes de encolarse: un contexto de log que lleve una dirección o un número de tarjeta nunca queda en claro en sus tablas jobs o failed_jobs. Un job cuyo envío ha fallado lanza, de modo que su segundo intento ocurre de verdad.

Nota sobre el plan

Los logs de aplicación son una funcionalidad de pago en el lado del servidor y cuentan para su cuota de eventos. Si su plan no incluye los logs, el servidor rechaza el batch. Eso nunca afecta a su aplicación, y ya no es invisible: el rechazo se escribe en su propio log como advertencia, nombrando el estado, la dirección y lo que respondió el servidor. Consulte la documentación del servidor.