Observability Filament Laravel Package

Getting Started

This package is the Filament presentation layer for Liberu's module-observability domain package — it almost certainly ships Filament resources, pages, and widgets (logs, health, metrics, traces, queue/scheduler status) rather than doing any collection itself. Treat it as a UI adapter: the core module does the work, this package renders it in your panel.

Minimum steps:

1. Install the core module first — composer require liberusoftware/module-observability — then the adapter:

   composer require liberusoftware/observability-filament
   

2. Publish anything publishable (config, migrations if it stores snapshots):

   php artisan vendor:publish --tag="observability-filament-config"
   

   Check the tag names in the service provider if that tag 404s — modular Liberu packages vary.
3. Register the plugin on your panel in app/Providers/Filament/AdminPanelProvider.php:

   ->plugin(ObservabilityFilamentPlugin::make())
   

4. Clear caches: php artisan optimize:clear && php artisan filament:optimize-clear.

Where to look first, in order:

• src/ObservabilityFilamentServiceProvider.php — what's registered, config keys, view namespaces.
• src/*Plugin.php — the plugin's register()/boot() and any fluent configuration (navigation group, authorization callbacks, widget toggles).
• src/Filament/Resources/* and src/Filament/Widgets/* — the actual surface area you'll be customizing.
• config/observability-filament.php — feature flags, retention, polling intervals.
• README.md and CHANGELOG.md — with 0 stars and a 2026 release date, the changelog is your only reliable API contract.

First use case: log into /admin, open the Observability navigation group, and confirm the health/overview page loads with live data from the core module. Then drag one widget (queue depth or failed jobs is a good canary) onto your main dashboard to prove the adapter is wired correctly before you build on it.

Implementation Patterns

Plugin-per-panel registration. Register the plugin only on panels that need it — typically AdminPanelProvider, not customer-facing panels. This keeps observability tooling behind your staff auth boundary.

Fluent configuration at the panel level. Most Liberu Filament adapters expose a chainable plugin API. Expect patterns like:

ObservabilityFilamentPlugin::make()
    ->navigationGroup('System')
    ->pollingInterval('30s')
    ->authorizeUsing(fn (User $user) => $user->hasRole('ops'));

Check the plugin class for the exact method names before relying on them.

Gate the whole surface. Don't rely on panel access alone. Add a viewObservability gate (or a policy on the core module's models) and hook it into the plugin's authorization callback. Logs and traces leak secrets, tokens, and PII — this is the single most important integration point.

Widgets over pages for day-to-day use. The resources are for investigation; the widgets are for monitoring. The highest-leverage pattern is composing 3–5 observability widgets into your existing dashboard rather than sending the team to a separate page:

protected function getHeaderWidgets(): array
{
    return [
        \LiberuSoftware\ObservabilityFilament\Filament\Widgets\HealthOverview::class,
        \LiberuSoftware\ObservabilityFilament\Filament\Widgets\FailedJobsTable::class,
    ];
}

Extend, don't fork. If a resource needs a column or filter, subclass the package resource and re-register it in your panel, overriding table(Table $table) or getEloquentQuery(). This survives package upgrades far better than editing vendor/.

Scope to tenancy. In multi-tenant apps, override getEloquentQuery() on each resource to constrain by tenant_id. The core module usually scopes writes; the adapter's read queries are the part you must verify.

Pair with the core module's events. Trigger Filament notifications from the core observability events (health check failed, queue threshold breached) via a small listener — the adapter won't do this for you, but it's the natural place to close the loop from "dashboard" to "alert."

Testing. Use Filament's testing helpers against the pages:

livewire(HealthOverview::class)->assertOk();

Set up a panel in TestCase with the plugin registered, or these tests will fail with "page not found" rather than a useful assertion.

Gotchas and Tips

• Version alignment is the big one. Filament v3 → v4 changed resource/page APIs substantially. Pin the adapter version against your Filament major in composer.json and read the changelog before any composer update. A 0-star package will not warn you about breakage.
• NOASSERTION license. Read the LICENSE file in the repo before shipping this commercially. "No assertion" means the package's own metadata doesn't declare a license — that's a legal question, not a technical one.
• Zero dependents, zero stars. There's no community to lean on. Budget time for reading source rather than Googling errors, and consider vendoring a pinned copy ("liberusoftware/observability-filament": "1.x-dev#<sha>") if the package is critical to your admin UI.
• Install both packages. Installing only the adapter gives you empty pages — the core module-observability package provides the models, queries, and collectors. Symptom: dashboard renders but every widget reads "no data."
• Cache clearing is non-optional. Filament caches components and views aggressively. After any config or resource change, run php artisan filament:optimize-clear (or optimize:clear), or you'll chase phantom bugs in local development.
• Tune widget polling. Livewire widgets default to short poll intervals; a table of logs polling every 5s across many admin users will load your database. Set intervals in the plugin config or override $pollingInterval per widget.
• Navigation collisions. The package registers its own navigation group. If you already have a "System" or "Logs" group, rename via the plugin's navigation config rather than editing views.
• Authorization defaults may be permissive. New modular packages frequently ship with panel-access-only gating. Add your own gate before exposing this to non-superadmin roles.
• Log volume kills the table. Long-running apps need retention/pruning on the underlying store; the Filament resource paginates but won't save you from a 10M-row activity_log scan. Confirm indexes on the core module's tables and configure pruning.
• Extension points to prefer, in order: plugin fluent config → resource subclass + re-register → published views (if views are publishable) → vendor patch (last resort, will be lost on update).
• Debugging empty resources: check the core module's collector is running (php artisan observability:status or equivalent), then check your getEloquentQuery() scoping, then check the panel's canAccessPanel() — in that order. The adapter failing looks identical to no data being collected.