​
Manually Reporting Exceptions

Nightwatch automatically listens to all exceptions reported within your Laravel application: 
report($e); // Nightwatch will capture this exception...
If you’re not seeing an exception in your Nightwatch dashboard, you can explicitly report it using the facade: 
use Laravel\Nightwatch\Facades\Nightwatch;

Nightwatch::report($e);
📘 This is only needed in rare cases where exceptions are not captured automatically.

​
Reporting Manually Failed Jobs

If you want to report a manually failed job, you need to manually report an exception. 
/**
 * Execute the job.
 */
public function handle(): void
{
    // ...

    report($e);

    $this->fail($e);
}

​
Customizing User Details

Nightwatch automatically captures details about the authenticated user when an event occurs. By default, it captures the user’s id, name, and email attributes. Sometimes you may need to adjust what is captured, for example:
  • Your app uses first_name and last_name instead of a single name field.
  • You run a multi-tenant app where the user IDs are not unique across tenants.
  • You prefer not to store certain user details at all.
Nightwatch makes this easy with the Nightwatch::user method, which you can call inside your AppServiceProvider.

​
Customizing User Fields

Here’s an example of how you can combine first_name and last_name as the name field: 
use Illuminate\Contracts\Auth\Authenticatable;
use Laravel\Nightwatch\Facades\Nightwatch;

Nightwatch::user(fn (Authenticatable $user) => [
    'name' => "{$user->first_name} {$user->last_name}",
    'username' => $user->email,
]);

​
Customizing User IDs

In systems where user IDs may not be unique, such as multi-tenant apps with auto-incrementing IDs, you can customise the ID to include the tenant identifier so Nightwatch can tell them apart. 
Nightwatch::user(fn (Authenticatable $user) => [
    'id' => "{$user->tenant_id}-{$user->id}",
    'name' => $user->name,
    'username' => $user->email,
]);

​
Omitting User Fields

If you don’t want Nightwatch to capture certain fields, you can simply leave them out of the returned array. Note that the id will always be captured. 
// Exclude both fields...
Nightwatch::user(fn (Authenticatable $user) => []);

// Only include the name field...
Nightwatch::user(fn (Authenticatable $user) => [
    'name' => $user->name,
]);

​
Monitoring Guzzle Requests

Nightwatch automatically captures outgoing HTTP requests made via Laravel’s Http client. If you’re using Guzzle directly, you can still capture these requests by attaching Nightwatch’s middleware to your Guzzle stack. 
use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Handler\CurlHandler;
use Laravel\Nightwatch\Facades\Nightwatch;

// Set up the handler stack...
$stack = new HandlerStack;
$stack->setHandler(new CurlHandler);

// Push Nightwatch's middleware...
$stack->push(Nightwatch::guzzleMiddleware());

// Create the client with the stack...
$client = new Client(['handler' => $stack]);
Requests made by $client will now be monitored by Nightwatch.

​
Customizing the Agent Port

By default, the Nightwatch agent listens on port 2407. You can change this by setting a different ingest URI and using the --listen-on flag when starting the agent. To run the agent on port 2408, update your .env file: 
NIGHTWATCH_INGEST_URI=127.0.0.1:2408
Then start the agent using the matching port: 
php artisan nightwatch:agent --listen-on=127.0.0.1:2408

​
Running Multiple Agents

If you’re running more than one Laravel application or environment on the same server, you can run multiple Nightwatch agents in parallel — each on a unique port.
Each agent must use a different port. See Customizing the Agent Port for instructions on how to set this per instance.
Here’s an example setup running two agents in the one server: 
# App 1 - /var/www/app-1
NIGHTWATCH_INGEST_URI=127.0.0.1:2407
php artisan nightwatch:agent --listen-on=127.0.0.1:2407

# App 2 - /var/www/app-2
NIGHTWATCH_INGEST_URI=127.0.0.1:2408
php artisan nightwatch:agent --listen-on=127.0.0.1:2408

​
Unrecoverable Exceptions

If Nightwatch experiences an unrecoverable exception when recording events from your application, it can become unable to notify you of the issue. You may register a handler for these scenarios with the Nightwatch::handleUnrecoverableExceptionsUsing method. You should put this in your AppServiceProvider::register method:
AppServiceProvider.php
use Laravel\Nightwatch\Facades\Nightwatch;
use Illuminate\Support\Facades\Log;

Nightwatch::handleUnrecoverableExceptionsUsing(function ($e) {
    // Ensure the error is written to a channel other than the `nightwatch` channel.
    Log::channel('single')->error(
        'Nightwatch experienced an unrecoverable exception',
        ['exception' => $e]
    );
});
This may generate a large number of logs in cases where Nightwatch is not configured correctly and fails on every request to your application.