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

# Getting started with Laravel Nightwatch

> An overview of Laravel Nightwatch, the hosted SaaS application monitoring platform, its differences from Telescope and Pulse, installation, and settings that make the free plan practical.

## What is Laravel Nightwatch?

[Laravel Nightwatch](https://nightwatch.laravel.com) is a **hosted SaaS platform** for continuously monitoring Laravel applications in production. It collects and visualizes telemetry from across your app—HTTP requests, SQL queries, exceptions, queued jobs, logs, and scheduled tasks—in real time.

<Info>
  Nightwatch is a **paid service** (monthly subscription). A free plan is available, but the number of events you can collect is capped. To use the free plan practically, the sampling and filtering settings described below are essential.
</Info>

***

## How it differs from Telescope and Pulse

Nightwatch's purpose differs from other monitoring and debugging tools in the Laravel ecosystem. Here's how they line up.

```mermaid theme={null}
graph TD
    A["Laravel monitoring tools"] --> B["Telescope<br>Dev-env debugging"]
    A --> C["Pulse<br>Production performance aggregation"]
    A --> D["Nightwatch<br>Hosted production monitoring"]

    B --> B1["Self-hosted<br>Dev only<br>Free / OSS"]
    C --> C1["Self-hosted<br>Realtime dashboard<br>Free / OSS"]
    D --> D1["SaaS platform<br>Requires resident agent<br>Paid service"]
```

| Tool           | Purpose                                              | Hosting                               | Target environment   |
| -------------- | ---------------------------------------------------- | ------------------------------------- | -------------------- |
| **Telescope**  | Debugging and query investigation during development | Self-hosted (inside your Laravel app) | Local dev            |
| **Pulse**      | Aggregation and visualization of performance metrics | Self-hosted (inside your Laravel app) | Production / staging |
| **Nightwatch** | Real-time monitoring of production apps              | Laravel-hosted SaaS                   | Production           |

It collects nearly the same information as Telescope, but Nightwatch runs a resident agent process that ships data to the cloud. That means historical data is accessible even if the server goes down, and multiple servers or applications can be managed together.

***

## Architecture

Nightwatch sits an agent process between your Laravel app and the Nightwatch cloud.

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

    App->>Agent: Send event data<br>(127.0.0.1:2407)
    Agent->>Cloud: Batched forwarding
    Cloud->>Dashboard: Visualization and alerts
```

The agent listens locally (`127.0.0.1:2407`), receives events from the Laravel app, and forwards them to the cloud. Because of this, the agent process must be running at all times.

***

## Installation and initial setup

### 1. Create your account and application

Create an account on [nightwatch.laravel.com](https://nightwatch.laravel.com) and register your organization and application. After registering an application, an **environment token** is issued.

### 2. Install the package

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

Unlike Telescope, the `--dev` flag is **not** used. Nightwatch is designed for production.

### 3. Configure the token

Add the token to `.env`.

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

### 4. Start the agent

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

The agent must run continuously in the background. Dedicated guides are available for Laravel Cloud, Laravel Forge, and Laravel Vapor. On Forge, using the official integration configures this automatically.

Check the agent's status:

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

### 5. Disable in the test environment

We recommend disabling Nightwatch while tests run.

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

It can also be set in `phpunit.xml`.

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

***

## Settings that make the free plan practical

<Warning>
  **The free plan has a monthly event cap.** With the defaults (sampling rate 100%, collect everything), a high-traffic app hits the limit quickly. Apply the settings below.
</Warning>

### Lower the sampling rate

`NIGHTWATCH_REQUEST_SAMPLE_RATE` defaults to `1.0` (collect every request). We recommend cutting it to about `0.1` (10%) on the free plan.

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

Example that keeps exceptions and commands fully sampled:

```ini theme={null}
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1    # Requests: only 10%
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0  # Exceptions: all (default)
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0    # Commands: all (default)
```

### Disable query collection

Database queries make up a large share of events. Disabling query collection on the free plan preserves room for more important events (exceptions, requests, jobs).

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

### Other filtering options

You can also disable cache events, mail, notifications, and outgoing requests as needed.

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

### Free plan recommended settings summary

```ini theme={null}
# .env (recommended for the free plan)
NIGHTWATCH_TOKEN=your-api-key
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
NIGHTWATCH_IGNORE_QUERIES=true
```

Just these three lines make practical monitoring feasible on the free plan.

***

## Main features

### Request monitoring

Collects response time, status code, and route info for each HTTP request. Identify unusually slow endpoints and pinpoint performance bottlenecks.

### Exception tracking

Captures unhandled exceptions in production in real time. Stack traces and source snippets are recorded automatically, making root cause analysis easier.

```ini theme={null}
# Capture exception source code (default: enabled)
NIGHTWATCH_CAPTURE_EXCEPTION_SOURCE_CODE=true
```

### Log collection

Integrates with Laravel's logging system (`Log::error()`, etc.) to send structured logs to Nightwatch.

```ini theme={null}
# Minimum log level to collect (default: debug)
NIGHTWATCH_LOG_LEVEL=error
```

### Jobs and scheduled task monitoring

Track execution history, success/failure status, and duration for queued jobs and scheduled tasks. Quickly identify issues in batch processing.

### Deployment tracking

Correlates release changes to issues. You can visually investigate "exceptions started spiking after this deploy."

### Alerts and notifications

Use Slack integration or webhooks to get notified instantly on exception spikes or performance regressions.

***

## When to use Telescope vs. Nightwatch

```mermaid theme={null}
flowchart TD
    Q1{"Need production data?"} -->|Yes| Q2{"Want to keep<br>data on your servers?"}
    Q1 -->|No| T["Telescope<br>(local development)"]
    Q2 -->|Yes| P["Pulse<br>(self-hosted)"]
    Q2 -->|No| N["Nightwatch<br>(hosted SaaS)"]
```

* **Local development** → Telescope
* **Aggregated production dashboard** → Pulse
* **Detailed production traces and alerts** → Nightwatch

The three aren't mutually exclusive—running Pulse and Nightwatch alongside each other is fine.

***

## Summary

Laravel Nightwatch is a powerful SaaS tool that significantly boosts visibility into production Laravel apps. Keep the following in mind when introducing it:

* The agent process must run continuously
* On the free plan, `NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1` and `NIGHTWATCH_IGNORE_QUERIES=true` are effectively required in practice
* Telescope (dev), Pulse (aggregation), and Nightwatch (monitoring) have different roles and can be used together

For detailed configuration, see the [official docs](https://nightwatch.laravel.com/docs/start-guide) and the [environment variables reference](https://nightwatch.laravel.com/docs/environment-variables).

<Card title="Laravel Telescope hands-on techniques" icon="telescope" href="/en/blog/telescope-introduction">
  Use Telescope for debugging in local development.
</Card>


## Related topics

- [Getting started - VOICEVOX for Laravel](/en/packages/laravel-voicevox/getting-started.md)
- [Getting started with React — the essentials for using it with Inertia × Laravel](/en/blog/react-introduction.md)
- [Getting started with Laravel testing using Pest PHP](/en/blog/pest-introduction.md)
- [Getting started with Svelte — the essentials for using it with Inertia × Laravel](/en/blog/svelte-introduction.md)
- [Getting started with Vue.js — the essentials for using it with Inertia × Laravel](/en/blog/vue-introduction.md)