Sampling

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.

​

Recommended Starting Point

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.

​

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 Illuminate\Laravel\Support\Route;
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:

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 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