Beem Php Laravel Package

Technical Evaluation

Architecture fit. v0.1.0 is deliberately framework-agnostic, not a Laravel package. It ships the primitives we care about — transactions, spans, exception capture, DSN handling, and a batching HTTP transport with shutdown flush — but no ServiceProvider, facade, publishable config, or auto-discovery. That is a reasonable vendor sequencing decision (one core for Symfony/Laravel/plain PHP), but it means Laravel fit is currently achieved by us, not by the package. The core domain model (transaction → span, exception capture) maps cleanly onto Laravel's request lifecycle and exception handler, so the conceptual fit is good; the ergonomic fit is absent until a Laravel bridge exists.

Integration feasibility. Feasible in a short spike. Expected work: bind the client as a container singleton, add a config file sourced from env (BEEM_DSN), register a middleware to open/close request transactions, and hook ExceptionHandler::report() for exception capture. The shutdown-flush design means we do not need to hand-wire flushing in the happy path, which removes the most common cause of silently dropped telemetry. Effort is measured in days, not weeks, for a competent Laravel engineer — but it is our code to own and maintain.

Technical risk.

• Pre-1.0 semver. v0.1.0 gives no stability guarantee. Minor bumps may break method signatures. Pin exactly (0.1.* or a commit hash) and treat upgrades as reviewed changes.
• Unproven transport. Batching + shutdown flush is the correct pattern for PHP's shared-nothing model, but reliability characteristics (buffer limits, retry/backoff on 429/5xx, behavior on timeout) are undocumented in the notes. Data loss under load is the primary risk.
• No framework context. No job/queue awareness, no Octane or Horizon awareness, no request-scoped user context out of the box. We would be building correlation IDs ourselves.
• Vendor maturity. Single initial release, unknown maintainer depth, no stated support policy or SLA.
• Secret handling. DSN carries an ingest key; it must land in env/secret manager, never in committed config.

Key questions for the vendor.

1. Roadmap for a first-party Laravel package (auto-discovery, config publish, middleware, Octane/queue support)?
2. Transport guarantees: max buffer size, flush timeout, retry/backoff semantics, behavior on process kill or fatal OOM?
3. Documented PHP and Laravel version support matrix; PSR-3/PSR-18 interoperability?
4. Sampling, PII scrubbing, and before-send hooks — are any present or planned?
5. Support model and deprecation policy leading to 1.0?

Integration Approach

Stack fit. Standard Composer install into an existing Laravel application. Confirm PHP constraint against our runtime (8.1/8.2/8.3 across services) before committing. No infrastructure dependency beyond outbound HTTPS to the ingest endpoint, which should pass existing egress controls.

Migration path. Greenfield — no incumbent to migrate from within this product. The real migration consideration is coexistence: most services already run Telescope (local) and/or an existing error tracker. Running two exception reporters doubles payloads and creates ambiguity about which system is authoritative. Decide up front: run Beem in a single pilot service alongside the incumbent, with a documented cutover/rollback switch, rather than instrumenting broadly on day one.

Compatibility. The shutdown-flush model behaves differently across our execution contexts and each needs explicit verification:

• PHP-FPM — flush at request shutdown; verify latency added to response tail.
• Queue workers (Horizon) — long-lived processes; shutdown fires only on worker recycle. Buffer growth and memory ceiling are the concern.
• Octane — persistent workers, same concern plus state leakage between requests if the client holds request-scoped data.
• CLI/artisan and scheduled tasks — confirm capture works and flush fires reliably.

Sequencing.

1. Spike (1 week): prototype the service provider + middleware in a sandbox service; validate all four execution contexts; measure shutdown latency and payload volume.
2. Internal adapter package: encapsulate the SDK behind a thin first-party package (acme/laravel-beem). This is the single highest-leverage decision — it isolates 0.x churn and makes a future swap or a first-party Laravel release a one-file change.
3. Pilot: one production service, one squad, 2–4 weeks, with success criteria agreed in advance (capture completeness, p95 tail latency impact, cost).
4. Expand: roll out via the adapter; only then consider deprecating the incumbent in that service.
5. Re-evaluate at 1.0 or when a first-party Laravel package ships — whichever comes first.

Operational Impact

Maintenance. We own the integration code, so budget a standing allocation for it. Pin the version, watch the upstream changelog, and schedule a review each minor release. Without an adapter layer, each 0.x bump is a potential app-wide change; with one, it is contained.

Support. No stated support tier makes this a "community/best-effort" dependency until a commercial agreement exists. Escalation path for ingest outages is unclear — which matters because an observability SDK can become an incident if it fails loudly in the request path.

Scaling. Two cost vectors: ingest volume (driven by transaction/span cardinality — apply sampling early, not after the bill arrives) and per-process memory for the batch buffer, which scales with worker lifetime. Long-running Horizon/Octane workers need a configured max buffer size and periodic forced flush; set these at rollout, not reactively.

Failure modes to design against.

• Silent data loss on fatal errors, OOM, or forced process termination — shutdown handlers do not run. Accept this as a known gap and document it; do not promise complete error coverage.
• Blocking network call at shutdown adding tail latency to every request. Set an aggressive flush timeout and verify it is honored.
• Retry storms / 429s from the ingest endpoint during incidents — precisely when volume spikes. Confirm backoff and a drop-on-pressure policy rather than unbounded buffering.
• Instrumentation-induced outage — treat the SDK as non-critical-path: any failure must degrade to no-op, never to an exception.
• Credential exposure if DSN is committed or logged.
• Double-reporting with the incumbent tracker causing alert noise and unclear ownership during incidents.

Ramp-up. Low for day-to-day use — the transaction/span/exception vocabulary is familiar to anyone who has used an APM tool. The genuine ramp-up is convention, not API: what constitutes a transaction, span naming rules, cardinality limits, and which team owns the dashboards. Write a one-page internal standard before the pilot begins, otherwise instrumentation quality will diverge across squads and the data will be hard to compare.