# The worker

Ranetrace buffers errors, events, logs, page visits, and JavaScript errors in cache, then ships them to the API in batches. Two moving parts make that happen:

1. **`ranetrace:work`**: a scheduled command that reads each buffer and dispatches batch jobs to the queue.
2. **A queue worker**: runs those jobs and posts the batches to the API.

If either piece is missing, buffered data stays put.

## Schedule `ranetrace:work`

Add it to `routes/console.php`:

```php
use Illuminate\Support\Facades\Schedule;

Schedule::command('ranetrace:work')
    ->everyMinute()
    ->withoutOverlapping()
    ->runInBackground();
```

Make sure Laravel's scheduler itself is running, typically a cron entry:

```bash
* * * * * cd /path-to-your-app && php artisan schedule:run >> /dev/null 2>&1
```

### Command options

From the command's signature:

```
ranetrace:work {--type= : Specific type to process (errors, events, logs, page_visits, javascript_errors)}
```

Without `--type`, the command processes every feature in turn.

## Run a queue worker

Batch jobs are dispatched to the queue named by `RANETRACE_BATCH_QUEUE_NAME` (default: `default`). Any standard Laravel queue worker processes them:

```bash
php artisan queue:work --queue=default
```

If you change the queue name:

```dotenv
RANETRACE_BATCH_QUEUE_NAME=ranetrace
```

…match the worker:

```bash
php artisan queue:work --queue=ranetrace
```

## Verify it's working

```bash
php artisan ranetrace:status
```

Status accepts `--json` for machine-readable output. After installing, run the test command to send a synthetic payload through the buffer:

```bash
php artisan ranetrace:test --all
```

Per-feature variants exist:

| Command | Source |
|---|---|
| `ranetrace:test` | `RanetraceTestCommand` |
| `ranetrace:test-errors` | `RanetraceErrorTestCommand` |
| `ranetrace:test-events` | `RanetraceEventTestCommand` |
| `ranetrace:test-logging` | `RanetraceLogTestCommand` |
| `ranetrace:test-analytics` | `RanetraceAnalyticsTestCommand` |
| `ranetrace:test-javascript-errors` | `RanetraceJavaScriptErrorTestCommand` |

## Configuration

From `config/ranetrace.php` under `batch`:

| Env var | Description | Default |
|---|---|---|
| `RANETRACE_BATCH_QUEUE_NAME` | Queue name for batch jobs | `default` |
| `RANETRACE_BATCH_CACHE_DRIVER` | Cache driver for the buffer | `CACHE_STORE`, then `file` |
| `RANETRACE_BATCH_MAX_BUFFER_SIZE` | Max items per feature buffer | `5000` |

The buffer needs a persistent cache driver: the `array` driver won't survive past a single request.

## Pauses

The package can pause a feature (or all features), for example after API errors. Inspect and clear pauses with:

```bash
# Inspect: pauses show up in ranetrace:status output
php artisan ranetrace:status

# Clear the global pause
php artisan ranetrace:pause-clear --global

# Clear a specific feature
php artisan ranetrace:pause-clear --feature=errors
```

Valid `--feature` values, from the command's signature: `errors`, `events`, `logs`, `page_visits`, `javascript_errors`.