### Enable and Start systemd Service

Source: https://nightwatch.laravel.com/docs/guides/other-providers

After creating and configuring the systemd service file, reload the systemd daemon, enable the service to start on boot, and then start the service.

```bash
sudo systemctl daemon-reload
sudo systemctl enable nightwatch-agent
sudo systemctl start nightwatch-agent
```

--------------------------------

### Install Supervisor

Source: https://nightwatch.laravel.com/docs/guides/other-providers

If you prefer using Supervisor for process management, install it using apt.

```bash
sudo apt install supervisor
```

--------------------------------

### Example Log Level Configuration

Source: https://nightwatch.laravel.com/docs/logs

This example demonstrates setting different log levels for Laravel's single channel and Nightwatch within a stack configuration. Single logs warnings and higher, while Nightwatch logs errors and higher.

```bash
LOG_CHANNEL=stack
LOG_STACK=single,nightwatch
LOG_LEVEL=warning
NIGHTWATCH_LOG_LEVEL=error
```

--------------------------------

### Start the Nightwatch Agent

Source: https://nightwatch.laravel.com/docs/start-guide

Run the Nightwatch agent using the Artisan command to start collecting and sending data.

```bash
php artisan nightwatch:agent
```

--------------------------------

### Update Supervisor and Start Process

Source: https://nightwatch.laravel.com/docs/guides/other-providers

After creating the Supervisor configuration file, reread the Supervisor configuration, update the running processes, and start the Nightwatch agent.

```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start nightwatch-agent
```

--------------------------------

### Example SQL Query with Bindings

Source: https://nightwatch.laravel.com/docs/queries

Illustrates a SQL query using a question mark (?) to represent a bound parameter, which Nightwatch redacts for security.

```sql
select * from users where email = ?
```

--------------------------------

### Webhook Setup

Source: https://nightwatch.laravel.com/docs/webhooks

Instructions on how to configure a webhook in your Nightwatch Laravel application settings.

```APIDOC
## Webhook Setup

### Description
Configure webhooks to receive HTTP POST notifications when events occur in your application. Only one webhook per application is allowed.

### Steps
1. Open your application settings in the Nightwatch dashboard.
2. Navigate to the **Webhooks** section.
3. Configure your webhook with a **Name** (descriptive label) and an **URL** (HTTPS endpoint).

### Note
To change the URL or name, edit the existing webhook configuration.
```

--------------------------------

### Run Laravel Boost Installation

Source: https://nightwatch.laravel.com/docs/mcp-server

Execute this command in your terminal to automatically configure the Nightwatch MCP server if your application uses Laravel Boost.

```bash
php artisan boost:install
```

--------------------------------

### Install Nightwatch Package with Composer

Source: https://nightwatch.laravel.com/docs/guides/cloud

Use this command to install the Laravel Nightwatch package locally. Ensure this is done before deploying to update your composer files.

```bash
composer require laravel/nightwatch
```

--------------------------------

### Add Nightwatch Environment Variables

Source: https://nightwatch.laravel.com/docs/guides/other-providers

Add these environment variables to your application's .env file after installing the Nightwatch package. Ensure NIGHTWATCH_TOKEN is set correctly. Restart the service if NIGHTWATCH_TOKEN is modified after the service has started.

```bash
NIGHTWATCH_TOKEN=your-api-key
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0
```

--------------------------------

### Configure Supervisor for Nightwatch Agent

Source: https://nightwatch.laravel.com/docs/guides/other-providers

Add this configuration to the nightwatch-agent.conf file. It specifies the program name, command to execute, working directory, user, and logging options. Ensure the command path and directory are correct for your setup.

```ini
[program:nightwatch-agent]
process_name=%(program_name)s
command=php /var/www/your-app/artisan nightwatch:agent
directory=/var/www/your-app
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/supervisor/nightwatch-agent.log
```

--------------------------------

### Sample Specific Job

Source: https://nightwatch.laravel.com/docs/jobs

Apply a dynamic sample rate for a specific job by calling `Nightwatch::sample()` at the start of the job's `handle` method. This allows for granular control over job event capture.

```php
use Laravel\Nightwatch\Facades\Nightwatch;

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

        // ...
    }
}
```

--------------------------------

### Configure Package Route Sampling

Source: https://nightwatch.laravel.com/docs/requests

Modify middleware applied to package routes through configuration files. This example shows how to add Nightwatch's Sample middleware to Laravel Nova's internal routes.

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

--------------------------------

### Run Nightwatch Agent with Artisan Command

Source: https://nightwatch.laravel.com/docs/guides/cloud

This command is used to start the Nightwatch agent as a background process in your Laravel Cloud application cluster. Ensure it's added as a custom worker.

```bash
php artisan nightwatch:agent
```

--------------------------------

### Configure Nightwatch Webhook Secret in Laravel

Source: https://nightwatch.laravel.com/docs/webhooks

This configuration example shows how to store your Nightwatch webhook signing secret. It is recommended to use environment variables for security.

```php
return [
    // Other service configurations...
    
    'nightwatch' => [
        'webhook_secret' => env('NIGHTWATCH_WEBHOOK_SECRET'),
    ],
];
```

--------------------------------

### Create Supervisor Configuration File

Source: https://nightwatch.laravel.com/docs/guides/other-providers

Create a new configuration file for the Nightwatch agent within the Supervisor configuration directory.

```bash
sudo nano /etc/supervisor/conf.d/nightwatch-agent.conf
```

--------------------------------

### Configure systemd Service

Source: https://nightwatch.laravel.com/docs/guides/other-providers

Add this configuration to the nightwatch-agent.service file. It defines the service description, execution command, user, and restart policy. Adjust WorkingDirectory to your application's path.

```ini
[Unit]
Description=Laravel Nightwatch Agent
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/your-app
ExecStart=/usr/bin/php artisan nightwatch:agent
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Apply Sampling Rate to Unmatched Routes

Source: https://nightwatch.laravel.com/docs/changelog

Monitor bot traffic or other unmatched requests by applying the Sample middleware to fallback routes.

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

// Applied to unmatched 404 routes
Route::fallback(fn () => abort(404))
    ->middleware(Sample::rate(0.1));
```

--------------------------------

### Create systemd Service File

Source: https://nightwatch.laravel.com/docs/guides/other-providers

Create a systemd service file for the Nightwatch agent to ensure it runs automatically on boot and restarts if it crashes. This is recommended for production deployments on Ubuntu systems.

```bash
sudo nano /etc/systemd/system/nightwatch-agent.service
```

--------------------------------

### Sample Specific Scheduled Tasks with Nightwatch

Source: https://nightwatch.laravel.com/docs/scheduled-tasks

Apply custom sampling rates to individual scheduled tasks using the Sample class in routes/console.php. Use Sample::rate() for a percentage, Sample::always() to always sample, or Sample::never() to exclude.

```php
use Illuminate\Support\Facades\Schedule;
use Laravel\Nightwatch\Console\Sample;

// Sample a task 50% of executions
Schedule::command('app:daily-report')->daily()->tap(Sample::rate(0.5));

// Always sample a task
Schedule::command('app:upload-post')->daily()->tap(Sample::always());

// Never sample a task
Schedule::command('app:process-comments')->everyHour()->tap(Sample::never());
```

--------------------------------

### Add and Authenticate Nightwatch MCP Server for OpenCode

Source: https://nightwatch.laravel.com/docs/mcp-server

Use `opencode mcp add` to add the server, selecting remote and entering the URL. Then, authenticate using the provided command.

```bash
opencode mcp auth nightwatch
```

--------------------------------

### Add Tenant Context for Debugging

Source: https://nightwatch.laravel.com/docs/requests

Integrate tenant-specific details into the request context to aid in debugging multi-tenant application issues. Ensure the $tenant variable is available in the scope.

```php
use Illuminate\Support\Facades\Context;

Context::add('tenant', [
    'id' => $tenant->id,
    'name' => $tenant->name,
    'plan' => $tenant->subscription_plan,
    'region' => $tenant->region,
]);
```

--------------------------------

### Example Resolved Issue Payload

Source: https://nightwatch.laravel.com/docs/webhooks

This JSON payload represents a resolved issue event, including details about the issue, the actor who resolved it, and associated application and webhook information. It is typically sent when an issue is marked as resolved within the Nightwatch system.

```json
{
  "event": "issue.resolved",
  "timestamp": "2026-02-18T12:00:00.000000Z",
  "payload": {
    "issue": {
      "id": "9d4e2c1a-1234-5678-abcd-ef0123456789",
      "ref": 42,
      "type": "exception",
      "title": "Illuminate\\Database\\QueryException: SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry '1' for key 'flights_id_unique' (Connection: mysql, SQL: insert into \"flights\" (\"id\", \"name\", \"created_at\", \"updated_at\") values (?, ?, ?, ?))",
      "status": "resolved",
      "priority": "high",
      "url": "https://nightwatch.laravel.com/us/applications/cf592d1a-5f91-4f3c-9c10-8c67013c4469/issues/42",
      "details": {
        "type": "exception",
        "handled": false,
        "class": "Illuminate\\Database\\QueryException",
        "message": "SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry '1' for key 'flights_id_unique' (Connection: mysql, SQL: insert into \"flights\" (\"id\", \"name\", \"created_at\", \"updated_at\") values (?, ?, ?, ?))",
        "file": "app/Actions/ProcessFlight.php",
        "line": 123,
        "laravel_version": "12.52.0",
        "php_version": "8.4.11"
      }
    },
    "actor": {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "type": "user"
    },
    "webhook_id": "fa2d5c2d-3b8c-41ad-8cf6-52f80d446818",
    "application_id": "cf592d1a-5f91-4f3c-9c10-8c67013c4469",
    "organization_id": "9cfeeac6-d449-4924-852b-c3a3294db9c2"
  }
}
```

--------------------------------

### Capture Default Vendor Commands

Source: https://nightwatch.laravel.com/docs/commands

Opt-in to collecting framework and first-party package commands that are typically ignored by Nightwatch by default. Use this in AppServiceProvider.

```php
use Laravel\Nightwatch\Facades\Nightwatch;

public function boot(): void
{
    Nightwatch::captureDefaultVendorCommands();
}
```

--------------------------------

### Apply Sampling Rate to Single Route

Source: https://nightwatch.laravel.com/docs/changelog

Use the Sample middleware with a specific rate to control event capture for a single route.

```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.8));
```

--------------------------------

### Configure Environment Token

Source: https://nightwatch.laravel.com/docs/start-guide

Add your environment's NIGHTWATCH_TOKEN to your .env file for authentication.

```dotenv
NIGHTWATCH_TOKEN=your-api-key
```

--------------------------------

### Add Nightwatch MCP Server via VS Code Command Palette

Source: https://nightwatch.laravel.com/docs/mcp-server

Open the VS Code Command Palette, select 'MCP: Add Server', and enter the provided URL to configure the Nightwatch MCP server.

```plaintext
https://nightwatch.laravel.com/mcp
```

--------------------------------

### Run nightwatch:deploy Artisan command

Source: https://nightwatch.laravel.com/docs/deployments

Use the `nightwatch:deploy` Artisan command to report deployments. This command can be used with or without arguments and options to provide deployment details.

```bash
php artisan nightwatch:deploy [deploy] [--ref=] [--name=] [--url=] [--timestamp=]
```

```bash
php artisan nightwatch:deploy
```

```bash
php artisan nightwatch:deploy --ref=1a50baf --name="v1.2.3"
```

```bash
php artisan nightwatch:deploy --ref=1a50baf \
  --name="v1.2.3" \
  --url="https://github.com/myorg/myapp/releases/tag/v1.2.3"
```

--------------------------------

### Configure Nightwatch MCP Server for Cursor

Source: https://nightwatch.laravel.com/docs/mcp-server

Add this JSON configuration to your `.cursor/mcp.json` file to set up the Nightwatch MCP server for Cursor.

```json
{
  "mcpServers": {
    "nightwatch": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://nightwatch.laravel.com/mcp"]
    }
  }
}
```

--------------------------------

### Add Tenant Context in PHP

Source: https://nightwatch.laravel.com/docs/context

Add tenant-specific context, including ID, name, plan, and region, to help debug multi-tenant issues. Requires Laravel 11.x or later.

```php
use Illuminate\Support\Facades\Context;

Context::add('tenant', [
    'id' => $tenant->id,
    'name' => $tenant->name,
    'plan' => $tenant->subscription_plan,
    'region' => $tenant->region,
]);
```

--------------------------------

### Sample Unmatched Routes for Bot Traffic

Source: https://nightwatch.laravel.com/docs/requests

Set sample rates for bot traffic using the Sample middleware with Laravel's fallback route. This helps identify and block unwanted requests by sampling unmatched 404 routes.

```php
// Applied to unmatched 404 routes
Route::fallback(fn () => abort(404))
    ->middleware(Sample::rate(0.5));
```

--------------------------------

### Create Custom Log Stack with Nightwatch

Source: https://nightwatch.laravel.com/docs/logs

Integrate Nightwatch into a custom log stack by specifying it alongside other channels in your .env file.

```env
LOG_CHANNEL=stack
LOG_STACK=syslog,nightwatch
```

--------------------------------

### Implement Dynamic Request Sampling

Source: https://nightwatch.laravel.com/docs/requests

Use dynamic sampling based on request attributes like user roles. This middleware samples requests if the user is an admin, otherwise it proceeds without sampling.

```php
use Closure;
use Illuminate\Http\Request;
use Laravel\Nightwatch\Facades\Nightwatch;
use Symfony\Component\HttpFoundation\Response;

class SampleAdminRequests
{
    public function handle(Request $request, Closure $next): Response
    {
        if (! $user = $request->user()) {
            return $next($request);
        }

        if ($user->isAdmin()) {
            Nightwatch::sample();

            return $next($request);
        }

        return $next($request);
    }
}
```

```php
use App\Http\Middleware\SampleAdminRequests;

Route::middleware(SampleAdminRequests::class)->group(function () {
    // ...
});
```

--------------------------------

### Configure Sampling Rates for Nightwatch

Source: https://nightwatch.laravel.com/docs/filtering

Set environment variables to control the sampling rate for exceptions, commands, and requests. The request sample rate is recommended to be set to 0.1 for new applications.

```bash
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1 # Recommended
```

--------------------------------

### Capture Default Vendor Cache Keys

Source: https://nightwatch.laravel.com/docs/cache

Opt in to collecting cache events generated from Laravel's internal systems and first-party packages. Be aware this can significantly increase the number of events captured.

```php
use Laravel\Nightwatch\Facades\Nightwatch;

public function boot(): void
{
    Nightwatch::captureDefaultVendorCacheKeys();
}
```

--------------------------------

### Apply Sampling Rate to Route Group

Source: https://nightwatch.laravel.com/docs/changelog

Apply a custom sampling rate to a group of routes using the Sample middleware.

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

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

--------------------------------

### Configure Kubernetes Deployment with Nightwatch Agent

Source: https://nightwatch.laravel.com/docs/guides/docker

Sets up a Kubernetes deployment for a Laravel application, including the Nightwatch agent as a separate container. The agent uses the application container image and is configured with environment variables and a liveness probe.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: laravel-app
  namespace: default
  labels:
    component: laravel-app
spec:
  replicas: 2
  strategy:
    type: Recreate
  selector:
    matchLabels:
      component: laravel-app
  template:
    metadata:
      name: laravel-app
      namespace: default
      labels:
        component: laravel-app
    spec:
      containers:
        - name: app
          image: myregistry/laravel-app:latest
          imagePullPolicy: Always
          env:
            - name: NIGHTWATCH_TOKEN
              secretKeyRef:
                name: nightwatch-token-secret
                key: production-token
            - name: NIGHTWATCH_REQUEST_SAMPLE_RATE
              value: "0.1"
            - name: NIGHTWATCH_COMMAND_SAMPLE_RATE
              value: "1.0"
            - name: NIGHTWATCH_EXCEPTION_SAMPLE_RATE
              value: "1.0"
          # ...
        - name: nightwatch-agent
          image: myregistry/laravel-app:latest
          imagePullPolicy: Always
          command: ["php", "artisan", "nightwatch:agent"]
          env:
            - name: NIGHTWATCH_TOKEN
              secretKeyRef:
                name: nightwatch-token-secret
                key: production-token
          livenessProbe:
            exec:
              command: ["php", "artisan", "nightwatch:status"]
            failureThreshold: 3
            initialDelaySeconds: 5
            periodSeconds: 30
            timeoutSeconds: 5

```

--------------------------------

### Docker Compose for Local Development with Nightwatch Agent

Source: https://nightwatch.laravel.com/docs/guides/docker

This Docker Compose configuration sets up an application container and the Nightwatch Agent service for local development. Ensure that the NIGHTWATCH_TOKEN and NIGHTWATCH_INGEST_URI environment variables are correctly set for both the application and any other services like schedulers or workers that need to communicate with the agent.

```yaml
version: "3.8"

services:
  app:
    # ...
    environment:
      - NIGHTWATCH_TOKEN=<your Nightwatch environment token>
      - NIGHTWATCH_INGEST_URI=nightwatch-agent:2407
    # ...
    networks:
      - sail

  nightwatch-agent:
    image: laravelphp/nightwatch-agent:latest
    environment:
      - NIGHTWATCH_TOKEN=<your Nightwatch environment token>
    healthcheck:
      test: php nightwatch-status
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 5s
    restart: unless-stopped
    networks:
      - sail
  
  # If you have separate containers for queue workers or schedulers, you would need to add the same environment variables.
  scheduler:
    # ...
    environment:
      - NIGHTWATCH_TOKEN=<your Nightwatch environment token>
      - NIGHTWATCH_INGEST_URI=nightwatch-agent:2407
    # ...
    networks:
      - sail
  
  worker:
    # ...
    environment:
      - NIGHTWATCH_TOKEN=<your Nightwatch environment token>
      - NIGHTWATCH_INGEST_URI=nightwatch-agent:2407
    # ...
    networks:
      - sail

networks:
  sail:
    driver: bridge
```

--------------------------------

### Report deployments via Nightwatch API

Source: https://nightwatch.laravel.com/docs/deployments

If the Artisan command is not accessible, report deployments directly to the Nightwatch API using a cURL request. Ensure you include your NIGHTWATCH_TOKEN for authorization.

```bash
curl -X POST https://nightwatch.laravel.com/api/deployments \
  -H "Authorization: Bearer $NIGHTWATCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "deploy": "$NIGHTWATCH_DEPLOY",
  "ref": "1a50baf",
  "name": "v1.2.3",
  "url": "https://github.com/myorg/myapp/releases/tag/v1.2.3"
}
EOF
```

--------------------------------

### Set Global Request Sample Rate

Source: https://nightwatch.laravel.com/docs/requests

Configure global sampling for HTTP requests using the NIGHTWATCH_REQUEST_SAMPLE_RATE environment variable. This samples a percentage of all requests.

```bash
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1 # Sample 10% of requests
```

--------------------------------

### Exclude Specific Commands from Sampling

Source: https://nightwatch.laravel.com/docs/commands

Listen for the CommandStarting event in AppServiceProvider to conditionally prevent specific Artisan commands from being sampled by Nightwatch.

```php
use Illuminate\Console\Events\CommandStarting;
use Illuminate\Support\Facades\Event;
use Laravel\Nightwatch\Facades\Nightwatch;

public function boot(): void
{
    Event::listen(function (CommandStarting $event) {
        if (in_array($event->command, [
            'schedule:finish',
            // ...
        ])) {
            Nightwatch::dontSample();
        }
    });
}
```

--------------------------------

### Environment Variables for Manual Integration

Source: https://nightwatch.laravel.com/docs/guides/cloud

Set these environment variables in your Laravel Cloud environment before running the Nightwatch agent manually. The recommended sample rates are provided.

```bash
NIGHTWATCH_TOKEN=your-api-key
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1 #recommended
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0
```

--------------------------------

### Report Deployment with GitHub Actions

Source: https://nightwatch.laravel.com/docs/deployments

Use this snippet in your GitHub Actions workflow to report a deployment to Nightwatch. It requires the commit SHA, branch name, and the deployment URL.

```yaml
- name: Report deployment to Nightwatch
  run: php artisan nightwatch:deploy --ref=${{ github.sha }} --name="${{ github.ref_name }}" --url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
```

--------------------------------

### Filter Cache Events by Key Patterns

Source: https://nightwatch.laravel.com/docs/cache

Filter cache events by their exact cache key or by using regular expression patterns for key matching. This allows for fine-grained control over which cache events are captured.

```php
use Laravel\Nightwatch\Facades\Nightwatch;

public function boot(): void
{
    Nightwatch::rejectCacheKeys([
        'my-app:users',
        '/^my-app:posts:/',
        '/^[a-zA-Z0-9]{40}$/',
    ]);
}
```

--------------------------------

### Set Nightwatch as Exclusive Log Channel

Source: https://nightwatch.laravel.com/docs/logs

Configure your .env file to send all logs exclusively to Nightwatch. Use with caution if sampling is enabled, as some logs might be missed.

```env
LOG_CHANNEL=nightwatch
```

--------------------------------

### Configure Environment Variables for Nightwatch Agent

Source: https://nightwatch.laravel.com/docs/guides/vapor

Add these environment variables to your worker server's site configuration to connect the Nightwatch Agent to your Vapor application. Ensure NIGHTWATCH_INGEST_URI uses the private IP of your worker server.

```bash
NIGHTWATCH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NIGHTWATCH_INGEST_URI=10.0.0.x:2407
```

--------------------------------

### Synchronize Vapor Deployment with EC2 using Curl

Source: https://nightwatch.laravel.com/docs/guides/vapor

Use curl to ping the Forge Deployment Trigger URL during the deploy step in your vapor.yml file. This ensures the Nightwatch Agent version on your EC2 instance stays in sync with your Vapor application.

```yaml
build:
    - 'composer install --no-dev'
    - 'php artisan event:cache'
    - 'npm ci && npm run build && rm -rf node_modules'
    # Deploy Forge Site...
    - 'curl https://forge.laravel.com/servers/{server}/sites/{site}/deploy/http?token={token}'
```

--------------------------------

### Run Multiple Agents on a Single Server

Source: https://nightwatch.laravel.com/docs/start-guide

Configure and run separate Nightwatch agent processes for multiple Laravel applications on the same server, each on its own port.

```bash
# 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
```

--------------------------------

### Add Nightwatch MCP Server for Codex

Source: https://nightwatch.laravel.com/docs/mcp-server

Configure the Nightwatch MCP server for Codex by running this command in your terminal.

```bash
codex mcp add nightwatch --url https://nightwatch.laravel.com/mcp
```

--------------------------------

### Use Nightwatch MCP Server URL with Other Clients

Source: https://nightwatch.laravel.com/docs/mcp-server

This is the server URL for MCP-compatible tools. If your client does not support remote servers, use `mcp-remote`.

```plaintext
https://nightwatch.laravel.com/mcp
```

```bash
npx -y mcp-remote https://nightwatch.laravel.com/mcp
```

--------------------------------

### Filter Specific Queries (PostgreSQL)

Source: https://nightwatch.laravel.com/docs/queries

Programmatically reject specific database queries, such as those related to 'jobs' or 'cache', within the AppServiceProvider. This helps conserve event quotas but may hide performance issues.

```php
// AppServiceProvider.php

use Laravel\Nightwatch\Facades\Nightwatch;
use Laravel\Nightwatch\Records\Query;

public function boot(): void
{
    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"');
    });
}
```

--------------------------------

### Combine First and Last Name for User Name

Source: https://nightwatch.laravel.com/docs/user

Use the `Nightwatch::user` method within your `AppServiceProvider` to combine `first_name` and `last_name` attributes for the user's name.

```php
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,
]);
```

--------------------------------

### React Component for Displaying Environment Variables

Source: https://nightwatch.laravel.com/docs/environment-variables

This React component is used to render environment variable information, including its name, default value, and a description. It formats the output with specific styling for clarity.

```javascript
export const EnvVar = props => {
  const slug = props.name.toLowerCase().replace(/_/g, '-');
  return <div className="field pt-2.5 pb-5 my-2.5 border-gray-50 dark:border-gray-800/50 border-b scroll-mt-20" id={slug}>
      <div className="flex items-baseline gap-3 flex-wrap">
        <a href={'#' + slug} className="border-none">
          <code className="text-sm font-semibold !text-blue-500 p-0 !bg-transparent">{props.name}</code>
        </a>
        {props.default && <div className="font-mono text-xs px-2 py-0.5 rounded-md bg-gray-100/50 dark:bg-white/5 text-gray-600 dark:text-gray-200 font-medium break-all">
            <span className="text-gray-400 dark:text-gray-500">default: </span>
            <span>{props.default}</span>
          </div>}
        {props.required && <span className="font-mono text-xs px-2 py-0.5 rounded-md bg-red-100/50 dark:bg-red-400/10 text-red-600 dark:text-red-300 font-medium whitespace-nowrap">required</span>}
      </div>
      <div className="mt-4 prose-sm prose-gray dark:prose-invert [&_.prose>p:first-child]:mt-0 [&_.prose>p:last-child]:mb-0">
        {props.children}
      </div>
    </div>;
};
```

--------------------------------

### Add Nightwatch MCP Server for Claude Code

Source: https://nightwatch.laravel.com/docs/mcp-server

Use this command to add the Nightwatch MCP server for use with Claude Code. After running, use `/mcp` in a Claude Code session to complete authentication.

```bash
claude mcp add --transport http nightwatch https://nightwatch.laravel.com/mcp
```

--------------------------------

### Set Log Level for Nightwatch

Source: https://nightwatch.laravel.com/docs/changelog

Configure NIGHTWATCH_LOG_LEVEL to 'warning' to send only logs at the warning level or higher to Nightwatch. Lower-level logs like info or debug will be ignored.

```bash
NIGHTWATCH_LOG_LEVEL=warning
```

--------------------------------

### Control Event Capture with Nightwatch::pause and Nightwatch::resume

Source: https://nightwatch.laravel.com/docs/filtering

Manually pause and resume event capturing using Nightwatch::pause() and Nightwatch::resume(). This provides fine-grained control over which operations are monitored, useful when callback-based filtering is not feasible.

```php
use App\Jobs\SyncUsers;
use App\Models\User;
use Laravel\Nightwatch\Facades\Nightwatch;

/*
 * Nightwatch will not capture the query, the queued job, or the job's attempts.
 */

Nightwatch::pause();

$users = User::get();

SyncUsers::dispatch($users);

Nightwatch::resume();
```

--------------------------------

### Report Deployment with Laravel Envoyer

Source: https://nightwatch.laravel.com/docs/deployments

Integrate this command into your Laravel Envoyer deployment script to notify Nightwatch. It uses environment variables for commit SHA and branch name.

```bash
php artisan nightwatch:deploy {{ sha }} --name="{{ branch }}"
```

--------------------------------

### Configure Global Command Sampling Rate

Source: https://nightwatch.laravel.com/docs/commands

Set the NIGHTWATCH_COMMAND_SAMPLE_RATE environment variable to control the percentage of Artisan commands sampled. A value of 1.0 samples 100% of commands.

```bash
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0 # Sample 100% of commands
```

--------------------------------

### Decouple Job Sampling in AppServiceProvider

Source: https://nightwatch.laravel.com/docs/jobs

De-couple the sampling of jobs from their parent execution contexts by using `Queue::before` in `AppServiceProvider`. This ensures jobs are sampled independently.

```php
use Illuminate\support\Facades\Queue;
use Laravel\Nightwatch\Facades\Nightwatch;

public function boot(): void
{
    Queue::before(fn () => Nightwatch::sample(rate: 0.5));
}
```

--------------------------------

### Filter Specific Queries (MySQL)

Source: https://nightwatch.laravel.com/docs/queries

Programmatically reject specific database queries, such as those related to 'jobs' or 'cache', within the AppServiceProvider. This helps conserve event quotas but may hide performance issues.

```php
// AppServiceProvider.php

use Laravel\Nightwatch\Facades\Nightwatch;
use Laravel\Nightwatch\Records\Query;

public function boot(): void
{
    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`');
    });
}
```

--------------------------------

### Customize User ID for Multi-Tenant Apps

Source: https://nightwatch.laravel.com/docs/user

Customize the user ID to include a tenant identifier when user IDs are not unique across tenants, ensuring proper identification within Nightwatch.

```php
Nightwatch::user(fn (Authenticatable $user) => [
    'id' => "{$user->tenant_id}-{$user->id}",
    'name' => $user->name,
    'username' => $user->email,
]);
```

--------------------------------

### Capture Default Vendor Commands in Laravel

Source: https://nightwatch.laravel.com/docs/changelog

To enable the capture of ignored vendor commands, call the `Nightwatch::captureDefaultVendorCommands()` method in a service provider. Read more about commands in the documentation.

```php
Nightwatch::captureDefaultVendorCommands()
```

--------------------------------

### Filter Cache Events Using a Callback

Source: https://nightwatch.laravel.com/docs/cache

Apply custom logic to filter each cache event by providing a callback function. This is useful for complex filtering requirements based on event properties.

```php
use Laravel\Nightwatch\Facades\Nightwatch;
use Laravel\Nightwatch\Records\CacheEvent;

public function boot(): void
{
    Nightwatch::rejectCacheEvents(function (CacheEvent $cacheEvent) {
        return str_starts_with($cacheEvent->key, 'temp:');
    });
}
```

--------------------------------

### Manually Report an Exception

Source: https://nightwatch.laravel.com/docs/exceptions

Explicitly report an exception using the Nightwatch facade if it's not being captured automatically. This is typically needed in rare scenarios.

```php
use Laravel\Nightwatch\Facades\Nightwatch;

Nightwatch::report($e);
```

--------------------------------

### Set Global Sampling Rate for Scheduled Tasks

Source: https://nightwatch.laravel.com/docs/scheduled-tasks

Configure the global sampling rate for all scheduled tasks using the NIGHTWATCH_SCHEDULED_TASK_SAMPLE_RATE environment variable. Set to 1.0 to sample 100% of tasks. This takes precedence over NIGHTWATCH_COMMAND_SAMPLE_RATE.

```bash
NIGHTWATCH_SCHEDULED_TASK_SAMPLE_RATE=1.0 # Sample 100% of tasks
```