Getting Started

Minimal Steps to First Use

Install the package via Composer (automatically included with spatie/laravel-flare):
```
composer require spatie/laravel-flare
```
The daemon is installed as a vendor binary (vendor/bin/flare-daemon).
Start the daemon locally (default: 127.0.0.1:8787):
```
php vendor/bin/flare-daemon
```
For debugging, add --verbose:
```
php vendor/bin/flare-daemon --verbose
```

Enable daemon transport in your Laravel app: Add this to your config/flare.php:

'transport' => [
    'daemon' => [
        'enabled' => true,
        'url' => 'http://127.0.0.1:8787',
    ],
],

Verify it works: Trigger an error in your app (e.g., throw new Exception('Test')). Check your Flare dashboard to confirm the error appears asynchronously.

First Use Case: Debugging a Production Issue

Start the daemon in verbose mode:

php vendor/bin/flare-daemon --verbose &

Reproduce the issue in staging/production. The daemon will buffer and forward errors/logs to Flare without blocking your request.

Monitor the daemon logs to track payloads in real-time:

tail -f /var/log/flare-daemon.log  # If using systemd/logging

Check Flare’s dashboard for the async-delivered payloads.

Key Files to Know

Daemon binary: vendor/bin/flare-daemon (or src/daemon.php for development).
Config: Environment variables (e.g., FLARE_DAEMON_LISTEN) or config/flare.php.
Health checks: /health (returns 200 if the daemon is running).
Status endpoint: /status (shows buffered payloads and flush stats).

Implementation Patterns

Workflow: Local Development

Start the daemon in the background:

php vendor/bin/flare-daemon --verbose &

Configure Laravel to use the daemon (as above).
Test locally:
- Use tests/test.sh to simulate error payloads:
```
bash tests/test.sh YOUR_API_KEY
```
- Check /status to monitor buffer drain:
```
curl http://127.0.0.1:8787/status
```

Workflow: Production Deployment

Option 1: Docker (Recommended for Containers)

Run the daemon as a sidecar:

docker run -d --name flare-daemon -p 8787:8787 ghcr.io/spatie/flare-daemon

Configure Laravel to point to the Docker host’s IP (or host.docker.internal for Mac/Windows).

Set resource limits (optional):

docker run -d --name flare-daemon -p 8787:8787 -e PHP_MEMORY_LIMIT=256M ghcr.io/spatie/flare-daemon

Option 2: Kubernetes (Helm)

Install the Helm chart:

helm install flare-daemon oci://ghcr.io/spatie/charts/flare-daemon --namespace monitoring --create-namespace

Configure Laravel to use the Kubernetes service:

'url' => 'http://flare-daemon.monitoring.svc.cluster.local:8787',

Enable composer.lock watcher (auto-shutdown on deployments):

helm upgrade flare-daemon oci://ghcr.io/spatie/charts/flare-daemon --set composerLockPath=/app/composer.lock

Option 3: Systemd (Bare Metal)

Create a service file (/etc/systemd/system/flare-daemon.service):

[Unit]
Description=Flare Daemon
After=network.target

[Service]
ExecStart=/usr/bin/php /var/www/vendor/bin/flare-daemon
User=www-data
Restart=always
Environment=FLARE_DAEMON_LISTEN=127.0.0.1:8787
Environment=PHP_MEMORY_LIMIT=256M

[Install]
WantedBy=multi-user.target

Start and enable:

sudo systemctl daemon-reload
sudo systemctl start flare-daemon
sudo systemctl enable flare-daemon

Integration Tips

Health Checks: Add a /health endpoint check to your monitoring (e.g., Prometheus, Datadog):
```
curl -I http://127.0.0.1:8787/health  # Should return 200
```

Buffer Monitoring: Use /status to monitor buffer size and flush rates:

curl http://127.0.0.1:8787/status

Example output:

{
  "buffers": {
    "api_key_123": {
      "errors": {"count": 5, "bytes": 1200},
      "logs": {"count": 20, "bytes": 4000}
    }
  },
  "last_flush": "2023-01-01T12:00:00Z"
}

Load Testing: Simulate high traffic with k6:
```
php vendor/bin/flare-daemon --test &
k6 run loadtest/loadtest.js
```
Target p95 latency < 10ms for production workloads.
Fallback Behavior: The Flare client automatically falls back to direct delivery if the daemon is unreachable. No code changes needed.

Custom Configuration: Override defaults via environment variables (e.g., in .env):

FLARE_DAEMON_LISTEN=0.0.0.0:8787  # Bind to all interfaces
FLARE_DAEMON_BUFFER_BYTES=524288  # 512 KB buffer
FLARE_DAEMON_FLUSH_AFTER_SECONDS=5  # Flush every 5 seconds

Gotchas and Tips

Pitfalls

Buffer Overflows:
- The daemon uses in-memory buffers (no persistence). If your app crashes or the daemon restarts, buffered payloads are lost.
- Mitigation: Monitor /status and adjust FLARE_DAEMON_BUFFER_BYTES (default: 256 KB) based on your traffic. For high-volume apps, increase to 1–2 MB.
Upstream Rate Limits:
- Flare’s ingress may return 429 (Too Many Requests) if the daemon flushes too aggressively.
- Mitigation: The daemon auto-pauses ingestion for 30 seconds on 429 responses. Monitor logs for 429 errors and adjust FLARE_DAEMON_FLUSH_AFTER_SECONDS (default: 10s).
Network Latency:
- If the daemon is on a separate machine (e.g., Kubernetes), add a timeout to avoid blocking:
```
'transport' => [
    'daemon' => [
        'timeout' => 2.0, // 2 seconds
    ],
],
```
Composer Lock Watcher:
- The daemon auto-shuts down if composer.lock changes (useful for deployments).
- Gotcha: This requires FLARE_COMPOSER_LOCK to point to the correct path (e.g., /app/composer.lock in Docker).
- Debugging: If the daemon crashes unexpectedly, check if composer.lock is being modified during runtime.
PHAR vs. Source:
- The Composer binary uses a bundled PHAR (build/daemon.phar). If you modify src/daemon.php, rebuild the PHAR:
```
bash build.sh
```

Debugging Tips

Verbose Logging: Start the daemon with --verbose to log every payload:

php vendor/bin/flare-daemon --verbose

Look for lines like:

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

Flare Daemon Laravel Package