Getting Started

Minimal Steps

Install the Daemon Add the package via Composer:

composer require spatie/flare-daemon

Or use the PHAR for standalone execution:

wget https://github.com/spatie/flare-daemon/releases/latest/download/daemon.phar
chmod +x daemon.phar

Start the Daemon Run the daemon locally (default: 127.0.0.1:8787):
```
php vendor/bin/flare-daemon
```
Or via PHAR:
```
./daemon.phar
```
Configure Your Flare Client Update your Laravel/Flare client to use the daemon for async delivery:
```
use Spatie\FlareClient\Flare;

Flare::useDaemon(); // Enables daemon transport
```
Verify Integration Trigger an error or log in your app. Check the daemon logs for buffered payloads:
```
php vendor/bin/flare-daemon --verbose
```

First Use Case: Debugging Production Errors

Scenario: A critical error occurs in production, but you want to avoid blocking the request with Flare’s network call.
Workflow:
1. Start the daemon in your local/dev environment.
2. Configure your Laravel app to use the daemon (e.g., via .env or runtime):
```
Flare::useDaemon('http://127.0.0.1:8787');
```
3. Reproduce the error. The payload is buffered locally and sent asynchronously.
4. Monitor the daemon’s /status endpoint or logs to confirm delivery.

Implementation Patterns

Core Workflow: Async Error/Log Delivery

Client-Side Setup
- Enable the daemon in your AppServiceProvider or config:
```
Flare::useDaemon(); // Uses default local address (127.0.0.1:8787)
```
- For custom addresses (e.g., Docker/Kubernetes):
```
Flare::useDaemon('http://flare-daemon:8787');
```

Daemon Configuration

Set environment variables (e.g., in .env):

FLARE_DAEMON_LISTEN=0.0.0.0:8787  # Bind to all interfaces for Docker
FLARE_DAEMON_BUFFER_BYTES=524288  # Increase buffer size for high-volume apps
FLARE_DAEMON_FLUSH_AFTER_SECONDS=5 # Flush more frequently

Payload Routing
- The daemon automatically routes payloads by:
  - API Key: Isolated buffers per key to avoid quota issues.
  - Entity Type: Errors, traces, and logs are buffered separately.
- Example payload structure:
```
{
  "api_key": "your-key-here",
  "type": "error",
  "payload": { ... }
}
```

Testing Locally

Use the --test flag to bypass upstream delivery (for debugging):
```
php vendor/bin/flare-daemon --test
```

Send a test payload via curl:

curl -X POST http://127.0.0.1:8787/v1/errors \
  -H "Content-Type: application/json" \
  -d '{"api_key":"test","payload":{"message":"Test error"}}'

Health Checks
- Expose daemon health via /health (returns 200 if running).
- Monitor buffer status via /status (returns buffered payload counts).

Advanced Patterns

1. Docker/Kubernetes Deployment

Sidecar Pattern: Run the daemon as a sidecar container:

# docker-compose.yml
services:
  app:
    build: .
  flare-daemon:
    image: ghcr.io/spatie/flare-daemon
    ports:
      - "8787:8787"
    environment:
      - FLARE_DAEMON_LISTEN=0.0.0.0:8787

Configure your app to target the sidecar:

Flare::useDaemon('http://flare-daemon:8787');

2. Graceful Shutdown

The daemon handles SIGINT/SIGTERM to drain buffers before exiting.
For long-running processes (e.g., CLI jobs), ensure the daemon is running in the same process group or use a process manager (e.g., Supervisor).

3. Quota Management

The daemon tracks 429 (Too Many Requests) and 403 (Forbidden) responses.
Automatically pauses ingestion for problematic API keys/types to avoid throttling.
Monitor via logs or extend the /status endpoint.

4. Custom Buffer Logic

Override buffer thresholds or flush intervals by extending the daemon’s config:

// In a service provider
$daemonConfig = [
  'buffer_bytes' => 1048576, // 1MB
  'flush_after_seconds' => 30,
];
// Pass config to the daemon (if supported in future versions)

5. Logging and Observability

Use --verbose for debugging:
```
php vendor/bin/flare-daemon --verbose
```

Integrate with Laravel’s logging:

Flare::useDaemon()->setLogger(app('log')->channel('flare'));

Gotchas and Tips

Pitfalls

Buffer Overflows
- Issue: Large payloads (e.g., big traces) may exceed FLARE_DAEMON_BUFFER_BYTES.
- Fix: Increase the buffer size or reduce payload size (e.g., truncate traces).
- Debug: Check daemon logs for BufferExceeded warnings.
Network Timeouts
- Issue: Slow upstream responses (FLARE_DAEMON_UPSTREAM_TIMEOUT_SECONDS) may block the daemon.
- Fix: Increase the timeout or monitor upstream health separately.
API Key Leaks
- Issue: Hardcoding API keys in client config or logs.
- Fix: Use environment variables or Laravel’s env() helper:
```
Flare::useDaemon()->setApiKey(env('FLARE_API_KEY'));
```
Daemon Not Running
- Issue: Payloads fail silently if the daemon is down.
- Fix: Enable fallback to direct delivery in the Flare client:
```
Flare::useDaemon()->fallbackToDirectDelivery();
```
Composer Lock Watcher
- Issue: The daemon stops on composer.lock changes (default behavior).
- Fix: Disable with FLARE_COMPOSER_LOCK="" if not needed.

Debugging Tips

Check Buffer Status

Query /status to see pending payloads:
```
curl http://127.0.0.1:8787/status
```

Expected response:

{
  "buffers": {
    "api_key_123": {
      "errors": 5,
      "traces": 0,
      "logs": 2
    }
  }
}

Enable Verbose Logging

Run with --verbose to see real-time payload processing:
```
php vendor/bin/flare-daemon --verbose
```

Look for lines like:

[DEBUG] Buffered error for api_key_123 (size: 1.2KB)
[DEBUG] Flushed 3 errors to Flare

Test Payloads Directly

Use the tests/test.sh script to simulate payloads:
```
bash tests/test.sh YOUR_API_KEY
```

For custom testing, send payloads via curl:

curl -X POST http://127.0.0.1:8787/v1/errors \
  -H "Content-Type: application/json" \
  -d '{"api_key":"test","payload":{"message":"Debug test"}}'

Inspect Upstream Failures
- Check for 429/403 responses in logs. The daemon auto-pauses ingestion for affected keys.
- Manually retry paused keys by restarting the daemon or clearing buffers (not yet supported; may require custom logic).

Extension Points

Custom Endpoints
- The daemon’s HTTP server is built on ReactPHP. Extend by:
  - Adding middleware to validate payloads.
  - Example (hypothetical):
```
//
```

Flare Daemon Laravel Package