README

Dual Agent is a Laravel package that automatically saves all Nightwatch monitoring data to your application's database while maintaining full compatibility with the original Nightwatch service.

Requirements

PHP 8.2+
Laravel 10.0+
Laravel Nightwatch installed and configured with sampling rates set appropriately

Installation

Install the package:
```
composer require theihasan/dual-agent
```

Add service providers (after Nightwatch):

For Laravel 10: Add to config/app.php:

'providers' => [
    // ...
    \Laravel\Nightwatch\NightwatchServiceProvider::class,
    \Ihasan\DualAgent\DualAgentServiceProvider::class,
    // ...
],

For Laravel 11+: Add to bootstrap/app.php:

'providers' => [
    \Laravel\Nightwatch\NightwatchServiceProvider::class,
    \Ihasan\DualAgent\DualAgentServiceProvider::class,
]

Configure your .env file:

# Nightwatch Configuration
NIGHTWATCH_ENABLED=true
NIGHTWATCH_TOKEN=your-nightwatch-token
NIGHTWATCH_REQUEST_SAMPLE_RATE=1.0
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0

# Dual Agent Configuration
DUAL_AGENT_ENABLED=true
DUAL_AGENT_AUTO_CONFIGURE=true

Run the installer:
```
php artisan dual-agent:install
```

Configuration

Variable	Default	Description
`DUAL_AGENT_ENABLED`	`true`	Enable/disable database storage
`DUAL_AGENT_AUTO_CONFIGURE`	`true`	Auto-configure when Nightwatch detected
`DUAL_AGENT_BUFFER_SIZE`	`100`	Records to buffer before database insert
`DUAL_AGENT_REQUEST_SAMPLE_RATE`	`1.0`	Sampling rate for requests (0.0-1.0)
`DUAL_AGENT_QUERY_SAMPLE_RATE`	`0.1`	Sampling rate for database queries
`DUAL_AGENT_EXCEPTION_SAMPLE_RATE`	`1.0`	Sampling rate for exceptions
`DUAL_AGENT_JOB_SAMPLE_RATE`	`0.5`	Sampling rate for queue jobs
`DUAL_AGENT_LOG_SAMPLE_RATE`	`0.01`	Sampling rate for log entries
`DUAL_AGENT_CLEANUP_ENABLED`	`true`	Enable automatic data cleanup
`DUAL_AGENT_RETENTION_DAYS`	`30`	Days to retain metrics data
`DUAL_AGENT_AGGREGATION_ENABLED`	`true`	Enable metric aggregation

Type Safety

This package includes a comprehensive PHPStan configuration for maximum type safety. The configuration is set to level 9 with strict rules enabled.

Running Type Analysis

# Run PHPStan analysis
composer run phpstan

# Generate baseline for existing issues
composer run phpstan:baseline

# Clear PHPStan cache
composer run phpstan:clear

# Run type checking and tests together
composer run test:all

Configuration Files

phpstan.neon - Main PHPStan configuration with strict type checking
phpstan-baseline.neon - Baseline file for managing existing issues

The configuration includes:

Level 9 strictness with all strict rules enabled
Laravel-specific ignores for dynamic methods and facades
Type coverage requirements for all methods and properties
Dead code detection for unused private methods and properties
Strict comparison rules to prevent type coercion issues
Missing type hints detection for all parameters and return types

Basic Usage

Query your monitoring data using the provided models:

use Ihasan\DualAgent\Models\DualAgentMetric;

// Get today's requests
$requests = DualAgentMetric::requests()->today()->get();

// Find slow requests
$slowRequests = DualAgentMetric::slowRequests(1000)->get();

// Get recent exceptions
$exceptions = DualAgentMetric::exceptions()->latest()->limit(10)->get();

See full documentation for more query examples and available scopes.

Common Issues

Data Not Appearing

Ensure Nightwatch sampling rates are set appropriately in your .env:

NIGHTWATCH_REQUEST_SAMPLE_RATE=1.0
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0

Installation Fails

Make sure Laravel Nightwatch is installed first:

composer require laravel/nightwatch
php artisan migrate

Links to Full Documentation

Complete Documentation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Changelog

Please see CHANGELOG.md for recent changes.

Security

If you discover any security-related issues, please email theihasan@gmail.com instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.

Credits

Ihasan
Built for Laravel Nightwatch
Inspired by the Laravel community

theihasan / dual-agent

Maintainers

Details