> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Introducción a Laravel Nightwatch

> Se explican una visión general de «Nightwatch», la plataforma SaaS gestionada de monitorización de aplicaciones Laravel; sus diferencias con Telescope y Pulse; el método de instalación; y la configuración necesaria para usarlo de forma práctica con el plan gratuito.

## ¿Qué es Laravel Nightwatch?

[Laravel Nightwatch](https://nightwatch.laravel.com) es una **plataforma SaaS gestionada** para monitorizar de forma continua el entorno de producción de aplicaciones Laravel. Recoge y visualiza en tiempo real datos de telemetría de toda la aplicación: peticiones HTTP, consultas SQL, excepciones, jobs de cola, logs, tareas programadas, etc.

<Info>
  Nightwatch es un **servicio de pago** (facturación mensual). Se puede usar también con el plan gratuito, pero hay un límite en el número de eventos que se pueden recoger. Para usarlo de forma práctica en el plan gratuito es imprescindible aplicar la configuración de muestreo y filtrado descrita a continuación.
</Info>

***

## Diferencias con Telescope y Pulse

Nightwatch difiere en propósito de las herramientas de monitorización y depuración ya existentes en el ecosistema Laravel. Vamos a organizar sus usos.

```mermaid theme={null}
graph TD
    A["Herramientas de monitorización de Laravel"] --> B["Telescope<br>Depuración en entorno de desarrollo"]
    A --> C["Pulse<br>Agregación de rendimiento en producción"]
    A --> D["Nightwatch<br>Monitorización gestionada en producción"]

    B --> B1["Self-hosting<br>Solo durante el desarrollo<br>Gratuito, OSS"]
    C --> C1["Self-hosting<br>Dashboard en tiempo real<br>Gratuito, OSS"]
    D --> D1["Plataforma SaaS<br>Requiere agente residente<br>Servicio de pago"]
```

| Herramienta    | Uso                                                   | Hosting                           | Entorno objetivo      |
| -------------- | ----------------------------------------------------- | --------------------------------- | --------------------- |
| **Telescope**  | Depuración e investigación de queries en desarrollo   | Propio (dentro de la app Laravel) | Desarrollo local      |
| **Pulse**      | Agregación y visualización de métricas de rendimiento | Propio (dentro de la app Laravel) | Producción y staging  |
| **Nightwatch** | Monitorización en tiempo real de apps en producción   | SaaS gestionado por Laravel       | Entorno de producción |

Recoge prácticamente la misma información que Telescope, pero Nightwatch mantiene un proceso agente residente y envía los datos a la nube. Por eso, aunque el servidor caiga, puedes consultar el histórico, y puedes gestionar múltiples servidores y aplicaciones de forma centralizada.

***

## Arquitectura

Nightwatch adopta una configuración en la que se interpone un proceso agente entre la app Laravel y la nube de Nightwatch.

```mermaid theme={null}
sequenceDiagram
    participant App as App Laravel
    participant Agent as Agente Nightwatch<br>(php artisan nightwatch:agent)
    participant Cloud as Nube de Nightwatch
    participant Dashboard as Dashboard<br>(nightwatch.laravel.com)

    App->>Agent: Envía datos de evento<br>(127.0.0.1:2407)
    Agent->>Cloud: Envío por lotes
    Cloud->>Dashboard: Visualización y alertas
```

El agente permanece a la escucha en local (`127.0.0.1:2407`), recibe eventos de la app Laravel y los reenvía a la nube. Por eso hay que mantener el proceso agente siempre en ejecución.

***

## Instalación y configuración inicial

### 1. Creación de cuenta y aplicación

Crea una cuenta en [nightwatch.laravel.com](https://nightwatch.laravel.com) y registra la organización y la aplicación. Tras registrar la aplicación se emite un **token de entorno**.

### 2. Instalación del paquete

```bash theme={null}
composer require laravel/nightwatch
```

A diferencia de Telescope, la flag `--dev` **no es necesaria**. Nightwatch está pensado para usarse en producción.

### 3. Configuración del token

Añade el token al archivo `.env`.

```ini theme={null}
NIGHTWATCH_TOKEN=your-api-key
```

### 4. Arranque del agente

```bash theme={null}
php artisan nightwatch:agent
```

Hay que mantener el agente ejecutándose siempre en segundo plano. Laravel Cloud, Laravel Forge y Laravel Vapor cuentan con guías específicas. En Forge, con la integración oficial se configura automáticamente.

Comprobación del estado del agente:

```bash theme={null}
php artisan nightwatch:status
```

### 5. Desactivación en el entorno de tests

Se recomienda desactivar Nightwatch durante la ejecución de tests.

```ini theme={null}
# .env
NIGHTWATCH_ENABLED=false
```

También se puede configurar en `phpunit.xml`.

```xml theme={null}
<php>
    <env name="APP_ENV" value="testing"/>
    <env name="NIGHTWATCH_ENABLED" value="false"/>
</php>
```

***

## Configuración para usarlo de forma práctica en el plan gratuito

<Warning>
  **El plan gratuito tiene un límite mensual de eventos.** Con la configuración por defecto (muestreo al 100 % y recolección de todos los datos), aplicaciones con mucho tráfico alcanzan rápidamente el límite. Aplica siempre la siguiente configuración.
</Warning>

### Bajar la tasa de muestreo

`NIGHTWATCH_REQUEST_SAMPLE_RATE` es por defecto `1.0` (recoge todas las peticiones). Se recomienda reducirlo a algo así como `0.1` (10 %) en el plan gratuito.

```ini theme={null}
# .env
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
```

Ejemplo de configuración que sigue recogiendo el 100 % de excepciones y comandos:

```ini theme={null}
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1    # Solo el 10 % de las peticiones
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0  # Todas las excepciones (por defecto)
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0    # Todos los comandos (por defecto)
```

### Desactivar la recolección de queries

Las consultas a base de datos representan una gran proporción de eventos. Desactivando la recolección de queries en el plan gratuito, dejas espacio para guardar eventos importantes (excepciones, peticiones, jobs).

```ini theme={null}
# .env
NIGHTWATCH_IGNORE_QUERIES=true
```

### Otras configuraciones de filtrado

Según sea necesario, puedes desactivar también la recolección de eventos de caché o de correo.

```ini theme={null}
NIGHTWATCH_IGNORE_CACHE_EVENTS=true
NIGHTWATCH_IGNORE_MAIL=true
NIGHTWATCH_IGNORE_NOTIFICATIONS=true
NIGHTWATCH_IGNORE_OUTGOING_REQUESTS=true
```

### Resumen de configuración recomendada para el plan gratuito

```ini theme={null}
# .env (configuración recomendada para plan gratuito)
NIGHTWATCH_TOKEN=your-api-key
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
NIGHTWATCH_IGNORE_QUERIES=true
```

Con solo estas tres líneas puedes lograr una monitorización de aplicaciones útil incluso en el plan gratuito.

***

## Funcionalidades principales

### Monitorización de peticiones

Recoge por cada petición HTTP el tiempo de respuesta, el código de estado y la información de ruta. Puedes identificar endpoints anormalmente lentos y descubrir cuellos de botella de rendimiento.

### Seguimiento de excepciones

Captura en tiempo real las excepciones no gestionadas que se produzcan en producción. Se registran automáticamente la traza y snippets del código fuente, lo que facilita la investigación de la causa.

```ini theme={null}
# Recolección de código fuente de la excepción (activado por defecto)
NIGHTWATCH_CAPTURE_EXCEPTION_SOURCE_CODE=true
```

### Recolección de logs

Se integra con el sistema de logging de Laravel (`Log::error()`, etc.) y envía logs estructurados a Nightwatch.

```ini theme={null}
# Nivel mínimo de logs a recoger (por defecto: debug)
NIGHTWATCH_LOG_LEVEL=error
```

### Monitorización de jobs y tareas programadas

Sigue el historial de ejecución, el estado de éxito o fallo y el tiempo de ejecución de los jobs de cola y las tareas programadas. Permite identificar rápidamente problemas en el procesamiento por lotes.

### Seguimiento de despliegues

Relaciona los cambios de cada release con los problemas. Permite investigar visualmente cosas como "desde este despliegue han aumentado las excepciones".

### Alertas y notificaciones

Usando la integración con Slack o webhooks puedes notificar al instante subidas repentinas de excepciones o degradaciones de rendimiento.

***

## Cuándo usar Telescope y cuándo Nightwatch

```mermaid theme={null}
flowchart TD
    Q1{"¿Necesitas datos<br>de producción?"} -->|Sí| Q2{"¿Quieres alojar los datos<br>en tu propio servidor?"}
    Q1 -->|No| T["Telescope<br>(desarrollo local)"]
    Q2 -->|Sí| P["Pulse<br>(self-hosting)"]
    Q2 -->|No| N["Nightwatch<br>(SaaS gestionado)"]
```

* **Desarrollo local** → Telescope
* **Quiero un dashboard agregado de producción** → Pulse
* **Quiero trazas detalladas y alertas en producción** → Nightwatch

Los tres no se excluyen mutuamente; también se puede usar Pulse y Nightwatch conjuntamente.

***

## Conclusión

Laravel Nightwatch es una potente herramienta SaaS que mejora enormemente la visibilidad de las aplicaciones Laravel en producción. Al implantarla, ten en cuenta lo siguiente.

* Hay que mantener el proceso agente ejecutándose siempre
* En el plan gratuito son prácticamente imprescindibles las configuraciones `NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1` y `NIGHTWATCH_IGNORE_QUERIES=true`
* Telescope (desarrollo), Pulse (agregación) y Nightwatch (monitorización) tienen roles distintos y pueden usarse conjuntamente

Para la configuración detallada consulta la [documentación oficial](https://nightwatch.laravel.com/docs/start-guide) y la [referencia de variables de entorno](https://nightwatch.laravel.com/docs/environment-variables).

<Card title="Técnicas prácticas de Laravel Telescope" icon="telescope" href="/es/blog/telescope-introduction">
  Para depurar en desarrollo local, usa Telescope.
</Card>


## Related topics

- [Introducción a React — Fundamentos para usarlo con Inertia × Laravel](/es/blog/react-introduction.md)
- [Introducción a Svelte — Fundamentos para usarlo con Inertia × Laravel](/es/blog/svelte-introduction.md)
- [Introducción a Vue.js — Fundamentos para usarlo con Inertia × Laravel](/es/blog/vue-introduction.md)
- [Introducción a Eloquent](/es/eloquent.md)
- [Introducción a la autenticación](/es/authentication.md)