Nightwatch captures everything by default. Without sampling or filtering, it will collect 100% of requests, jobs, queries, exceptions, and more, giving you complete visibility with zero setup. Sampling lets you reduce the volume of data collected, helping you manage usage in high-throughput or noisy environments. You might choose to sample aggressively in staging, more conservatively in production, or apply targeted sampling to specific routes. Sample rates in Nightwatch are decimal values where 1 captures 100%, 0 captures 0%, and values like 0.25 capture 25% of events. 
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1 # Recommended
💡 Tip: We recommend starting with the sample rate of 0.1 or lower on requests to build an understanding of your application’s profile and adjusting the rate based on your observations.

​
Request and Command Sampling

You can configure global sampling for both HTTP requests and Artisan commands using environment variables. When a request or command is sampled in, Nightwatch captures the full execution context, including related database queries, queued jobs, exceptions, and outbound HTTP calls.
Why do we only expose global sampling controls for requests and commands? Take a look at the Nightwatch Sampling Philosophy section to learn more.

​
Exception Sampling

You can combine exception sampling with other sampling types. When you set both request sampling (10%) and exception sampling (50%), Nightwatch will:
  • Capture all exceptions from the sampled requests
  • Capture 50% of exceptions from non-sampled requests
To ignore exceptions on non-sampled requests, set NIGHTWATCH_EXCEPTION_SAMPLE_RATE=0. This setting ensures that exceptions are captured only from sampled requests.

​
Exception Throttling

Laravel provides additional ways to throttle exception reporting for high traffic applications or when you need to protect against sudden spikes. https://laravel.com/docs/errors#throttling-reported-exceptions

​
Route-based Sampling

The Nightwatch Sample middleware provides individual route or route group sampling rates within your Laravel application. 
// web.php

use Illuminate\Support\Facades\Route;
use Laravel\Nightwatch\Http\Middleware\Sample;

// Applied to a single route
Route::get('/users', [UserController::class, 'index'])
    ->middleware(Sample::rate(0.5));

// Applied to a route group
Route::middleware(Sample::rate(0.5))->group(function () {
    // ...
});

​
Unmatched Routes Sampling

You can set sample rates for bot traffic by using the Sample middleware with Laravel’s fallback route. We don’t recommend ignoring all unmatched routes. Instead, you should implement a reduced sample rate for bot traffic to help identify and block unwanted requests. 
// Applied to unmatched 404 routes
Route::fallback(fn () => abort(404))
    ->middleware(Sample::rate(0.5));

​
Package Route Sampling

Many packages provide options to modify the middleware applied to their routes through configuration. For example, Laravel Nova lets you add middleware to its internal routes in your config/nova.php configuration file. 
/*
|--------------------------------------------------------------------------
| Nova Route Middleware
|--------------------------------------------------------------------------
|
| These middleware will be assigned to every Nova route, giving you the
| chance to add your own middleware to this stack or override any of
| the existing middleware. Or, you can just stick with this stack.
|
*/

'middleware' => [
    \Laravel\Nightwatch\Http\Middleware\Sample::rate(0.5),
    'web',
    \Laravel\Nova\Http\Middleware\HandleInertiaRequests::class,
    'nova:serving',
],

​
Dynamic Sampling

Under the hood, all the sampling options above defer to the low-level Nightwatch::sample method. You can call this method directly for fine-grained control in situations where Nightwatch doesn’t yet provide sampling capabilities. 
use Laravel\Nightwatch\Facades\Nightwatch;
Nightwatch::sample(); // Sample 100% of executions.
Nightwatch::sample(rate: 1.0); // Sample 100% of executions.
Nightwatch::sample(rate: 0.5); // Sample 50% of executions.
Nightwatch::sample(rate: 0); // Sample 0% of executions.
Nightwatch::dontSample(); // Sample 0% of executions.

​
Dynamic Sampling Examples

When setting dynamic sample rates, it’s important to consider:
  • Always set the sample rate as early as possible.
  • An exception may reactivate sampling for the execution based on the global NIGHTWATCH_EXCEPTION_SAMPLE_RATE.

​
Sampling the Health Check Endpoint

// AppServiceProvider.php

use Illuminate\Foundation\Events\DiagnosingHealth;
use Laravel\Nightwatch\Facades\Nightwatch;

Event::listen(function (DiagnosingHealth $event) {
    Nightwatch::dontSample();
});

​
Sampling Specific Jobs

Nightwatch currently doesn’t offer or recommend setting a sample rate for a specific job. However, you could achieve this by adding the following to the start of your job: 
use Laravel\Nightwatch\Facades\Nightwatch;

class MyJob
{
    public function handle()
    {
        Nightwatch::sample(rate: 0.5); // Sample 50%

        // ...
    }
}

​
Event Filtering

In addition to sampling, you can filter out specific events entirely. This allows you to focus your event allocation on the events that matter most to your application. When an event is filtered, it is completely excluded from collection, no data will be sent to Nightwatch, and the event will not appear in your stream, traces, or usage metrics.

​
Filtering With a Callback

Nightwatch provides the following methods that allow you to filter events using a callback function:
  • Nightwatch::rejectCacheEvents()
  • Nightwatch::rejectMail()
  • Nightwatch::rejectNotifications()
  • Nightwatch::rejectOutgoingRequests()
  • Nightwatch::rejectQueries()
  • Nightwatch::rejectQueuedJobs()
For example, you may wish to filter out cache events based on the cache key:
AppServiceProvider.php
use Laravel\Nightwatch\Facades\Nightwatch;
use Laravel\Nightwatch\Records\CacheEvent;

Nightwatch::rejectCacheEvents(function (CacheEvent $cacheEvent) {
    return in_array($cacheEvent->key, [
        'illuminate:foundation:down',
        'illuminate:queue:restart',
        'illuminate:schedule:interrupt',
    ]);
});
Filtering events can help to conserve your event quota, but may also hide issues in your application. In the above example, if your cache service was responding slowly, your queue throughput would be reduced, but you wouldn’t have visibility as to why.
Nightwatch will not capture events during the callback to prevent infinite recursion.

​
Filtering Underlying Query Events

You may also wish to filter events that are already represented. For example, if you are using the database queue or cache driver, you may wish to exclude the underlying queries: 
use Laravel\Nightwatch\Facades\Nightwatch;
use Laravel\Nightwatch\Records\Query;

Nightwatch::rejectQueries(function (Query $query) {
    return str_contains($query->sql, 'into "jobs"');
});

Nightwatch::rejectQueries(function (Query $query) {
    return str_contains($query->sql, ' from "cache"')
        || str_contains($query->sql, ' into "cache"');
});

​
Filtering all Events of a Specific Type

Set any of the following environment variables in your .env file to true to disable collection of that event type:
  • NIGHTWATCH_IGNORE_CACHE_EVENTS — Exclude all cache events
  • NIGHTWATCH_IGNORE_MAIL — Exclude all mail events
  • NIGHTWATCH_IGNORE_NOTIFICATIONS — Exclude all notification events
  • NIGHTWATCH_IGNORE_OUTGOING_REQUESTS — Exclude all outgoing HTTP requests
  • NIGHTWATCH_IGNORE_QUERIES — Exclude all database queries

​
Ignoring Cache Events

For applications that make heavy use of caching, cache events can consume a significant portion of your quota. By filtering them out, you can preserve more of your allocation for higher-value signals like queries, jobs, and exceptions. To ignore cache events, add the following to your .env file: 
NIGHTWATCH_IGNORE_CACHE_EVENTS=true

​
Nightwatch Sampling Philosophy

Nightwatch collects rich, contextually linked data related to the events that happen in Laravel applications. Fundamentally, any event which occurs in a Laravel application can be traced back to one of three entry points; a request, command, or scheduled task. When Nightwatch samples the data generated by your application, it aims to preserve the relationship between these entry points and all of the events they trigger (e.g. jobs, exceptions, queries, etc). As a result, reducing the sampling rate for the entry point which triggers these other events, will also reduce the number of jobs, queries, cache events, etc. which are collected. This ensures that despite reducing the overall volume, for any captured event you are still able to look at a full picture of every other related event which occurred, ensuring that you always have the most complete understanding possible of how your application is behaving. All applications are different, however, and for some this approach won’t give the best signal to noise ratio. This is why we allow more fine-grained control of sampling and filtering of events, so that you can tune Nightwatch to capture the data which best suits your specific needs. The dynamic sampling and filtering methods described above allow flexible control of what is captured and at what rate, to help you achieve the best result. For example, while global sampling of jobs is not configurable using an environment variable (for the reasons outlined above), it is possible to de-couple the sampling of jobs from the sample rates of their parent entry points:
AppServiceProvider.php
use Illuminate\Support\Facades\Queue;
use Laravel\Nightwatch\Facades\Nightwatch;

Queue::before(fn () => Nightwatch::sample(rate: 0.5));
It should noted, however, that this may necessarily lead to the request, command or scheduled task that triggered a captured job not being captured, or a job triggered by a captured request, command, or scheduled task not being captured, which could lead to a less complete view of how your application is performing.