📖 WatchdogAI Help

1. Install

composer require watchdog-ai/laravel
php artisan migrate
# Optional: publish config so you can edit it locally
php artisan vendor:publish --tag=watchdog-ai-config

The package auto-loads its routes, migrations, and views via Laravel's package discovery — no config/app.php edits required.

2. Configure providers

Visit https://watchdog.sicl.ai/watchdog/settings and configure at least one provider:

• Groq — fast and cheap, great for log analysis. Get a key at console.groq.com.
• Anthropic (Claude) — best for code-fix quality. Create a key.
• xAI (Grok), OpenAI, Ollama (local) — also supported.

Keys are encrypted at rest using your application's APP_KEY. Backups never contain plaintext.

3. Log events from your code

Use the Watchdog facade anywhere in your app — controllers, services, jobs, middleware:

use WatchdogAI\Laravel\Facades\Watchdog;

Watchdog::error('PaymentService', 'charge_failed', $msg, $exception, [
    'order_id' => $order->id,
]);

Watchdog::warning('OrderQueue', 'slow_job', "Job took {$ms}ms", ['job_id' => $jobId]);

Watchdog::info('Auth', 'login', "User {$user->id} signed in");

The package automatically captures the calling file and line number — no need to pass __FILE__ manually. Identical events within a 10-second window are deduped to avoid runaway logging.

Watchlist (which sources/levels actually persist)

By default, only the levels enabled on the baseline (*) row are recorded. To capture less or more, open the Watch list from the Events page. Adding any non-* service activates strict mode — only listed services are logged.

4. Run the AI Monitor

The watchdog-ai:monitor command pulls the last N minutes of events, sends them to the configured LLM, and stores the analysis. Schedule it in app/Console/Kernel.php:

$schedule->command('watchdog-ai:monitor')->everyTenMinutes();

Or run on demand:

php artisan watchdog-ai:monitor                  # default 10-min window
php artisan watchdog-ai:monitor --minutes=60     # last hour
php artisan watchdog-ai:monitor --dry-run        # preview without LLM call
php artisan watchdog-ai:monitor --provider=anthropic   # one-off override

5. Suggest Fix workflow

1. Open AI Monitor.
2. Click X finding(s) on any analysis with results.
3. Click Suggest Fix on a finding that has a file path.
4. The package reads ±50 lines around the offending line, sends to the configured code_fix provider, and renders the returned diff inline.
5. Copy the diff with the Copy diff button and apply via git apply or paste into your editor.

Path safety: the resolver only reads files under app/, config/, routes/, database/ by default. Tweak in config/watchdog-ai.php → code_fix.allowed_paths. Any path containing .. is rejected outright; .env/.key/.pem extensions are blocked.

6. Tuning and limits

• Per-provider daily/monthly token limits — set in Settings. When hit, calls return null with a clear "limit reached" error instead of silently overspending.
• Different providers for different tasks — set WATCHDOG_AI_LOG_PROVIDER=groq (cheap analysis) and WATCHDOG_AI_FIX_PROVIDER=anthropic (high-quality fixes) in .env.
• Custom Laravel log path — if your app uses a non-default log location, set WATCHDOG_AI_LARAVEL_LOG_PATH=/path/to/laravel.log. Set to empty string to disable Laravel-log scanning entirely.
• Event retention — WATCHDOG_AI_EVENT_RETENTION_DAYS=30 (default). Set to 0 to keep forever.

7. Emergency disable

One env line takes the package offline without uninstalling. Watchdog facade calls become no-ops, the cron exits 0 immediately, and the Suggest Fix endpoint returns 503:

WATCHDOG_AI_ENABLED=false
php artisan config:cache

Re-enable by removing the line (or setting it to true) and re-running config:cache.