Configuración

El SDK se configura por completo mediante variables de entorno, fusionadas en el espacio de configuración monitor. Publicar config/monitor.php es opcional (consulte Instalación).

Configuración mínima

Añada lo siguiente al .env de su aplicación:

MONITOR_ENABLED=true
MONITOR_KEY=su-clave-api-de-proyecto

# Solo para una instancia autoalojada: el servicio alojado es el valor por defecto
MONITOR_URL=https://monitor.example.com

• MONITOR_KEY es la clave de API por proyecto generada en el dashboard de Quiet Guard. Se muestra una sola vez, al crear el proyecto. Consulte la documentación del servidor para saber cómo crear los proyectos y las claves.
• MONITOR_URL vale https://quietguard.dev por defecto, es decir, el servicio alojado: en el servicio alojado solo tiene que pegar la clave. Defínala para apuntar el SDK a su propia instancia si se autoaloja.

Una URL base que ya termina en /api o /api/v1 se acepta y se normaliza: el propio SDK añade /api/v1/..., así que el sufijo se retira en lugar de duplicarse. Ambas formas funcionan, de modo que leer la dirección de la API en el dashboard ya no puede responder 404 en silencio en cada llamada.

Cuando MONITOR_KEY está vacía, el SDK permanece totalmente silencioso: nunca envía nada y nunca lanza errores. La clave es lo único que puede faltar: a partir de la versión 0.3.1, una MONITOR_URL vacía no detiene nada, equivale al servicio alojado (hasta la versión 0.3.0, cortaba en silencio el envío de excepciones y de logs). Una máquina que tiene una clave y ninguna dirección, un entorno de preproducción por ejemplo, reporta por tanto ahora al servicio alojado. Para mantenerla en silencio, vacíe su clave o use MONITOR_ENABLED=false, que lo dice.

Todas las opciones

Entornos

Por defecto, el SDK solo reporta desde production y staging. Dicho de otro modo, en local no se envía nada mientras no modifique la lista:

# Reportar desde todos los entornos
MONITOR_ENVIRONMENTS=

# O añadir local mientras prueba la integración
MONITOR_ENVIRONMENTS=production,staging,local

La comprobación se apoya en app()->environment() de Laravel, es decir, el valor de su APP_ENV. Los heartbeats automáticos pasan además por su propia lista, MONITOR_HEARTBEAT_ENVIRONMENTS, producción por defecto: ambas listas deben admitirlo.

Release

La release es el identificador de la versión desplegada, adjuntado a cada evento: el servidor lo usa para vincular una incidencia a un despliegue concreto y, cuando es un SHA de commit, para abrir desde la incidencia el commit sincronizado que estaba en ejecución en el momento del error.

No tiene que definir nada en el caso habitual: cuando MONITOR_RELEASE está vacío, el SDK detecta la release por sí mismo, una vez por proceso, leyendo por orden un archivo REVISION en la raíz de la aplicación (Capistrano, Deployer y la mayoría de los scripts de despliegue escriben uno) y después el .git/HEAD del checkout, siguiendo la referencia de rama hasta el commit. Un valor explícito siempre gana:

MONITOR_RELEASE=v2.4.1

Para enviar únicamente el valor configurado, por ejemplo cuando el checkout presente en el servidor no es la rama que realmente se ejecuta, desactive la detección:

MONITOR_RELEASE_AUTO=false

Automatizar el hash de git en el despliegue

El servidor solo vincula una incidencia a un commit cuando la release es el SHA de ese commit. Según cómo despliegue, así es como ese hash llega a MONITOR_RELEASE sin que nadie lo escriba a mano.

Laravel Forge. En modo sin interrupción, cada directorio de release es un checkout de git: .git/HEAD lleva el SHA y no hay nada que hacer, incluido un clon --depth 1. En modo clásico, añada una línea al script de despliegue después del git pull:

git rev-parse HEAD > REVISION

Envoyer. Envoyer expone el SHA desplegado en la variable {{ sha }}; escríbalo en un archivo REVISION desde un hook de despliegue, antes de activar la release:

cd {{ release }} && echo "{{ sha }}" > REVISION

GitHub Actions, o cualquier integración continua. El SHA del commit está en GITHUB_SHA; escríbalo en el .env del artefacto desplegado, o en un archivo REVISION incluido con él:

echo "MONITOR_RELEASE=${GITHUB_SHA}" >> .env

Si su configuración está en caché, vuelva a ejecutar php artisan config:cache después de modificar .env; de lo contrario, el valor en caché se mantiene.

Docker. Pase el hash al construir la imagen y fíjelo en una variable de entorno:

ARG GIT_SHA
ENV MONITOR_RELEASE=$GIT_SHA

docker build --build-arg GIT_SHA=$(git rev-parse HEAD) .

Un servidor actualizado con git pull. Se lee el .git/HEAD del repositorio; no hay nada que hacer.

El servidor compara la release con el SHA completo de 40 caracteres de los commits sincronizados; un SHA abreviado de al menos 7 caracteres se resuelve como prefijo. Un tag (v2.4.1) funciona como etiqueta de un despliegue, pero no enlaza con ningún commit.

Envío asíncrono

Por defecto, los reportes se envían de forma síncrona durante la petición, dentro del límite de MONITOR_TIMEOUT. Para sacar ese trabajo del ciclo de vida de la petición, póngalo en una cola:

# Usar una conexión de cola concreta
MONITOR_QUEUE=redis

# O la conexión por defecto
MONITOR_QUEUE=true

Los reportes se despachan entonces como jobs en cola (SendExceptionToMonitor, SendLogsToMonitor); por lo tanto, debe haber un worker de cola en ejecución.

MONITOR_QUEUE designa una conexión de cola, es decir, una clave de su array queue.connections, y no un nombre de cola. MONITOR_QUEUE=default, =monitoring o =high no designan ninguna conexión en una aplicación Laravel estándar. Un valor así se rechaza para los reportes de excepciones: el SDK escribe una advertencia nombrando las conexiones que sí existen y envía el reporte de forma síncrona, porque un reporte que bloquea la petición vale más que un reporte que nunca sale. Los lotes de logs leen el mismo ajuste y no tienen ese repliegue, así que dele un nombre que su aplicación declare realmente.

Dos propiedades del camino en cola conviene conocerlas. Los payloads se enmascaran antes de encolarse, de modo que las formas que el enmascaramiento por valor existe para detener nunca quedan en claro en sus propias tablas jobs y failed_jobs. Y un job cuyo envío ha fallado lanza, de modo que el segundo de sus dos intentos es real y un fallo definitivo queda registrado en failed_jobs en lugar de marcarse como correcto.

Rutas de petición ignoradas

Por defecto se reporta toda excepción, dondequiera que ocurra. Defina ignore_paths con una lista de rutas de petición cuyas excepciones nunca se reportan, en la sintaxis que acepta Illuminate\Http\Request::is() de Laravel:

'ignore_paths' => ['api/v1/*'],

Vacía por defecto. Un comando de consola lleva una petición ficticia cuya ruta es /, que no coincide con ninguno de estos patrones, de modo que ignore_paths nunca silencia un job en cola ni una tarea programada, solo las peticiones HTTP. Esto afecta únicamente a las excepciones, los logs no se ven afectados.

Esta opción existe para una aplicación que aloja su propio endpoint de supervisión: las excepciones producidas al servirlo no deben reportarse de vuelta a él.

Claves enmascaradas

La lista monitor.scrub por defecto enmascara cualquier clave de petición/contexto cuyo nombre contenga uno de estos términos (sin distinción de mayúsculas y minúsculas, de forma recursiva):

password, password_confirmation, passphrase, token, signature, 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

referer y referrer llevan la dirección de la página de la que viene el visitante, y una URL es donde las aplicaciones colocan sus secretos de un solo uso: un enlace para darse de baja, una descarga firmada, un restablecimiento de contraseña, un enlace para compartir. Se enmascara por el nombre, porque ese valor no tiene ninguna forma que un enmascarador de valores pueda reconocer.

Las seis últimas son las cabeceras que llevan la dirección IP del visitante. Detrás de un proxy inverso, que es la topología de producción habitual, una de ellas contiene la dirección de la persona que provocó el error. Es un dato personal, y no le concierne a usted sino a sus visitantes, que no eligieron nada. Por eso se enmascara por defecto. Si dispone de una base jurídica para conservarla, elimine la línea correspondiente: la decisión es suya, en su condición de responsable del tratamiento.

Para ampliarla, publique la configuración y modifique el array scrub. Los valores enmascarados se sustituyen por [scrubbed]. Consulte Reporte de excepciones para más detalles.