README

Enterprise-grade real-time error monitoring and alerting system for Laravel applications via Discord webhooks.

20250727_1034_Logo Laravel Watchdog_simple_compose_01k15kpqzmfd8bjwgsrdd36nvw

Overview

Watchdog Discord is a high-performance monitoring solution that provides intelligent error tracking, analytics, and instant Discord notifications for Laravel applications. Built with enterprise scalability in mind, it offers Redis-powered error deduplication, severity scoring, and asynchronous processing to ensure zero impact on application performance.

Key Features

🚀 High Performance: Redis-powered error tracking with sub-millisecond performance
🔄 Asynchronous Processing: Queue-based notifications to prevent application slowdown
🎯 Smart Deduplication: Hash-based error grouping and frequency analysis
📊 Error Analytics: Severity scoring, trend detection, and analytics dashboard
🛡️ Rate Limiting: Configurable thresholds to prevent notification spam
🌍 Multi-language Support: Built-in translations for 9 languages
🐳 Docker Ready: Full containerization support for modern deployments

Architecture

Application Layer
├── Exception Handler    ├── Middleware    ├── Facade    ├── Manual Logging
│
Service Layer  
├── Discord Notifier (Central orchestration and payload building)
│
Business Logic Layer
├── Error Tracking Service    ├── Rate Limiter    ├── Queue Manager
│
Data Access Layer
├── Redis Cache    ├── Database (MySQL)    ├── Discord API

The system implements a layered architecture with Redis-first caching, database persistence, and configurable async processing for optimal performance in production environments.

Installation

composer require vinkius-labs/watchdog-discord

Publish Configuration

php artisan vendor:publish --provider="VinkiusLabs\WatchdogDiscord\WatchdogDiscordServiceProvider" --tag="watchdog-discord-config"

Run Migrations

php artisan migrate

Basic Configuration

Environment Setup

# Required
WATCHDOG_DISCORD_ENABLED=true
WATCHDOG_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your/webhook/url

# Performance (Production)
WATCHDOG_DISCORD_ASYNC_ENABLED=true
WATCHDOG_DISCORD_QUEUE_CONNECTION=redis
WATCHDOG_DISCORD_CACHE_PREFIX=watchdog_prod

# Error Tracking
WATCHDOG_DISCORD_ERROR_TRACKING_ENABLED=true
WATCHDOG_DISCORD_MIN_SEVERITY=7
WATCHDOG_DISCORD_FREQUENCY_THRESHOLD=10

# Rate Limiting
WATCHDOG_DISCORD_RATE_LIMIT_ENABLED=true
WATCHDOG_DISCORD_RATE_LIMIT_MAX=20
WATCHDOG_DISCORD_RATE_LIMIT_WINDOW=5

Discord Webhook Setup

Navigate to your Discord server settings
Go to Integrations → Webhooks
Create a new webhook and copy the URL
Add the URL to your .env file

Usage

Automatic Error Handling

The package automatically captures and reports Laravel exceptions through the exception handler integration.

Manual Logging

use VinkiusLabs\WatchdogDiscord\Facades\WatchdogDiscord;

// Log exceptions with context
try {
    $result = $riskyOperation->execute();
} catch (\Exception $e) {
    WatchdogDiscord::send($e, 'error', [
        'operation' => 'payment_processing',
        'user_id' => auth()->id()
    ]);
    throw $e;
}

// Log custom messages
WatchdogDiscord::sendLog('warning', 'High memory usage detected', [
    'memory_usage' => memory_get_usage(true),
    'peak_memory' => memory_get_peak_usage(true)
]);

Log Levels Support

The package supports all PSR-3 log levels with intelligent severity scoring:

// Emergency level (severity: 10)
WatchdogDiscord::emergency('Database server down');

// Alert level (severity: 9)  
WatchdogDiscord::alert('Payment gateway unreachable');

// Critical level (severity: 8)
WatchdogDiscord::critical('Application crashed');

// Error level (severity: 6)
WatchdogDiscord::error('User authentication failed');

// Warning level (severity: 4)
WatchdogDiscord::warning('High memory usage');

// Notice level (severity: 2)
WatchdogDiscord::notice('New admin user created');

// Info level (severity: 1) 
WatchdogDiscord::info('Backup completed successfully');

// Debug level (severity: 1)
WatchdogDiscord::debug('Cache warming started');

Configuration: Control which log levels are sent to Discord:

# Production (critical issues only)
WATCHDOG_DISCORD_LOG_LEVELS=emergency,alert,critical,error
WATCHDOG_DISCORD_MIN_SEVERITY=7

# Development (all levels)
WATCHDOG_DISCORD_LOG_LEVELS=emergency,alert,critical,error,warning,notice,info,debug  
WATCHDOG_DISCORD_MIN_SEVERITY=1

Middleware Integration

// Apply to specific routes
Route::middleware('watchdog-discord:error')->group(function () {
    Route::post('/api/payments', [PaymentController::class, 'process']);
});

// Global middleware (app/Http/Kernel.php)
protected $middleware = [
    \VinkiusLabs\WatchdogDiscord\Middleware\WatchdogDiscordMiddleware::class,
];

Dependency Injection

use VinkiusLabs\WatchdogDiscord\DiscordNotifier;

class PaymentService
{
    public function __construct(
        private DiscordNotifier $notifier
    ) {}
    
    public function processPayment($data)
    {
        try {
            return $this->gateway->charge($data);
        } catch (\Exception $e) {
            $this->notifier->send($e, 'critical', [
                'payment_data' => $data,
                'gateway' => $this->gateway->getName()
            ]);
            throw $e;
        }
    }
}

Performance Optimization

Redis Configuration

For optimal performance, configure Redis connection:

// config/database.php
'redis' => [
    'default' => [
        'host' => env('REDIS_HOST', '127.0.0.1'),
        'port' => env('REDIS_PORT', '6379'),
        'database' => env('REDIS_DB', '0'),
    ],
],

Queue Workers

Configure dedicated queue workers for notifications:

# Supervisor configuration
php artisan queue:work redis --queue=watchdog_notifications --sleep=3 --tries=3

Production Settings

# Optimal production configuration
WATCHDOG_DISCORD_ASYNC_ENABLED=true
WATCHDOG_DISCORD_QUEUE_CONNECTION=redis
WATCHDOG_DISCORD_CACHE_TTL=300
WATCHDOG_DISCORD_ERROR_TRACKING_ENABLED=true
WATCHDOG_DISCORD_RATE_LIMIT_ENABLED=true

Testing

# Test Discord notifications
php artisan watchdog-discord:test --exception

# Test with custom message
php artisan watchdog-discord:test --level=error --message="Test notification"

# Run test suite
composer test

# Code analysis
composer analyse

Documentation

Installation Guide - Detailed installation and setup
Configuration Reference - Complete configuration options
Architecture Guide - Technical architecture details
Performance Guide - Production optimization
Examples - Usage examples and patterns
Troubleshooting - Common issues and solutions

Requirements

PHP: 8.1, 8.2, or 8.3
Laravel: 9.x, 10.x, 11.x, or 12.x
Redis: 6.0+ (recommended for production)
MySQL: 5.7+ or 8.0+

Security

If you discover a security vulnerability, please send an email to VinkiusLabs at labs@vinkius.com. All security vulnerabilities will be promptly addressed.

License

The MIT License (MIT). Please see License File for more information.

Credits

Vinkius Labs - Package development and maintenance
Contributors - Community contributions

Built with ❤️ by Vinkius Labs

vinkius-labs / watchdog-discord

Maintainers

Details