Observability Livewire Laravel Package

Getting Started

First, calibrate expectations. This is a zero-star, zero-dependent module with a NOASSERTION license and a release date that appears to be in the future relative to normal packagist cadence. It is almost certainly an internal building block of the Liberu monorepo (the module-* naming and liberusoftware namespace follow that convention) rather than a standalone, documented package. Treat the source as the documentation and budget time for reading it before you composer require anything.

Minimal setup path:

composer require liberusoftware/observability-livewire
php artisan vendor:publish --provider="Liberu\Observability\Livewire\ObservabilityLivewireServiceProvider"
php artisan list | grep -i observ

Where to look first, in this order:

1. composer.json — require tells you what it actually wraps. If you see open-telemetry/*, spatie/laravel-ray, or laravel/telescope, that determines your whole integration strategy. If the dependency list is thin and Livewire-only, it is a presentation adapter over data something else produces, and it will render empty until that producer exists.
2. The service provider in vendor/liberusoftware/observability-livewire/src/ — check what it binds, whether it registers a Livewire component namespace, routes, or middleware, and whether config is merged vs. published.
3. config/ and resources/views/ — for a "presentation adapter," the Blade views are the API. They reveal the exact property names the Livewire components expect.

First use case: get the thing to render on a single route before wiring it anywhere else. In the Liberu stack that usually means adding the shipped Livewire component to an existing dashboard view:

<livewire:observability-dashboard />

…or whatever the namespace resolves to after php artisan livewire:list. If nothing renders and no error appears, you are looking at a silent-empty-data problem, not a broken install — see the Gotchas section.

Implementation Patterns

Mount it as a panel, not a page. Observability UI is read-heavy and rarely needs its own top-level route. The lowest-friction pattern is embedding the adapter's component into an existing admin/filament-style dashboard, guarded by your normal admin middleware. This avoids inheriting whatever auth assumptions the module ships with.

Feed it from the layer below, don't instrument inside it. The healthy split is:

• Producer (your app middleware, Livewire lifecycle hooks, queue middleware) writes spans/events/metrics to a store.
• Adapter (this package) reads that store and renders it.

If you find yourself adding Log::info() calls inside the adapter's components to make numbers appear, you have inverted the dependency and the next package upgrade will erase your work.

Livewire-side instrumentation pattern. Livewire requests are easy to lose in traces because they look like ordinary POSTs to /livewire/update. If you are generating the signal yourself, wrap the update endpoint and tag it with the component name so the adapter's tables are actually readable:

// middleware
public function handle($request, Closure $next)
{
    $span = $this->tracer->span('livewire.update', [
        'livewire.component' => $request->input('components.0.snapshot.memo.name'),
        'livewire.method'    => $request->input('components.0.calls.0.method'),
    ]);

    try {
        return $next($request);
    } finally {
        $span->end();
    }
}

That single tag is the difference between a dashboard of anonymous POSTs and one you can actually diagnose with.

Polling beats websockets for v1. These adapters typically expose a Livewire poll directive. Start conservative:

<div wire:poll.15s>

Then relax it. Aggressive polling on a dashboard that queries a trace table without an index is the single most common way this package becomes the incident it was installed to detect.

Integration tip — correlate with your log channel. Push the current trace/span ID into the log context once, globally, so storage/logs/laravel.log and the dashboard agree:

Log::withContext(['trace_id' => $span->getTraceId()]);

Then a user-reported error is one grep away from the span the adapter is displaying.

Keep it out of production hot paths. Gate the whole thing behind a config flag (OBSERVABILITY_UI_ENABLED) resolved in the service provider, so you can disable rendering without removing the package or redeploying config.

Gotchas and Tips

Silent empty state is the default failure mode. A presentation adapter with no producer, no published config, or a misconfigured driver renders a clean, plausible-looking empty dashboard with no error. When the first render is blank, check in this order: config published? store reachable? rows actually exist in the underlying table/collector? Do not start editing Blade files.

The license is NOASSERTION. That is a legal unknown, not an open-source license. Before this reaches anything client-facing or distributed, confirm the actual terms with the maintainer or read the LICENSE file directly in the repo. For internal Liberu-module use this is usually fine; for a shipped product it is a blocker.

Zero dependents means zero field-testing. No one else's bug reports exist, so version bumps are unvalidated. Pin to an exact version, and after any composer update, diff vendor/liberusoftware/observability-livewire/ against your last known-good copy. There is no changelog you can trust.

Config merge vs. publish. If the provider uses mergeConfigFrom, published config wins forever and silently ignores upstream defaults added in later releases — a classic source of "the new option does nothing." Keep a comment at the top of your published config noting the version you published from.

Livewire component namespace collisions. Modules that register their own namespace (Livewire::component('observability.*', ...)) will conflict with an app-level component of the same name. Run php artisan livewire:list after install and confirm exactly one match per name.

Debugging without a debugger. Since docs are absent, use these to map the surface area:

php artisan vendor:publish --provider="..." --tag=config   # discover tags
php artisan route:list | grep -i observ
php artisan about --only=config                            # confirm config loaded

Extension points to prefer. Blade view overriding (php artisan vendor:publish --tag=views) is the safest customization seam — it survives minor upgrades. Subclassing the Livewire components is next safest. Monkey-patching the service provider is a last resort that will break on the first release.

Performance guard. Wrap any custom query you add behind the adapter in DB::listen() for one profiling session; if the dashboard adds more than a handful of queries per poll, move the aggregation into a scheduled command writing to a summary table, and let the adapter read that.