README

Deep observability for Laravel Events and Listeners with execution tracing, waterfall visualization and side-effect tracking.

Features

• Event tracing - Capture every dispatch(), until() and listener execution with parent-child hierarchy
• Waterfall visualization - Interactive dashboard showing event execution trees with timing bars
• Side-effect tracking - Count database queries and mails sent per listener via pluggable watchers
• Payload inspection - Safe serialization with binary detection, depth limits, string truncation and key redaction
• Model change tracking - Automatic dirty-state capture for Eloquent models in event payloads
• Polymorphic model linking - Associate events with models via HasEventLens trait
• Exception capture - Record exceptions thrown during listener execution with error filtering and breakdown
• Event tagging - Opt-in structured metadata via Taggable interface with dashboard filtering
• Cross-queue tracing - Correlation ID propagation through queued jobs
• Octane safe - Automatic state reset between requests
• Sampling - Configurable rate to minimize production overhead
• Statistics dashboard - Tabbed interface (Overview, Performance, Errors) with execution time histogram, event mix composition bar, error breakdown, query load ranking, listener-level drill-down, and daily timeline with error overlay

Requirements

• PHP 8.2+
• Laravel 10 or 11

Installation

composer require gladehq/laravel-event-lens
php artisan event-lens:install

The install command publishes the config file and runs migrations.

Manual installation

php artisan vendor:publish --tag=event-lens-config
php artisan migrate

Configuration

All options live in config/event-lens.php:

Dashboard

Visit /event-lens (or your configured path) to access:

• Stream - Live event feed with filtering by event name, listener name, payload content, tag content, date range, slow-only and errors-only toggles. Each row shows listener name, inline badges for errors, query counts, mail counts and tags, and a copy-to-clipboard button for correlation IDs.
• Statistics - Tabbed dashboard organized into three views. Always-visible summary cards (total events, avg execution time, slow count, error rate, total queries, total mails) with quick date presets (Today, 7d, 30d). Overview tab: daily volume bar chart with error rate dots overlay, execution time distribution histogram (color-coded latency buckets), and event mix composition bar. Performance tab: top events by frequency with inline proportional bars and expandable per-listener breakdown, slowest individual events, and heaviest events by query load with inline bars. Errors tab: error breakdown grouped by exception type with count badge. All event names link to the stream page for drill-down. Tabs are bookmarkable via URL hash.
• Waterfall - Per-correlation execution tree with timing bars, query/mail counts, error and slow counts in the header, error propagation badges on ancestor nodes, "Jump to error" navigation, and a compact/detailed view toggle
• Detail - Listener-focused header with event context, previous/next sibling navigation within the correlation, payload and correlation ID copy-to-clipboard, expandable exception with collapsible stack trace, model changes rendered as a before/after diff table, tags, and side effects

Authorization

By default, the dashboard is accessible only in the local environment. Customize via config:

'authorization' => function ($user) {
    return $user && $user->isAdmin();
},

Octane Support

EventLens automatically resets all singleton state (buffer, recorder, watchers) between Octane requests when Laravel\Octane is detected. No configuration needed.

Queue Tracing

Correlation IDs propagate automatically into queued job payloads. Events dispatched inside a job inherit the parent correlation ID, linking the full trace across sync and async boundaries. No configuration needed.

HasEventLens Trait

Associate models with their event logs:

use GladeHQ\LaravelEventLens\Concerns\HasEventLens;

class Order extends Model
{
    use HasEventLens;
}

// Query events for a model
$order->eventLogs()->latest()->get();

Events automatically detect models in their public properties and store model_type/model_id for polymorphic lookups.

Event Tagging

Tag events with structured metadata by implementing the Taggable interface:

use GladeHQ\LaravelEventLens\Contracts\Taggable;

class OrderPlaced implements Taggable
{
    public function __construct(
        public Order $order,
        public string $channel,
    ) {}

    public function eventLensTags(): array
    {
        return [
            'channel' => $this->channel,
            'priority' => $this->order->total > 1000 ? 'high' : 'normal',
        ];
    }
}

Tags are stored in a dedicated JSON column and displayed as purple badges on the dashboard. Use the "Tag Contains" filter on the stream page to search events by tag content.

Custom Watchers

Implement WatcherInterface to track additional side effects:

use GladeHQ\LaravelEventLens\Contracts\WatcherInterface;

class RedisWatcher implements WatcherInterface
{
    protected array $stack = [];

    public function boot(): void
    {
        // Register listeners for Redis commands
    }

    public function start(): void { $this->stack[] = 0; }
    public function stop(): array { return ['redis' => array_pop($this->stack) ?? 0]; }
    public function reset(): void { $this->stack = []; }
}

Register in config:

'watchers' => [
    \GladeHQ\LaravelEventLens\Watchers\QueryWatcher::class,
    \GladeHQ\LaravelEventLens\Watchers\MailWatcher::class,
    \App\Watchers\RedisWatcher::class,
],

Artisan Commands

Publishing Views

php artisan vendor:publish --tag=event-lens-views

Views will be published to resources/views/vendor/event-lens/.

How It Differs from Telescope

License

MIT