Inspector Php Laravel Package

Technical Evaluation

Architecture Fit

• Shape of the solution: inspector-apm/inspector-php is a pure-PHP SDK (no daemon, no extension, no sidecar). It creates a Configuration + Inspector object, opens a transaction per execution cycle, and nests segments via addSegment(callable, label). That maps cleanly onto Laravel's request lifecycle, queued jobs, artisan commands, and scheduled tasks — the four execution contexts our TPM roadmap usually has to cover.
• Instrumentation model: manual/code-level tracing plus (per the ecosystem) Laravel middleware for automatic request capture. This is a good fit for a Laravel monolith or a small set of Laravel services; it is a weaker fit if the platform strategy is polyglot microservices, because the trace model stops at the PHP boundary unless we bridge to OpenTelemetry ourselves.
• Async/concurrency: The fork() scope primitive (v3.17.0) is the technically interesting differentiator. It gives each concurrent task its own segment stack, so Fibers / ReactPHP / Amp / pcntl_fork workers keep correct parent-child relationships instead of corrupting a shared stack. For teams running queue workers and event loops, this removes a real class of "the trace is a lie" bugs that plague naive APM integrations.
• Error capture: registerGlobalHandler() (v3.16.7) auto-registers with PHP's global exception handler — low-effort coverage of unhandled exceptions, but it is a process-global side effect that needs to be reasoned about in apps that already install their own handlers (Laravel's Handler, Sentry, etc.).
• Extensibility: TransportInterface + setTransport(callable) is the escape hatch that matters to a TPM. It means we are not hard-locked to Inspector's ingest endpoint; we can route data elsewhere (or no-op in tests/CI) without forking the library. That is the difference between "vendor decision" and "architecture decision."
• Strategic direction signal: Recent releases ("Support Neuron 4", "Neuron AI Observer") plus MCP/agentic integration docs show the vendor is pivoting toward AI/agent observability, not just classic APM. Good for future relevance; a risk if it distracts from core PHP APM stability.

Integration Feasibility

• Effort: Genuinely small for a first slice. composer require, instantiate with an ingestion key, wrap the hot path or add the middleware. A single service can be producing traces in under a day; a credible pilot with dashboards and alerts is a 1–2 week effort for one engineer.
• Constraints to confirm before committing:
  • PHP >= 8.1 — fine for Laravel 10/11, but blocks any legacy service still on 8.0 or below. This alone can shrink the addressable scope.
  • Ingestion key + outbound HTTPS to the Inspector cloud — a network/egress review item in regulated or locked-down environments. Self-hosting is referenced as possible but is not documented in this package's README, so treat it as unvalidated until proven.
  • Overlap with existing observability — if Sentry, Telescope, or an OTel collector is already installed, we must decide who owns exceptions and spans, or we double-pay and double-alert.
• Data/privacy: Segment labels and transaction names are developer-authored, so PII leakage risk is mostly a naming-discipline problem, not a library problem. Still worth a written convention (no user IDs, no email, no query parameters in transaction names).

Technical Risk

• Adoption risk (highest): 34 GitHub stars and 0 dependents is a thin public signal. This is a commercial vendor's open-source client (MIT), so the license is safe, but the community depth is not. Our bus factor is effectively "the vendor stays in business and keeps shipping."
• Version/metadata anomaly: The listed last-release date (2026-09-30) is in the future relative to normal release cadence. Either a metadata artifact or a scheduled/mislabeled release — verify against Packagist before relying on it for a currency or supportability claim.
• Blast radius of instrumentation: Tracing code sits inline in request paths. A thrown exception inside a segment callback, or a transport that blocks on cURL at flush time, can degrade the very latency we're trying to measure. Mitigation: wrap in try/catch, set timeouts, and prefer async/batched flush.
• Global handler collision: registerGlobalHandler() can fight with existing error handlers. Needs explicit ordering and a rollback plan.
• Vendor-hosted dashboard dependency: The SDK is MIT, but the value is in the SaaS. "No vendor lock-in" is only half true — the data model and UI are proprietary; only the agent is open.
• Ecosystem drift: No native OpenTelemetry export documented here. If the org standardizes on OTel later, this becomes a migration, not a config change.

Key Questions

1. Scope: Is this for one Laravel service as a pilot, or is it intended as the platform-wide APM standard? The answer changes the vendor-risk calculus entirely.
2. Complement or replace: Does Inspector replace an existing tool (cost saving) or sit alongside one (added complexity)? Who owns the overlap decision?
3. Data governance: Are we permitted to ship request metadata to a third-party SaaS? If not, is self-hosting actually supported and documented, or is that marketing?
4. Commercial terms: What is the pricing model at our projected event/span volume, and what happens on overage? What's the exit cost if we leave in 12 months?
5. Support expectation: What response time does the vendor commit to for SDK bugs? Is there a paid support tier, and who on our side is the named owner?
6. Exit path: If we needed to leave in one quarter, is the TransportInterface sufficient to redirect to an internal collector, or does the segment/transaction model assume Inspector semantics?

Integration Approach

Stack Fit

• Best fit: Laravel 10/11 on PHP 8.1+, monolithic or a modest number of services, synchronous HTTP + queue workers, teams already comfortable with the idea of spans/segments.
• Acceptable fit: Lumen/Slim/plain PHP services where we hand-place startTransaction and addSegment. More work, same model.
• Poor fit: Polyglot estates requiring a single cross-language trace, air-gapped environments, or teams with no tracing literacy (they will instrument nothing and the dashboard will be empty).
• Adjacent capabilities to check before assuming: whether the official Laravel integration package (separate from this one) is what we actually install, versus wiring this SDK manually. That choice belongs in the ADR, not in a developer's composer.json.

Migration Path

1. Baseline first (no code change): capture current p50/p95/p99 latency, error rate, and queue depth from existing logs/metrics for the pilot service. Without a baseline, the pilot produces anecdotes, not evidence.
2. Shadow mode: install the SDK in the pilot service with a short-lived ingestion key, run it in staging for one week. Goal is to prove overhead (~1–3% is the vendor claim — measure it) and validate that traces are actually legible to engineers.
3. Production, one endpoint or one job class: narrow blast radius. Add the global handler only after we've confirmed no collision with Laravel's existing handler.
4. Expand to the full service, then decide on a second service based on a written go/no-go.
5. Exit rehearsal: prove the TransportInterface swap works by pointing at a no-op or internal sink in CI. If we can't do it in an afternoon, we don't have an exit and the "MIT, no lock-in" argument is hollow.

Compatibility

• Pin the major version; this library ships frequently (3.16.x → 3.19.1 within a short window) and minor bumps have included behavioral changes (registerGlobalHandler, fork scopes).
• Validate against: Laravel version, PHP version, existing error handler (Laravel Handler, Sentry), existing tracing (Telescope, OTel), HTTP client instrumentation, and queue driver.
• Confirm PHP-CLI path explicitly — queue workers and scheduled commands are often where the value is highest and where integration is most often forgotten.

Sequencing (TPM view)

The critical sequencing rule: dashboards and alerts must be defined before production rollout, otherwise the pilot ends with pretty charts nobody watches and we've spent the budget for zero decisions.

Operational Impact

Maintenance

• Low carrying cost, non-zero: SDK upgrades are composer update plus a regression pass on the pilot service. Budget roughly a half-day per quarter for version currency, more if we adopt new features (fork scopes, global handler).
• Ownership must be named: someone owns the ingestion key, the alert thresholds, and the "why is the dashboard empty" question. Unowned observability decays into noise within two quarters.
• Instrumentation rot: segment labels written ad hoc become inconsistent (db, Database, db-query). Enforce a naming convention early, or the data becomes unqueryable at exactly the moment you need it.

Support

• Vendor support tier is unknown from the README — this is a procurement question, not a technical one, and it should be answered before production, not after the first outage.
• Community support is thin (34 stars, 0 dependents). Escalation path is the vendor's own channels, not Stack Overflow. That's acceptable for a low-criticality nice-to-have; riskier if we intend to page on Inspector alerts.
• Internal support surface: anyone who can edit addSegment calls can break trace continuity. Document the convention and keep instrumentation in a thin, reviewable layer rather than sprinkled through business logic.

Scaling

• Request-path overhead scales linearly with span count per request. A few dozen segments per request is fine; instrumenting every Eloquent query in a 200-query endpoint is not. Set a per-request span budget and enforce it.
• Ingestion volume is a cost lever, and it is the lever most likely to surprise us. High-traffic endpoints can be sampled or excluded; decide the sampling policy at rollout, not after the first invoice.
• Flush behavior under load: synchronous HTTP flush at the end of each transaction is the classic tail-latency amplifier. Verify the transport batches, and if not, use setTransport to build one that does. This is the single most important pre-production check for high-QPS services.
• Queue workers: long-lived processes are where memory leaks and unbounded queues surface. Confirm that per-job transactions are properly closed and that a worker crash doesn't silently drop the whole batch.
• Ceiling: at genuinely high RPS (tens of thousands), evaluate whether this or a sampling-first APM is the right tool. It is not built to be a 100K RPS solution.

Failure Modes

The recurring theme: every failure mode should be fail-open. Observability must never be able to take down the thing it observes. If the design can't guarantee that, the pilot isn't ready for production.

Ramp-Up

• Engineers: ~1 hour to first trace, ~1 day to be genuinely productive (understanding transactions vs. segments, where to place them). The README examples are sufficient for a first slice; the vendor docs carry the rest.
• The real ramp is conceptual, not technical: teams that don't think in spans will instrument randomly and get noise. Budget a 45-minute internal walkthrough plus a short written convention doc ("here is when you add a segment; here is when you don't").
• On-call/SRE: half a day to learn the dashboard, alert tuning, and — critically — what to do when data stops arriving. Add a runbook entry for "Inspector shows no data."
• The MCP/agentic integration is a genuine onboarding accelerant for developers already using Claude Code/Cursor/VS Code assistants — worth trialing with one or two engineers and measuring whether it actually shortens time-to-first-useful-trace.
• Realistic total ramp: two engineer-days for the pilot service including documentation. Anything beyond that suggests the team lacks observability fundamentals and should start with Laravel Telescope/Debugbar first — adopting APM before that literacy exists produces cost without insight.