Eagle Eye Filament Laravel Package

Getting Started

dotswan/eagle-eye-filament is the admin UI layer, not the engine. The core dotswan/eagle-eye package does the capture, storage and querying; this package gives you Filament 5 pages, charts and widgets on top of it. Budget for installing both, in that order.

Prerequisites

• Laravel 12 or 13, Filament 5.x already installed and a panel booting.
• dotswan/eagle-eye at 1.0.0-beta.1 or newer — the Filament package will not work against older core versions.
• PHP version matching Filament 5's floor, and a database the core package supports for its event table.

Install

composer require dotswan/eagle-eye:^1.0@beta dotswan/eagle-eye-filament:^1.0@beta

Both constraints need @beta (or minimum-stability: beta in composer.json) because no stable tag exists yet. Pin both to the same beta line and bump them together — see Gotchas.

Then, in rough order

1. Publish and run the core package's migrations/config (php artisan vendor:publish --tag=... then migrate). The Filament package is a read layer; it has nothing to show until events exist.

2. Register the plugin on your admin panel in app/Providers/Filament/AdminPanelProvider.php:

   ->plugin(\Dotswan\EagleEyeFilament\EagleEyeFilamentPlugin::make())
   

   Confirm the exact FQCN from the package README — pre-1.0 namespaces have moved before.

3. Publish the Filament assets (php artisan filament:assets) and, if you use a custom theme, rebuild it so the package views pick up your Tailwind config.

4. Define who can see it. Do this before you demo it to anyone — the pages expose request payloads, actor identities and field-level diffs.

First use case: open the Activity overview and read the KPI cards and channel/severity charts to establish a baseline, then jump into the Activity explorer and filter to a single channel and a 24-hour window. That two-minute path tells you whether your capture pipeline is emitting what you think it is, which is the fastest way to validate the whole install.

Where to look first: the core package's config (channels, severity mapping, retention), then the Filament package's config for reveal policies and Livewire capture, then your AuthServiceProvider/policies.

Implementation Patterns

Panel plugin, not a route file. Everything hangs off the panel plugin registration. Put it on your admin/staff panel only; registering it on a customer-facing panel is the fastest way to leak internals. If you run multiple panels, register per-panel and vary config through the panel's ->plugin(...) chain rather than global config where possible.

Gate the surface, then gate the detail. Two layers:

// Coarse: who can open the pages at all
public function canAccess(): bool
{
    return $this->user?->hasRole('support-lead') ?? false;
}

// Fine: policy-gated reveal of field-level changes / payloads
Gate::define('viewEagleEyePayload', fn (User $u, $event) => $u->isAdmin());

Coarse gating via the plugin/panel keeps the navigation clean; the per-event reveal policy is what stops a support agent from reading a password-reset token out of a payload diff. Wire both, and write a test asserting the 403 — this is the one place where a silent regression is a security incident.

Dashboard widgets on the panel, history on resources. KPI cards, sparklines and the actor heatmap are panel widgets — register them in the panel's widgets([...]) or discoverWidgets. The record history and recent-traces blocks are more useful embedded next to the thing they describe: drop them onto a resource view page or as a tab so an agent debugging "why did this order change" never leaves the order screen. Keep the dashboard for aggregate triage and the resource page for per-record forensics.

Structured token search is the power feature — teach it. The explorer's token syntax (channel:, severity:, plus whatever actor/trace tokens the package exposes — check the in-UI field reference, not the release notes) is what separates this from a log viewer. Bake the syntax into onboarding docs and saved links. Facets and tokens should agree; if a facet click produces a filter the token bar can't reproduce, that's worth reporting upstream.

Traces are only as good as your propagation. The trace timeline and stream view correlate events by trace/request ID. That ID has to be injected by you — middleware that generates a ULID per request and pushes it into the core package's context, plus job/middleware propagation for queues. Without that, the trace view renders single-event timelines and looks broken.

Livewire interaction capture needs scoping. Turning it on gives you readable Filament page/action titles instead of raw component classes, which is genuinely useful for "what did the admin actually click". But it is high-volume and it captures user behaviour. Enable it for admin/support panels, not the whole app; filter out noisy polling components; and check whether payloads are captured or only titles before you enable it in production.

Seed realistic data locally. You cannot evaluate the charts against three fixture rows. Write a seeder or artisan command that pushes a few thousand synthetic events through the core package across several channels, severities and trace IDs, with a minority of events carrying field-level changes. This also gives you a dataset for checking chart query performance.

Gotchas and Tips

• Beta means beta. Both packages are 1.0.0-beta.1 and the notes explicitly say the API may change. Pin exact versions (1.0.0-beta.1, not ^1.0@beta) in composer.lock, read CHANGELOG.md before every bump, and expect at least one breaking change to plugin registration or config keys before 1.0.0. Do not build internal tooling that hard-depends on package internals.
• Version lockstep. The Filament package requires core >= 1.0.0-beta.1. Upgrading one and not the other produces confusing failures — typically a missing method or an empty page rather than a clean exception.
• Nothing renders without events. A blank overview page is almost always "no data captured", not "broken install". Check the core event table has rows before debugging the UI.
• High-volume tables hurt here first. Sparklines, heatmaps and the overview charts all run aggregate queries. On a busy app, default the explorer to a narrow window, add indexes on the timestamp and channel columns the package queries (check the migration), and consider pointing the core package at a read replica or a pruned/rolled-up table. The heatmap is the usual culprit.
• Timezone drift. Store events in UTC, render in app timezone — but verify how the package buckets chart data by day/hour. Off-by-one day boundaries in a heatmap are hard to spot and easy to misread as a real trend.
• Reveal policies fail closed, silent and quiet. If the policy denies, the UI typically hides the section rather than erroring. During rollout, temporarily log denials so you can tell "no data" from "permission denied" while wiring policies.
• Navigation collisions. The plugin registers several pages; if your panel already has pages with similar slugs or a crowded nav group, set the navigation group/label/sort through the plugin config rather than editing vendor views.
• Filament 5 asset pipeline. Custom themes need a rebuild after install or the package's views render unstyled. filament:assets alone is not enough if you ship a Vite/Tailwind theme.
• Capture capture capture. Livewire interaction capture plus full payload storage plus policy-gated reveal is a lot of PII in one table. Decide retention before launch, not after, and confirm what the reveal gate actually protects — titles only, or arguments too.
• Extension points to prefer: custom dashboard widgets (standard Filament widgets over the core query API), your own policy classes, overridden Blade views via vendor:publish for branding, and config-level channel/severity labels for domain vocabulary. Avoid subclassing package pages — those are the classes most likely to change pre-1.0.
• Testing: use Livewire component tests for any custom widget you add, and one feature test per policy path (allowed and denied). For the package's own pages, assert access control and that the page renders 200 with data present — don't assert on chart internals.