## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require laravel/pulse
   php artisan pulse:install

This publishes the Pulse migration, config, and assets.

Run Migrations:
```
php artisan migrate
```
Start Pulse:
```
php artisan pulse:work
```
This starts the Pulse worker in the foreground. For production, use a process manager like Supervisor.
Access Dashboard: Visit /pulse in your browser (ensure your app is running).

First Use Case: Monitoring Requests

Pulse automatically tracks HTTP requests, queue jobs, and database queries.
Navigate to the Requests tab to see real-time metrics like response times, status codes, and error rates.
Use the Exceptions tab to debug errors with stack traces and context.

Implementation Patterns

Core Workflows

1. Real-Time Monitoring

Automatic Tracking: Pulse hooks into Laravel’s service container to monitor:
- HTTP requests (Illuminate\Http\Request).
- Queue jobs (Illuminate\Queue\Jobs\Job).
- Database queries (Illuminate\Database\Connection).
- Livewire interactions (Livewire\Component).

Custom Metrics: Extend Pulse by recording custom events:

use Laravel\Pulse\Facades\Pulse;

Pulse::record('custom_event', ['key' => 'value']);
Pulse::set('custom_metric', 42); // Incremental counter

2. Custom Cards

Create tailored dashboards using cards. Example: A card for tracking API rate limits.

// config/pulse.php
'cards' => [
    \App\Pulse\Cards\ApiRateLimitCard::class,
],

Implement the Laravel\Pulse\Contracts\Card contract:

namespace App\Pulse\Cards;

use Laravel\Pulse\Contracts\Card;

class ApiRateLimitCard implements Card {
    public function title(): string { return 'API Rate Limits'; }
    public function render(): string { /* ... */ }
    public function data(): array { return ['limits' => $this->fetchRateLimits()]; }
}

3. Environment-Specific Configuration

Disable Pulse in local environments or restrict access:

// config/pulse.php
'environments' => ['production', 'staging'],
'private_tunnel' => [
    'enabled' => env('PULSE_TUNNEL_ENABLED', false),
    'environments' => ['local'],
],

4. Data Retention

Configure how long data is retained (default: 30 days):

// config/pulse.php
'trim' => [
    'duration' => '30 days',
],

Run the trim command manually:

php artisan pulse:trim

5. Livewire Integration

Pulse tracks Livewire component interactions. For Livewire v4+:

// config/pulse.php
'livewire' => [
    'enabled' => true,
    'highlighting' => true, // Syntax highlighting for Livewire code
],

6. Queue Monitoring

Monitor queue jobs with:
- Job duration.
- Failure rates.
- Payload inspection. Configure thresholds for "slow" jobs:
```
// config/pulse.php
'thresholds' => [
    'jobs' => [
        'slow' => 5000, // ms
    ],
],
```

7. Database Query Analysis

Identify slow queries with:

Execution time.
Query binding inspection. Customize slow query thresholds:

// config/pulse.php
'thresholds' => [
    'queries' => [
        'slow' => 100, // ms
        'regex' => 'SELECT.*FOR UPDATE', // Custom regex patterns
    ],
],

8. Third-Party Services

Integrate with external tools (e.g., Sentry, Datadog) by extending Pulse’s Ingest logic:

// app/Providers/PulseServiceProvider.php
public function boot() {
    Pulse::ingest(function ($data) {
        // Forward data to Sentry, etc.
        Sentry::captureEvent($data);
    });
}

Gotchas and Tips

Pitfalls

Worker Process Management:
- Pulse requires a persistent worker (pulse:work). In production, use Supervisor or similar:
```
[program:pulse]
command=php /path/to/artisan pulse:work
autostart=true
autorestart=true
```
- Gotcha: Forgetting to restart the worker after config changes may cause stale data.
Database Load:
- Pulse stores raw request/queue data. For high-traffic apps, adjust trim.duration or use a read replica.
- Tip: Use pulse:trim --dry-run to test retention policies.
Livewire Version Conflicts:
- Pulse supports Livewire v3/v4. Ensure compatibility:
```
composer require livewire/livewire:^4.0
```
- Gotcha: Mixing Livewire versions may break Pulse’s Livewire card.

Private Tunnel Security:

The private_tunnel feature exposes Pulse in local environments. Restrict access:

'private_tunnel' => [
    'environments' => ['local'],
    'ip' => '192.168.1.100', // Whitelist IPs
],

Tip: Use .env to toggle:
```
PULSE_TUNNEL_ENABLED=false
```

Custom Card Caching:
- Cards are cached per request. Clear cache if data appears stale:
```
php artisan cache:clear
```
- Tip: Implement shouldCache() in your card to opt out.
Enum Support:
- Pulse v1.7.1+ supports enums in Pulse::record() and Pulse::set():
```
Pulse::record('status', UserStatus::Active);
```
- Gotcha: Older Laravel versions (<10.30) may throw errors. Use string values as a fallback.
Redis Serialization:
- Pulse uses Redis for real-time updates. Ensure your Redis server supports the latest serialization:
```
// config/database.php
'redis' => [
    'client' => 'phpredis',
    'options' => [
        'serialize' => \Illuminate\Redis\Connections\Connection::SERIALIZER_PHP,
    ],
],
```
- Gotcha: Laravel 13+ changed Redis prefixing. Update Pulse to v1.7.3+.
Slow Query Highlighting:
- Disable syntax highlighting for performance:
```
'queries' => [
    'highlighting' => false,
],
```
- Tip: Use pulse:reload to refresh the dashboard after config changes.

Environment Detection:

Pulse may misidentify environments (e.g., local vs. development). Override detection:

// app/Providers/PulseServiceProvider.php
Pulse::detectEnvironment(function () {
    return app()->environment('staging') ? 'staging' : config('app.env');
});

Memory Leaks:
- Older versions (<1.3.2) had leaks in pulse:work. Upgrade and restart the worker:
```
php artisan pulse:work --stop
php artisan pulse:work
```

Debugging Tips

Check Worker Logs:
```
tail -f storage/logs/pulse.log
```
Enable Debug Mode:
```
// config/pulse.php
'debug' => true,
```
Test Locally with Tunneling:
```
php artisan pulse:tunnel
```
Access via the provided URL (e.g., https://pulse-12345.ngrok.io).
Inspect Raw Data: Use the pulse:export command to dump data for analysis:
```
php artisan pulse:export --format=json > pulse_data.json
```

Extension Points

Custom Ingest Logic: Extend Laravel\Pulse\Ingest to modify or enrich data before storage:

Pulse::extend(function ($ingest) {
    $ingest->listen('request', function ($payload) {
        $payload['custom_field'] = 'value';
        return $payload;
    });
});

Override Default Cards: Replace built-in cards (e.g., RequestsCard) by binding your own:
```
// app/Providers/PulseServiceProvider.php
public function boot() {
    Pulse::
```

Pulse Laravel Package