Scout Apm Laravel Laravel Package

Getting Started

Scout APM is Laravel-side instrumentation for the Scout monitoring service — you install it, set three env vars, and it starts reporting request, query, and job performance to the Scout dashboard with no code changes.

Minimal setup:

1. composer require scoutapp/scout-apm-laravel (2.5.0 is current; its only change is a widened Composer constraint so illuminate/* v11 is now allowed — see Gotchas).
2. Set the identifying env vars per environment:

SCOUT_KEY=your_agent_key
SCOUT_NAME=my-laravel-app
SCOUT_MONITOR=true

3. Publish the config if you need to change defaults (the README lists the current publish provider/tag for config/scout_apm.php — check it rather than guessing, since this package and Laravel Scout both use a scout prefix).
4. Deploy to staging, hit a few endpoints, and confirm transactions appear in the Scout UI within a minute or two.

Where to look first:

• config/scout_apm.php (once published) — this is the whole surface area: key/name/monitor toggles, log level, error and queue collection, ignored paths, and URI reporting.
• The Scout dashboard's endpoint list — sort by 95th percentile, not average. The first useful thing this package buys you is "which endpoint is slow," and the answer is rarely the one you'd guess.
• The transaction breakdown for your slowest endpoint — it separates time spent in queries vs. views vs. other layers, which tells you whether to reach for the query log or the profiler.

First concrete use case: install in staging only, find your worst-performing authenticated endpoint, and fix the N+1 the breakdown will almost certainly reveal.

Implementation Patterns

Environment-gated monitoring. The standard pattern is SCOUT_MONITOR=true in staging and production, false locally and in CI. Local monitoring pollutes your account with noise and adds pointless overhead to test runs. Since it's env-driven, keep it out of committed .env files and set it in your deploy platform's config.

Start with auto-instrumentation, add manual instrumentation second. The package hooks Laravel's request lifecycle, query events, and (if enabled) queue jobs automatically. Resist writing custom instrumentation until the dashboard shows a gap — e.g. a transaction spending a large chunk of time in "other," or a service class that hides three slow calls behind one method.

Custom instrumentation for opaque code paths. Wrap meaningful units of work so they show up as named segments rather than anonymous time:

$report = ScoutApm::instrument('Build monthly report', function () use ($tenant) {
    return $this->reports->build($tenant);
});

Use this for report generation, third-party API calls, PDF rendering, and anything else that dominates a request but isn't a query or a view.

Tag multi-tenant or variant traffic. If the same route behaves differently per tenant, plan, or feature flag, attach context so you can tell the slow 5% from the fast 95%. Without this, a single bad tenant makes an endpoint look uniformly mediocre.

Queue workers are a separate mental model. Enable queue instrumentation and expect jobs to appear as their own transaction type. This is where long-running workers, retries, and memory growth show up — issues that never surface in the web transaction view. Restart workers after config changes (see Gotchas).

Correlate deploys with performance. Feed deploy markers into Scout as part of your release pipeline. The single highest-value habit with any APM is checking, after each deploy, whether p95 moved — and it's only possible if deploys are marked.

Ignore the noise deliberately. Health checks, /up, horizon dashboards, and asset routes will dominate your endpoint counts and drown out real traffic. Add them to the ignore configuration rather than learning to scroll past them.

Gotchas and Tips

2.5.0 is a compatibility release, not a feature release. The one change widens the Composer constraint to include Laravel 11. Practical implications:

• If you'd pinned illuminate/* below v11 solely because this package blocked the upgrade, you can drop that pin.
• If you were on a fork, dev branch, or a composer.json patch just to run on Laravel 11, revert to the tagged release — those workarounds rot.
• It does not add new monitoring features. Don't go looking for a changelog entry that isn't there.
• Verify with composer why-not scoutapp/scout-apm-laravel after upgrading; other packages may still hold you back on L11 and give you a false sense that this one is at fault.

Config caching bites. Env vars are read through Laravel's config system. If you change SCOUT_MONITOR or SCOUT_KEY on a server running config:cache, nothing happens until you re-cache. Deploy scripts that cache config before injecting env vars produce a silently inert agent.

Octane and long-running workers need restarts. Config and agent state are resolved at boot. octane:reload / worker restarts are required after changes — otherwise you'll debug a "broken" agent that's actually running yesterday's config.

Silent failure is by design. The agent is built not to take down your app, so a bad key, blocked outbound HTTPS, or a DNS problem manifests as no data rather than an exception. When transactions are missing, check in this order: SCOUT_MONITOR is truthy, the key is valid for the named app, the host can reach Scout's collector over HTTPS, and the request isn't matched by an ignore rule.

Raise the log level only while debugging. SCOUT_LOG_LEVEL=debug is how you diagnose a missing agent, but leaving it on floods your logs. Turn it back down.

URI reporting and sensitive query strings. Depending on how URI reporting is configured, query parameters can end up in Scout. If your URLs carry tokens, emails, or IDs, review this setting before enabling in production — it's a data-handling question, not just a noise question.

Avoid high-cardinality instrumentation names. ScoutApm::instrument("Fetch user {$id}") creates one metric per user. Use a stable name and attach the ID as context instead.

Don't confuse this with Laravel Scout. Different package, different purpose (search indexing), overlapping artisan prefix. When following docs or Stack Overflow answers, confirm you're reading the APM package — the naming collision wastes real time.

Watch the overhead trade-off on hot paths. Overhead is typically modest, but if you're monitoring a very high-throughput service, measure rather than assume. Sampling and selective instrumentation of only the endpoints that matter are legitimate levers.