README

Laravel error observability dashboard with a Sentry-inspired UI for viewing and investigating error logs.

LogPulse scans your Laravel log files, groups similar errors into issues, tracks events over time, and provides a clean dashboard to investigate stack traces, request context, and error trends.

Requirements

• PHP 8.2+
• Laravel 11 or 12
• Inertia.js v2 with React

Installation

composer require abdasis/logpulse

Publish the config file:

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

Run migrations:

php artisan migrate

Publish the frontend pages (Inertia/React):

php artisan vendor:publish --tag=logpulse-pages

This copies the dashboard pages to resources/js/pages/admin/logpulse/.

Configuration

After publishing, the config file is at config/logpulse.php:

return [
    // Database connection (null = default app connection)
    'connection' => env('LOGPULSE_DB_CONNECTION', null),

    // Route prefix
    'prefix' => 'cat-admin/logpulse',

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

    // Directories to scan for log files
    'log_paths' => [
        storage_path('logs'),
    ],

    // Glob pattern for log files
    'log_pattern' => 'laravel*.log',

    // Scanner position tracking file
    'position_file' => storage_path('logpulse/scanner-positions.json'),

    // Days to keep events before pruning
    'retention_days' => 30,
];

Database Connection

By default LogPulse uses your app's default database connection. To use a separate database (e.g. SQLite), set the LOGPULSE_DB_CONNECTION env variable and add the corresponding connection in config/database.php.

Route Prefix & Middleware

Customize the prefix and middleware to match your application's admin route structure.

Usage

Scanning Logs

Scan your log files and aggregate errors into issues:

php artisan logpulse:scan

The scanner tracks file positions, so subsequent runs only process new log entries. It also detects log rotation automatically.

For continuous monitoring, schedule the command in your routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('logpulse:scan')->everyFiveMinutes();

Pruning Old Events

Remove events older than the configured retention period:

php artisan logpulse:prune

Override the retention period:

php artisan logpulse:prune --days=7

Dashboard

Visit the dashboard at your configured prefix (default: /cat-admin/logpulse). The dashboard provides:

• Log file browser -- Select and browse individual log files
• Search & filter -- Filter by log level, search by message or exception class
• Pagination -- Navigate through large log files

Issue Detail

Each issue page shows:

• Exception class, message, file, and line number
• Full stack trace with vendor frame highlighting
• Event timeline chart (last 14 days)
• Request context (method, URL, headers, body)
• Actions: resolve, reopen, archive, delete

How It Works

1. LogScanner reads log files from configured paths, tracking file positions to avoid re-processing
2. LogParser extracts structured data (level, message, exception, stack trace, timestamp) from raw log entries
3. Fingerprinter generates a unique hash for each error based on exception class, file, line, and normalized message
4. LogAggregator groups parsed entries into issues by fingerprint and stores individual events
5. Resolved issues are automatically reopened if the same error reappears

Database Tables

LogPulse creates two prefixed tables to avoid conflicts:

• logpulse_issues -- Grouped error issues with fingerprint, status, and event count
• logpulse_events -- Individual error occurrences with full context

License

MIT License. See LICENSE for details.