Lara Monitor Laravel Package

Getting Started

nivseb/lara-monitor is an in-app APM/tracing layer for Laravel: it records requests and the nested spans inside them so you can see where time is spent without wiring up an external agent. v1.2.0 is a good entry point — it adds span recording limits, Laravel 13 support, and PHP 8.5 support, and the test suite moved to Pest 4.

Minimum steps:

1. composer require nivseb/lara-monitor (v1.2.0 requires a modern Laravel/PHP combination — Laravel 13 and PHP 8.5 are now explicitly supported, so bump your platform constraints if you were holding back).
2. Publish the config: php artisan vendor:publish --tag=lara-monitor-config (check the package README for the exact tag) and review it before enabling anything in production.
3. Confirm the storage/driver setup the package expects — it needs somewhere to write recorded spans, and that backing store should be created/migrated before you flip the switch.
4. Start with the smallest possible surface: enable recording for a single route or a single job, hit it, and verify data shows up end-to-end.

First use case to try: wrap one slow endpoint (or one queued job) and look at the span breakdown. That immediately tells you whether the granularity is useful for your debugging workflow or whether you need to tune what gets recorded.

Where to look first in the codebase: the service provider (what gets bound and auto-registered), the config file (all the toggles and, new in this release, the span limiting settings), and the middleware/job hooks that start and stop recording.

Implementation Patterns

Instrument the boundaries, not the internals. The natural pattern is one span per meaningful unit of work: an HTTP request, a queued job, a console command, an outbound HTTP call. Let the package handle the request boundary automatically and add manual spans around the expensive things you actually care about (a reporting query, a third-party API call, a batch loop).

// Manual span around an expensive operation
$result = monitor()->span('report:generate', function () use ($range) {
    return $this->reportService->build($range);
});

Use the new span limits as a production guardrail, not a dev tool. In v1.1.x, a pathological request (a loop that creates spans per item) could quietly generate an unbounded number of spans per trace. Configure the limit deliberately: pick a ceiling per trace that is comfortably above your normal worst case, so you cap runaway traces without truncating legitimate ones. In local/staging, set it high (or disable) so you don't lose detail while debugging.

Pair it with sampling. Limiting spans per trace and sampling traces are complementary: sampling controls how many traces you keep; the new limit controls how big each kept trace can get. Use sampling for volume and the span limit for the outliers.

Integrate at the job/dispatch layer for queue-heavy apps. Wrap handle() in a span tied to the job class name, and tag it with the job's identifying payload keys (not the whole payload — see gotchas). This gives you a clean per-job-type latency picture across the whole app with very little code.

Keep instrumentation out of domain code where you can. Prefer decorators, middleware, or event listeners over sprinkling span calls through services. It keeps the business logic testable without the monitor installed, and makes it trivial to disable monitoring in a given environment.

CI usage. The Laravel 13 / PHP 8.5 support means you can run a modern matrix; make sure your test environment either disables recording or points at an in-memory/fake store so the suite doesn't write traces on every test.

Gotchas and Tips

• The span limit is a truncation, not a throttle. Once you hit the cap, later spans in that trace are dropped — the first spans survive, not the slowest ones. If the expensive thing happens late in a request, a tight limit will hide exactly what you're looking for. Validate the number against real traces before trusting it.
• Upgrade the two things at once or neither. Laravel 13 support lands alongside PHP 8.5 support in this release. If you're on Laravel 13, you're almost certainly on a PHP version your other packages may not yet support — check the wider dependency tree before pulling this in on a branch you care about.
• Config is cached. php artisan config:cache will freeze your span limit and sampling values. Any change requires a re-cache; a surprising number of "the setting isn't working" reports are this.
• Long-running workers hold old config. Queue workers and Octane keep the container alive. After changing limits, queue:restart (and reload Octane) or you'll see inconsistent behaviour across workers.
• Don't tag spans with raw request/job payloads. You'll bloat storage and leak PII into your traces. Pull out identifiers only.
• Nested spans should mirror your call stack. If you open a span and throw, make sure it still closes — a leaked span can distort the rest of the trace, and with limits now in play a stuck span may consume budget you needed elsewhere.
• The Pest 4 migration is internal, but a signal. If you maintain forks, patches, or your own tests extending the package's test helpers, expect churn in the test setup area. Nothing in it should affect runtime behaviour.
• Debugging "nothing recorded": check, in order — is the monitor enabled for this environment, is the recorder bound, does the storage backend actually exist and is it writable, and (new) have you already exhausted the per-trace span limit before the point you care about.
• Extension point worth knowing: manual span wrapping around a closure is the safest integration; if you need custom data on the trace, layer it via the config/middleware rather than patching the provider, so future minor releases don't break you.
• Pinning: this is a 1.x minor with a genuine feature addition plus new framework/PHP support. Pin to ^1.2 and read the diff if you're on Laravel 13 or PHP 8.5 — those are the combinations most likely to surface the less-travelled paths in a package this size.