README

ErrorWatch Laravel SDK

Self-hosted error monitoring & APM for Laravel applications

Installation • Quick Start • Features • Configuration • Documentation

⚠️ Beta Notice: This SDK is currently in beta (v0.1.x). The API is stable but may receive minor improvements before v1.0.0. We recommend testing in staging environments first.

Why ErrorWatch?

Self-hosted error monitoring that doesn't cost a fortune. Unlike Sentry's per-event pricing, ErrorWatch runs on your infrastructure with predictable costs.

🔒 Full Data Ownership - All error data stays on your servers
💰 Predictable Costs - No per-event pricing surprises
⚡ Zero Vendor Lock-in - Standard SQL database, easy to export
🎯 Laravel Native - Built specifically for Laravel, by Laravel developers

Features

Error Monitoring

✅ Automatic Exception Capture - Unhandled exceptions are caught automatically
✅ Stack Trace Parsing - Clean, readable stack traces with context
✅ Error Grouping - Smart fingerprinting groups similar errors
✅ Breadcrumbs - 360° context for every error (HTTP, DB, Auth, Queue, Console)

Performance Monitoring (APM)

✅ Request Tracing - End-to-end transaction tracking
✅ Eloquent Query Spans - See every database query with duration
✅ N+1 Detection - Automatic alerts for repeated queries
✅ Slow Query Alerts - Configurable threshold for query performance
✅ HTTP Client Tracing - Track outgoing API calls

Laravel Integration

✅ Queue Job Monitoring - Failed jobs captured with full context
✅ Auth Integration - Automatic user context from authenticated requests
✅ Console Commands - Track Artisan command execution and failures
✅ Monolog Handler - Forward logs to ErrorWatch in real-time
✅ Session Replay - Replay user sessions to understand errors

Developer Experience

✅ Auto-Discovery - Zero-configuration service provider
✅ Artisan Commands - errorwatch:install and errorwatch:test
✅ Blade Directive - @errorwatchReplay() for session recording
✅ Facade - Clean ErrorWatch::captureException() syntax
✅ Full TypeScript Support - For your frontend integration

Requirements

Requirement	Version
PHP	^8.1
Laravel	10.x, 11.x, 12.x
Guzzle	^7.0

Installation

Install via Composer:

composer require errorwatch/sdk-laravel:@beta

Publish the configuration file:

php artisan vendor:publish --tag=errorwatch-config

Add your ErrorWatch credentials to .env:

ERRORWATCH_ENABLED=true
ERRORWATCH_ENDPOINT=https://api.errorwatch.io
ERRORWATCH_API_KEY=your-api-key-here

Test the installation:

php artisan errorwatch:test

That's it! Your Laravel application is now monitoring errors.

Quick Start

Automatic Error Capture

Errors are captured automatically via middleware. No code changes needed!

// This exception will be automatically captured and sent to ErrorWatch
throw new RuntimeException('Something went wrong');

Manual Exception Capture

use ErrorWatch\Laravel\Facades\ErrorWatch;

try {
    // Risky operation
    ProcessPayment::dispatch($order);
} catch (PaymentFailedException $e) {
    // Capture with additional context
    ErrorWatch::captureException($e, [
        'extra' => [
            'order_id' => $order->id,
            'amount' => $order->total,
        ],
        'tags' => [
            'payment_provider' => 'stripe',
        ],
    ]);

    throw $e;
}

Add Context with Breadcrumbs

use ErrorWatch\Laravel\Facades\ErrorWatch;

// Track user actions
ErrorWatch::addBreadcrumb('User initiated checkout', 'user', [
    'cart_items' => 3,
    'cart_total' => 149.99,
]);

// When an error occurs later, you'll see the full context!

Set User Context

// In your authentication listener or middleware
ErrorWatch::setUser([
    'id' => auth()->id(),
    'email' => auth()->user()->email,
    'username' => auth()->user()->name,
]);

// Now every error includes who experienced it

APM Transactions

use ErrorWatch\Laravel\Facades\ErrorWatch;

// Track custom operations
$transaction = ErrorWatch::startTransaction('process-payout');
$transaction->setTag('payout.method', 'bank_transfer');

$span = $transaction->startChild('api-call', 'http.client');
// ... make external API call
$span->finish();

ErrorWatch::finishTransaction();

Configuration

All configuration options in config/errorwatch.php:

return [
    // Core
    'enabled' => env('ERRORWATCH_ENABLED', true),
    'endpoint' => env('ERRORWATCH_ENDPOINT'),
    'api_key' => env('ERRORWATCH_API_KEY'),
    'environment' => env('APP_ENV', 'production'),
    'release' => env('APP_VERSION'),

    // Session Replay
    'replay' => [
        'enabled' => env('ERRORWATCH_REPLAY_ENABLED', false),
        'sample_rate' => env('ERRORWATCH_REPLAY_SAMPLE_RATE', 0.1),
    ],

    // Breadcrumbs
    'breadcrumbs' => [
        'enabled' => true,
        'max_count' => 100,  // Keep last 100 breadcrumbs
    ],

    // User Context
    'user_context' => [
        'enabled' => true,
        'capture_ip' => true,
    ],

    // Queue Monitoring
    'queue' => [
        'enabled' => true,
        'capture_retries' => false,  // Only capture final failures
    ],

    // APM
    'apm' => [
        'enabled' => true,
        'eloquent' => [
            'enabled' => true,
            'log_queries' => true,
        ],
        'http_client' => [
            'enabled' => true,
        ],
        'n_plus_one_threshold' => 5,      // Alert after 5 identical queries
        'slow_query_threshold_ms' => 500,  // Alert queries > 500ms
        'excluded_routes' => ['telescope/*', 'horizon/*'],
    ],

    // Logging
    'monolog' => [
        'enabled' => true,
        'level' => 'warning',  // warning, error, critical, alert, emergency
    ],
];

Session Replay

Enable session replay to see exactly what users did before an error:

ERRORWATCH_REPLAY_ENABLED=true
ERRORWATCH_REPLAY_SAMPLE_RATE=0.1  # 10% of sessions

Add to your layout Blade file:

<!DOCTYPE html>
<html>
<head>
    <title>{{ config('app.name') }}</title>
    @errorwatchReplay()
</head>
<body>
    @yield('content')
</body>
</html>

Artisan Commands

Install Command

php artisan errorwatch:install

# Output:
# ✓ Configuration file published to config/errorwatch.php
#
# Next steps:
# 1. Add ERRORWATCH_ENDPOINT and ERRORWATCH_API_KEY to your .env
# 2. Run php artisan errorwatch:test to verify

Test Command

# Send a test message
php artisan errorwatch:test

# Send a test exception
php artisan errorwatch:test --exception

# Custom message
php artisan errorwatch:test --message="Testing from production"

Automatic Integrations

The SDK automatically integrates with these Laravel features:

Integration	What it captures
HTTP Middleware	Request/response timing, exceptions
Eloquent ORM	SQL queries, duration, N+1 patterns
Queue Workers	Job failures, retries, duration
Auth	User context on login/logout
HTTP Client	Outgoing API calls with timing
Console	Command execution, exit codes
Monolog	Log entries above threshold

Self-Hosting ErrorWatch

ErrorWatch is self-hosted. Deploy your own instance:

# Using Docker Compose
git clone https://github.com/MakFly/errorwatch
cd errorwatch
docker-compose up -d

See the self-hosting documentation for detailed setup instructions.

Documentation

Comparison with Sentry

Feature	ErrorWatch	Sentry
Self-hosted	✅	⚠️ (Enterprise only)
Pricing	Free (self-hosted)	Per-event
Data ownership	100% yours	Stored by Sentry
Laravel native	✅	⚠️ (Generic SDK)
N+1 detection	✅	❌
Session replay	✅	💰 Paid add-on

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

# Run tests
composer test

# Run static analysis
composer stan

Security

If you discover a security vulnerability, please email security@errorwatch.io. All security vulnerabilities will be promptly addressed.

License

The MIT License (MIT). See LICENSE for more information.

Support

📧 Email: support@errorwatch.io
💬 Discord: Join our community
🐛 Issues: GitHub Issues
📖 Docs: docs.errorwatch.io

Made with ❤️ by the ErrorWatch Team

errorwatch / sdk-laravel

Maintainers

Details