README

Real-time error monitoring, slow query detection, and AI-powered debugging for Laravel applications. Reports issues directly to your Clawdbot instance for automatic analysis, issue creation, and PR generation.

Installation

composer require clawdbot/laravel-monitor

Configuration

Publish the config:

php artisan vendor:publish --tag=clawdbot-monitor-config

Add to your .env:

CLAWDBOT_PROJECT_ID=my-project
CLAWDBOT_WEBHOOK_URL=https://your-clawdbot-gateway/api/monitor
CLAWDBOT_WEBHOOK_SECRET=your-secret-key

# Optional tuning
CLAWDBOT_REPORT_EXCEPTIONS=true
CLAWDBOT_REPORT_SLOW_QUERIES=true
CLAWDBOT_SLOW_QUERY_THRESHOLD=500
CLAWDBOT_REPORT_FAILED_JOBS=true
CLAWDBOT_QUEUE_REPORTS=true

Features

Exception Reporting

Automatically catches and reports all unhandled exceptions with full context:

• Stack trace
• Request data (URL, method, input, headers)
• User context (ID, email, name)
• Environment info

// Exceptions are reported automatically. To report manually:
use Clawdbot\Monitor\Facades\ClawdbotMonitor;

ClawdbotMonitor::reportException($exception, [
    'custom_context' => 'value',
]);

Slow Query Detection

Monitors all database queries and reports those exceeding the threshold:

CLAWDBOT_SLOW_QUERY_THRESHOLD=500  # milliseconds

Reports include:

• SQL query with bindings
• Execution time
• Source file/line (where the query originated)
• Connection name

Failed Job Reporting

Automatically reports failed queue jobs:

• Job class and payload
• Exception details
• Queue/connection info

User Complaint API

Built-in API endpoint for users or support to report issues:

POST /api/clawdbot/complaint
Authorization: Bearer {token}

{
    "description": "My balance doesn't update after payment",
    "category": "payment",
    "steps": "1. Made a payment via Stripe\n2. Checked balance page\n3. Balance still shows old amount",
    "expected": "Balance should reflect the payment",
    "actual": "Balance unchanged after 10 minutes"
}

Debug API (Optional)

Allow Clawdbot to remotely debug issues:

CLAWDBOT_ALLOW_DEBUG_QUERIES=true     # Enable read-only SQL queries
CLAWDBOT_ALLOW_IMPERSONATION=true     # Enable user context lookup

Available endpoints (HMAC-signed):

• POST /api/clawdbot/debug/query - Execute read-only SELECT queries
• POST /api/clawdbot/debug/user-context - Get user info + relationships
• POST /api/clawdbot/debug/logs - Read application logs

Custom Events

Report custom events from anywhere in your app:

use Clawdbot\Monitor\Facades\ClawdbotMonitor;

// Payment webhook failed
ClawdbotMonitor::reportEvent('webhook.failed', [
    'provider' => 'stripe',
    'event_type' => 'payment_intent.succeeded',
    'error' => 'Timeout connecting to database',
]);

// Unusual activity
ClawdbotMonitor::reportEvent('security.unusual_login', [
    'user_id' => 123,
    'ip' => '1.2.3.4',
    'country' => 'XX',
]);

Testing

Verify your setup works:

php artisan clawdbot:test
php artisan clawdbot:test --type=slow_query
php artisan clawdbot:test --type=failed_job
php artisan clawdbot:test --type=event

Security

• All debug endpoints are protected by HMAC signature verification
• Only SELECT queries allowed through the debug API
• Sensitive data (passwords, tokens, API keys) automatically redacted
• IP allowlisting supported for debug endpoints
• Request input sanitized and truncated

Webhook Payload Format

All reports follow this structure:

{
    "type": "exception|slow_queries|failed_job|complaint|custom_event|health",
    "project_id": "my-project",
    "environment": "production",
    "server": {
        "hostname": "web-01",
        "ip": "10.0.0.1",
        "php_version": "8.3.0",
        "laravel_version": "11.0.0"
    },
    "timestamp": "2026-01-28T12:00:00.000Z",
    "data": { ... }
}

License

MIT