Scout Apm Symfony Bundle Laravel Package

Technical Evaluation

Architecture fit. This repository is scoutapp/scout-apm-symfony-bundle — a Symfony bundle, not a Laravel package. A TPM must flag this before scoping any Laravel work: the artifact does not drop into a Laravel app. What does transfer is the underlying instrumentation API (ScoutApm\Agent) and the operational model, both of which the sibling package scoutapp/scout-apm-laravel wraps. Treat this repo as the reference implementation for "how Scout wires into a PHP framework's container, kernel, and console" — useful for review and comparison, but the integration surface for Laravel is the Laravel package plus the Scout PHP agent (a downloaded binary, not a Composer dependency).

Integration feasibility. The Symfony-side work is genuinely low-touch: register the bundle, add a scout_apm.yaml config block, set SCOUT_KEY, SCOUT_NAME, SCOUT_MONITOR. For Laravel, the analogous path is service-provider auto-discovery plus env vars — no custom middleware required. The real feasibility question is not code but environment: the agent binary must be downloadable and writable at runtime, which is the dominant failure mode in containerized PHP.

Technical risk. Three risks matter to a TPM:

1. Silent no-op degradation. Missing key, monitor=false, or an unreachable agent all fail open — the app runs, telemetry is zero, nothing throws. Mitigation is a staging smoke test asserting a transaction was recorded, plus agent-log inspection (SCOUT_LOG_LOCATION), never dashboard silence.
2. Build matrix ≠ Composer constraint. 1.2.0 adds PHP 8.3 to CI; that is evidence the suite is green on 8.3, not proof composer.json permits 8.3. Check the constraint before bumping platform.php anywhere.
3. Long-running process state. Under Octane/FrankenPHP/queue workers, an unstopped transaction bleeds into the next unit of work, misattributing traces. try/finally around Agent::instrument() is non-negotiable.

Key questions. Is the target service Symfony or Laravel (determines the artifact)? Have we committed to Scout as a vendor, or is this a trial? What's the per-host cost envelope and expected trace volume? Who owns the agent-binary build step in CI? Do we need vendor-neutral OTel instead?

Integration Approach

Stack fit. For a Symfony service, this bundle is the correct artifact and the integration is a config exercise. For a Laravel service, use scoutapp/scout-apm-laravel; do not spike this bundle. Mixed shops should standardize SCOUT_NAME conventions (<app>-<env>) and inject SCOUT_REVISION_SHA from CI so cross-service traces line up.

Migration path. Low ceremony. The 1.2.0 diff is two PRs, both tooling (PHP 8.3 in matrix, release automation) — zero functional, config, or API changes, no deprecations. That makes it a drop-in minor bump. Pin ^1.2 and let minors flow through staging first, primarily to catch agent-binary compatibility drift rather than PHP breakage.

Compatibility. Validate three things independently: the package's php constraint against your runtime, the Symfony major against the bundle's supported range, and the agent binary's compatibility with your PHP build. The release notes give you confidence on the third only by implication.

Sequencing. (1) Confirm framework/vendor decision. (2) Bake or pre-download the agent in the image build; point its path at writable storage. (3) Wire env vars and config. (4) Enable framework auto-instrumentation (Doctrine, HTTP client, Twig) as baseline. (5) Add ignore rules for health checks, probes, asset routes, and metrics scrapers next to route definitions. (6) Hand-instrument only the gaps — queued jobs, webhook handlers, report generators — wrapping with instrument() and deterministic stop(). (7) Add a staging smoke test asserting a recorded transaction.

Operational Impact

Maintenance. Low. Release automation landed in 1.2.0, so patch releases should be predictable; consuming them is a routine dependency bump. The maintenance burden concentrates in the agent binary (image rebuilds, version pinning), not this repo.

Support. Scout APM is commercial SaaS. Support relationship, SLA, and pricing are vendor-level, not package-level. This bundle has 2 stars and a single contributor on the 1.2.0 PRs — it is thin glue maintained as part of a commercial product, not a community project. Do not evaluate it as OSS you might fork.

Scaling. Overhead scales with span count, not request count. Instrumenting a hot loop or an ORM accessor called thousands of times per request shows up in p50. Prefer service decorators and middleware — wrap at boundaries, not leaves. Cost also scales with hosts and trace volume, so ignore-list discipline is a budget control, not just a hygiene item.

Failure modes. Silent no-op (most common); read-only filesystem or no network at runtime blocking the binary; dangling transactions in workers; misconfigured app name making staging spikes look like production incidents; no-op on unsupported PHP/Symfony combinations. All of these look like "no data," not errors — build the detection into staging.

Ramp-up. Fast for a PHP developer: one custom Agent::instrument() exercise on a non-controller code path teaches the transaction model that context, naming, and ignoring all build on. Roughly a day to first useful trace, a sprint to sensible ignore rules and job instrumentation. The Laravel learning curve is the same shape — the API is shared; only the registration mechanics differ. Budget separate time for the agent-in-container work, which is the part that actually delays first data.