README

🦅 Simorgh Logger for Laravel

🦅 Simorgh Logger - A powerful and feature-rich logging package for Laravel applications with dashboard, alerts, and intelligent categorization. Named after the legendary Persian bird that watches over and protects all under its wings.

"Just as the mythical Simorgh watches over all birds under its wings, this package watches over and protects all your application logs."

✨ Features

🎯 Smart Categorization - Organize logs by modules (auth, api, payments, etc.)
📊 Visual Dashboard - Beautiful web interface with real-time updates
🚨 Automated Alerts - Email, Slack, Telegram notifications with intelligent triggers
🔍 Advanced Filtering - Search and filter logs with powerful query builder
📈 Analytics & Stats - Comprehensive statistics and performance metrics
🔒 Security - Automatic sanitization of sensitive data
📁 Multiple Storage - Database, File, Sentry, Elasticsearch support
🎨 Export Options - JSON, CSV, XML export capabilities
⚡ Performance - Queue support and optimized queries
🧹 Auto Cleanup - Configurable retention policies

🎮 Try Live Demo

Want to see Simorgh Logger in action before installing? Try our demo!

Quick Demo (One Command)

git clone https://github.com/falahatiali/laravel-advance-log-monitoring.git
cd laravel-advance-log-monitoring
chmod +x demo.sh && ./demo.sh

Then visit: http://localhost:8000/logs

Docker Demo (No PHP Required)

git clone https://github.com/falahatiali/laravel-advance-log-monitoring.git
cd laravel-advance-log-monitoring
docker-compose up -d

Visit: http://localhost:8080/logs

📖 Full demo guide: DEMO.md

📦 Installation

Composer

composer require falahatiali/simorgh-logger

Laravel Auto-Discovery

The package will automatically register itself. If auto-discovery is disabled, add the service provider to your config/app.php:

'providers' => [
    // ...
    Simorgh\Logger\SimorghLoggerServiceProvider::class,
],

Publish Configuration

php artisan vendor:publish --provider="Simorgh\Logger\SimorghLoggerServiceProvider" --tag="simorgh-logger-config"

Publish Migrations

php artisan vendor:publish --provider="Simorgh\Logger\SimorghLoggerServiceProvider" --tag="simorgh-logger-migrations"

Run Migrations

php artisan migrate

🚀 Quick Start

Basic Usage

use Simorgh\Logger\Facades\Simorgh;

// Simple logging
Simorgh::info('Application started successfully');

// With context
Simorgh::error('Payment failed', [
    'user_id' => 123,
    'amount' => 99.99,
    'payment_method' => 'credit_card'
]);

// Categorized logging
Simorgh::category('auth')
    ->warning('Failed login attempt', [
        'email' => 'user@example.com',
        'ip' => request()->ip()
    ]);

Advanced Usage

// Chainable methods
Simorgh::category('api')
    ->user(auth()->id())
    ->context(['request_id' => Str::uuid()])
    ->error('API rate limit exceeded', [
        'endpoint' => '/api/users',
        'limit' => 100,
        'current' => 150
    ]);

// Performance logging
Simorgh::performance('Database query', 0.250, [
    'query' => 'SELECT * FROM users WHERE...',
    'rows' => 1500
]);

// Security events
Simorgh::security('Suspicious activity detected', [
    'type' => 'multiple_failed_logins',
    'ip' => request()->ip(),
    'user_agent' => request()->userAgent()
]);

// Exception logging
try {
    // Some risky operation
} catch (\Exception $e) {
    Simorgh::exception($e, [
        'context' => 'Payment processing',
        'user_id' => auth()->id()
    ]);
}

📊 Dashboard

Access the dashboard at /simorgh-logger (or your configured prefix).

Features:

Real-time log monitoring
Advanced filtering and search
Log statistics and charts
Alert management
Export functionality
Settings configuration

Dashboard Routes:

/simorgh-logger - Main dashboard
/simorgh-logger/logs - Log browser
/simorgh-logger/stats - Statistics
/simorgh-logger/alerts - Alert management
/simorgh-logger/settings - Configuration

📸 Dashboard Screenshots

Main Dashboard

Real-time overview with statistics, log distribution charts, and recent log entries

All Logs Browser

Advanced filtering, search capabilities, and export options (JSON, CSV, XML)

Statistics & Analytics

Comprehensive insights with date range filters, distribution charts, and trend analysis

Alert Configuration

Configure alert channels (Email, Slack, Telegram) and threshold settings

🚨 Alerts Configuration

Email Alerts

// config/simorgh-logger.php
'alerts' => [
    'enabled' => true,
    'channels' => [
        'email' => [
            'enabled' => true,
            'to' => 'admin@example.com',
            'subject_prefix' => '[Simorgh Alert]',
        ],
    ],
    'thresholds' => [
        'critical' => [
            'count' => 5,
            'time_window' => '1 hour',
        ],
    ],
],

Slack Alerts

'alerts' => [
    'channels' => [
        'slack' => [
            'enabled' => true,
            'webhook' => 'https://hooks.slack.com/services/...',
            'channel' => '#alerts',
        ],
    ],
],

Telegram Alerts

'alerts' => [
    'channels' => [
        'telegram' => [
            'enabled' => true,
            'bot_token' => '123456789:ABCdefGHIjklMNOpqrsTUVwxyz',
            'chat_id' => '-123456789',
        ],
    ],
],

🔧 Configuration

Environment Variables

# Enable/disable Simorgh Logger
SIMORGH_LOGGER_ENABLED=true

# Storage driver (database, file, sentry, elasticsearch)
LOG_STORAGE_DRIVER=database

# Alert settings
LOG_ALERTS_ENABLED=true
LOG_ALERT_EMAIL_ENABLED=true
LOG_ALERT_EMAIL_TO=admin@example.com
LOG_ALERT_SLACK_ENABLED=true
LOG_ALERT_SLACK_WEBHOOK=https://hooks.slack.com/services/...

# Dashboard settings
LOG_DASHBOARD_ENABLED=true
LOG_DASHBOARD_PREFIX=advanced-logger
LOG_DASHBOARD_REALTIME=true

# Auto-logging
LOG_AUTO_REQUESTS=true
LOG_AUTO_MODELS=false
LOG_AUTO_QUERIES=false

# Performance
LOG_USE_QUEUE=false
LOG_RETENTION_ENABLED=true
LOG_RETENTION_DAYS=30

Custom Route Prefix & Middleware

You can customize the route prefix and middleware for the dashboard:

Option 1: Using Environment Variables

# Custom route prefix (default: advanced-logger)
LOG_DASHBOARD_PREFIX=admin/dashboard/logs/panel

Option 2: Using Config File

// config/advanced-logger.php
'dashboard' => [
    'enabled' => true,
    'prefix' => 'admin/dashboard/logs/panel', // Custom prefix
    'middleware' => ['web', 'auth', 'role:admin'], // Add your middleware
    // ...
],

Examples:

Configuration	Resulting URL
`prefix => 'advanced-logger'`	`mysite.com/advanced-logger`
`prefix => 'admin/logs'`	`mysite.com/admin/logs`
`prefix => 'admin/dashboard/logs/panel'`	`mysite.com/admin/dashboard/logs/panel`

Middleware Examples:

// Basic authentication only
'middleware' => ['web', 'auth'],

// With role-based access (Spatie Permission)
'middleware' => ['web', 'auth', 'role:admin'],

// With permission-based access
'middleware' => ['web', 'auth', 'permission:view-logs'],

// Multiple roles
'middleware' => ['web', 'auth', 'role:admin|developer'],

// Custom middleware
'middleware' => ['web', 'auth', 'custom.admin'],

Auto-Logging Middleware

Add to your app/Http/Kernel.php:

protected $middleware = [
    // ...
    \Simorgh\Logger\Middleware\LogRequestsMiddleware::class,
];

📈 Statistics & Analytics

// Get comprehensive stats
$stats = Simorgh::getStats();

// Get stats with filters
$stats = Simorgh::getStats([
    'level' => ['error', 'critical'],
    'date_from' => '2025-01-01',
    'date_to' => '2025-01-31'
]);

// Get logs with pagination
$logs = Simorgh::getLogs([
    'category' => 'auth',
    'search' => 'login'
], 50);

📤 Export & Cleanup

Export Logs

// Export as JSON
$json = Simorgh::exportLogs(['level' => 'error'], 'json');

// Export as CSV
$csv = Simorgh::exportLogs(['category' => 'auth'], 'csv');

// Export as XML
$xml = Simorgh::exportLogs(['date_from' => '2025-01-01'], 'xml');

Cleanup Commands

The package includes a powerful cleanup command that automatically removes old logs:

# Cleanup logs older than 30 days (uses config default)
php artisan logs:cleanup

# Cleanup logs older than specific number of days
php artisan logs:cleanup --days=30

# Cleanup only specific level
php artisan logs:cleanup --level=error

# Cleanup only specific category
php artisan logs:cleanup --category=auth

# Dry run (see what would be deleted without actually deleting)
php artisan logs:cleanup --dry-run

# Compress logs before deletion (saves backup)
php artisan logs:cleanup --compress

Automatic Cleanup (Cron Job)

The cleanup command runs automatically! No manual setup needed. 🎉

By default, it runs daily at 2 AM and removes logs older than:

7 days in local environment
14 days in staging environment
30 days in production environment

Customize the schedule:

# .env
LOG_RETENTION_ENABLED=true
LOG_RETENTION_DAYS=30  # Not used by auto-scheduler, but by manual command

// config/advanced-logger.php
'retention' => [
    'enabled' => true,
    'days' => [
        'local' => 7,
        'staging' => 14,
        'production' => 30,  // Delete logs older than 30 days
    ],
    'compress_before_delete' => true,
    'cleanup_schedule' => '0 2 * * *', // Daily at 2 AM (cron expression)
],

Custom cron schedules:

Expression	Description
`0 2 * * *`	Daily at 2:00 AM (default)
`0 0 * * 0`	Weekly on Sunday at midnight
`0 3 * * 1`	Every Monday at 3:00 AM
`/30 * * *`	Every 30 minutes
`0 /6 * *`	Every 6 hours

Important: Make sure Laravel's scheduler is running:

# Add to your crontab (crontab -e)
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Manual Cleanup

You can also run cleanup manually at any time:

# Clean up now using environment defaults
php artisan logs:cleanup

# Force cleanup of logs older than 1 month
php artisan logs:cleanup --days=30

# Test what would be deleted first
php artisan logs:cleanup --days=30 --dry-run

🔒 Security Features

Automatic Sanitization

The package automatically sanitizes sensitive data:

// These will be automatically masked
Simorgh::info('User data', [
    'password' => 'secret123',        // → '[REDACTED]'
    'api_token' => 'abc123',         // → '[REDACTED]'
    'credit_card' => '4111111111111111', // → '[REDACTED]'
    'ssn' => '123-45-6789',          // → '[REDACTED]'
]);

Custom Sanitization Patterns

// config/simorgh-logger.php
'security' => [
    'sensitive_patterns' => [
        '/password/i',
        '/token/i',
        '/secret/i',
        '/key/i',
        '/credit_card/i',
        '/ssn/i',
        '/social_security/i',
        '/my_custom_field/i',  // Add your own patterns
    ],
    'mask_replacement' => '[REDACTED]',
],

🎯 Categories

Predefined categories for better organization:

auth - Authentication & Authorization
api - API Requests & Responses
payments - Payment Processing
database - Database Operations
mail - Email Operations
queue - Queue Processing
cache - Cache Operations
file - File Operations
security - Security Events
performance - Performance Monitoring
debug - Debug Information

🔌 Integrations

Sentry Integration

'integrations' => [
    'sentry' => [
        'enabled' => true,
        'dsn' => env('SENTRY_LARAVEL_DSN'),
    ],
],

Elasticsearch Integration

'integrations' => [
    'elasticsearch' => [
        'enabled' => true,
        'host' => env('ELASTICSEARCH_HOST', 'localhost:9200'),
        'index' => env('ELASTICSEARCH_LOG_INDEX', 'laravel-logs'),
    ],
],

🧪 Testing

# Run tests
composer test

# Run with coverage
composer test-coverage

Testing in Your Application

// Test logging
Simorgh::shouldReceive('error')->once()->with('Test message', []);
Simorgh::error('Test message', []);

// Test alerts
$alertHandler = app(\Simorgh\Logger\Handlers\AlertHandler::class);
$results = $alertHandler->testChannels();

📝 Changelog

Please see CHANGELOG for more information on what has changed recently.

🤝 Contributing

Please see CONTRIBUTING for details.

🐛 Bug Reports

If you discover a security vulnerability, please send an email to falaahatiali@gmail.com. All security vulnerabilities will be promptly addressed.

📄 License

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

🙏 Credits

Falahati Ali - Creator and maintainer
All Contributors - Contributors

📚 Additional Resources

Installation Guide - Complete setup guide
Integration Guide - Integrate with existing admin panels
Laravel Logging Documentation
Monolog Documentation
Laravel Package Development

Made with ❤️ and 🦅 for the Laravel community