Laravel Monocle Laravel Package

Getting Started

Monocle is a tracing/observability package for Laravel: it records what your app did during a request (queries, cache hits/misses, validation, views, logs, notifications) and surfaces it in a UI so you can see why something happened, not just that it was slow.

Minimal path:

1. composer require exeque/laravel-monocle (dev dependency unless you want it in production — see Gotchas).
2. Run php artisan monocle:install to publish the config and scaffold the tracing setup. Note (v0.9.0): the installer does not enable browser tracing; you must set trace.browser.enabled to true yourself if you want the Monocle button in the browser.
3. Open config/monocle.php and read the trace.* tree first — that's where lenses, storage and the browser toggle live. Everything else in the docs is downstream of that file.
4. Start with the cache lens: the repeated-read warning is the fastest way to see value, because a duplicate Cache::get() inside a loop is a real bug you can fix in minutes.
5. Keep the docs open at exeque.github.io/laravel-monocle — the browser-tracing page is the one that has historically drifted from the actual behaviour.

First realistic use case: a page that feels slow. Open the trace, sort by duration, and look at the origins attached to each span rather than the span names.

Implementation Patterns

Lens-driven tracing. Treat the lenses (validation, cache, log, views, notifications) as independently switchable units. Enable only what you're investigating in a given environment — tracing everything everywhere both costs performance and buries the signal. Per-environment config in config/monocle.php is the intended integration point.

Browser tracing as an opt-in, per-developer toggle. Since v0.9.0 the Monocle button is strictly gated on trace.browser.enabled. The practical pattern is to leave it false in the committed config and flip it via .env (MONOCLE_BROWSER_ENABLED=true) so individuals opt in without touching shared config.

Full-page Livewire components. Traces now name the layout template (e.g. layout:layouts.public) and attribute the view to the component's render(). Use this to distinguish layout cost from component cost — previously both collapsed into an opaque inline:<hash> entry, which made it impossible to tell whether a slow full-page component was the layout or the component itself.

Filament notifications. On Filament ≥ 5.10.2, notifications sent with ->send() live in a notification mailbox rather than the session. If you're writing assertions or trace-based checks around notifications, don't reach into the session — read the trace output instead, which works across both the old and new Filament storage models.

Log origins as navigation. A logged warning now carries its own file and line as origin rather than the app code that happened to be executing. Build the habit of clicking through the origin rather than grepping the message; the origin points at the trigger_error/deprecation site, which is usually the fixed location, not the call site that surfaced it.

Pair it with a profiler. Monocle answers "what did the framework do on this request and why"; it is not a CPU profiler. Use it alongside Telescope-style request inspection, not instead of it.

Gotchas and Tips

• Version 0.9.0 is pre-1.0. There is no stability promise. Pin the exact version in composer.json and read release notes on every bump — this release alone changed view naming and log origins, both of which are observable-output changes.
• The layout: rename is a breaking change in practice. If you have saved traces, fixtures, dashboards, or assertions that match on inline: + hash, they will silently stop matching. Grep your test suite and any saved trace baselines for inline: before upgrading.
• Log origins moved. Anything asserting on the previous origin for warnings/deprecations — snapshot tests especially — will diff. The new behaviour is more useful, but it is different.
• PHP 8.5 + validation lens was logging SplObjectStorage deprecations on every validated request. Fixed in 0.9.0. If you're on 8.5 and on an earlier version, those deprecations are noise from Monocle, not from your code — don't go hunting.
• The array-driver cache warning is now suppressed. Cache::memo() can't save anything on the array store, so the repeated-read warning was a false positive. Note that this means you won't get a nudge for genuinely repeated reads in tests that use the array driver — switch to a real store if you're using Monocle to validate cache behaviour.
• Filament version boundary at 5.10.2. Notification recording behaves differently either side of it. If notifications are missing from traces, check the Filament version first; both paths are supported but the failure modes differ.
• Browser button missing? It's trace.browser.enabled, and monocle:install will not turn it on. This tripped people up enough that the README, install docs and command output were all updated — if you're following a stale tutorial, that's the gap.
• Don't ship tracing to production by accident. Tracing adds overhead and can capture sensitive request data. Gate the whole package on APP_ENV / a dedicated flag rather than relying on individual lens toggles.
• Extension point: the config file's lens definitions are the sanctioned seam for custom instrumentation. Prefer registering an additional lens over patching vendor code — the internals are still moving at 0.x.