Nightwatch Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require laravel/nightwatch
   

   Publish the config file:

   php artisan vendor:publish --provider="Laravel\Nightwatch\NightwatchServiceProvider"
   

2. Configure .env Add your Nightwatch API token and project ID:

   NIGHTWATCH_API_TOKEN=your_api_token_here
   NIGHTWATCH_PROJECT_ID=your_project_id_here
   

3. First Use Case: Track HTTP Requests Enable HTTP request monitoring in config/nightwatch.php:

   'http' => [
       'enabled' => true,
   ],
   

   No additional code needed—requests are automatically tracked.

Implementation Patterns

Core Workflows

1. Sampling and Ignoring Events

   • Sampling: Control event frequency via .env:

     NIGHTWATCH_COMMAND_SAMPLE_RATE=0.1  # 10% of commands
     NIGHTWATCH_SCHEDULED_TASK_SAMPLE_RATE=0.5  # 50% of tasks
     

   • Ignoring: Exclude specific events (e.g., CLI commands):

     Nightwatch::ignore('command', 'queue:work');
     

2. Custom Event Tracking

   • Manually log custom events:

     Nightwatch::event('custom.event', [
         'key' => 'value',
         'user_id' => auth()->id(),
     ]);
     

3. Deploy Tracking

   • Use the nightwatch:deploy command:

     php artisan nightwatch:deploy --message="Production release v1.0"
     

   • Automate with CI/CD (e.g., GitHub Actions):

     - run: php artisan nightwatch:deploy --message="Deployed via CI"
     

4. Exception Redaction

   • Redact sensitive data in exceptions:

     Nightwatch::redact('password', 'secret_*');
     

5. Vapor Sub-Minute Scheduling

   • Track vapor:schedule commands for sub-minute tasks:

     NIGHTWATCH_SCHEDULED_TASK_SAMPLE_RATE=0.3  # Applies to Vapor schedules
     

Integration Tips

• Queue Workers: Automatically tracked. Use NIGHTWATCH_QUEUE_SAMPLE_RATE to control frequency.
• Scheduled Tasks: Sub-minute tasks (including Vapor schedules) are supported. Configure via:

  NIGHTWATCH_SCHEDULED_TASK_SAMPLE_RATE=0.3
  

• Livewire/Blade: Ignore checksum failures:

  Nightwatch::ignore('cache', 'livewire-checksum-*');
  

Gotchas and Tips

Pitfalls

1. Sampling Conflicts

   • NIGHTWATCH_SCHEDULED_TASK_SAMPLE_RATE overrides NIGHTWATCH_COMMAND_SAMPLE_RATE for tasks. Set both explicitly if needed.

2. Token Expiry

   • Handle expired tokens gracefully. Nightwatch auto-retrieves tokens if NIGHTWATCH_API_TOKEN is missing.

3. Vendor Command Sampling

   • Disabled by default (e.g., octane:status). Re-enable via:

     Nightwatch::ignore('command', false); // Global override
     

4. Windows stdout/stderr

   • Use synchronous writes for consistency:

     Nightwatch::writeToStdout('Log message'); // Sync on Windows
     

5. Laravel 13 Compatibility

   • Ensure proper serialization for Laravel 13 projects. No additional config needed; the package now handles this internally.

Debugging

• Payload Buffering: Force immediate ingestion:

  Nightwatch::digest(); // Transmit pending events
  

• Log Inspection: Check storage/logs/nightwatch.log for agent activity.

Extension Points

1. Custom Metrics Extend the Nightwatch facade to log domain-specific data:

   Nightwatch::extend(function ($nightwatch) {
       $nightwatch->event('custom.metric', ['value' => $this->getMetric()]);
   });
   

2. Agent Configuration Override default behavior via service provider:

   public function boot()
   {
       Nightwatch::ignore('cache', 'my-custom-key-*');
   }
   

3. Boost Skills Use pre-built skills (e.g., configure-nightwatch) for common setups:

   php artisan boost:skill configure-nightwatch
   

4. Naming Conventions

   • Follow standardized naming for events and keys (e.g., snake_case for consistency). The package now enforces this internally.