Traceview Bundle Laravel Package

Getting Started

The single most important thing to internalize: this package is not the monitoring product, and it is not a Laravel package. It is ~30–60 lines of Symfony2 event-subscriber glue that decorates transactions opened by the native traceview PHP agent (the Oboe-based PECL extension). All real instrumentation lives in the extension; the bundle only adds framework-aware naming so transactions show up as App\Http\Controllers\OrderController::show instead of index.php.

For a Laravel developer, "getting started" means extracting the pattern, not installing the artifact:

1. Verify the agent exists for your runtime before anything else. The bundle is inert without it. Confirm the PECL extension builds for your PHP version (8.2/8.3 under FPM and Octane), then php -m | grep traceview. If there is no supported build, stop — no amount of middleware will help.
2. Read the bundle's listener first. It is the entire spec for what you are about to reimplement: subscribe to kernel.request, open/name the transaction from the route/controller, subscribe to kernel.response, close it. Port that mental model to middleware.
3. Do not composer require appneta/traceview-bundle. It is a Symfony Bundle registered in AppKernel, requires symfony/framework-bundle 2.x, and will not boot or even resolve inside a Laravel app.
4. First use case: wrap one route and confirm a named transaction lands in TraceView. Register a global middleware that opens a transaction, names it after $request->route()?->getName() (falling back to the URI pattern, not the raw URI), and closes it in a finally.

Implementation Patterns

Service provider + singleton. Bind a thin tracer wrapper in a service provider, but make the binding conditional on extension_loaded('traceview') so the app boots cleanly on machines without the agent. Guard every extension call behind that check, or use a null-object tracer. This keeps local/dev/CI functional and avoids fatals.

Global middleware, try/finally. The core pattern mirrors the bundle's subscriber:

public function handle($request, Closure $next)
{
    $this->tracer->start($request);
    try {
        return $next($request);
    } finally {
        $this->tracer->setStatus($response->getStatusCode() ?? 500);
        $this->tracer->finish();
    }
}

The finally matters — the Symfony subscriber gets the same behavior from kernel.exception, but in Laravel a thrown exception skips the response path entirely, so without finally a failed request leaves an open transaction and a broken trace.

Register after session/auth. Place the middleware after StartSession and any authentication middleware so you can tag user_id and tenant from the resolved user, which is the whole point of route-aware naming. Placing it first gives you latency numbers but no attribution.

Exception reporting. Hook bootstrap/app.php's withExceptions (Laravel 11) or Exceptions\Handler::report() to mark the active transaction errored and attach the exception class. This is the Laravel equivalent of the bundle's kernel.exception listener.

Job and command listeners. This is where the bundle gives you nothing — it only hooks the HTTP kernel. Queue workloads need separate JobProcessing/JobProcessed/JobFailed listeners (and a console hook for artisan commands), each opening and closing its own transaction. If you skip this, your async traffic is invisible and your traces are half-true.

Noise and cost control. Exclude /health, /horizon, /telescope, and artisan bootstrapping from tracing, and lean on agent-side sampling. These are your primary levers for both cost (TraceView prices per host/agent) and dashboard signal-to-noise. The bundle offers neither; you build it explicitly.

Gotchas and Tips

• The worst failure mode is silent. If the extension is missing, version-mismatched, or the collector is unreachable, the app boots fine and traces just vanish — which reads as "no traffic" on the dashboard, not "instrumentation broken." Add a startup check or a canary transaction and alert on its absence.
• Octane and long-lived workers leak transaction state. The agent was designed for per-request FPM workers; under Octane or a persistent worker, an unclosed or global transaction can bleed into the next request and misattribute traces. Ensure every code path closes the transaction, and test under a persistent server before rollout.
• Naming matters more than span count. Use traceview_set_transaction_name() (via the extension) with the route name or controller action, never the raw URI — otherwise every /orders/12345 becomes a distinct transaction and your aggregates are useless.
• Watch PII leaving the network. URLs, query strings, and auth headers can end up in trace payloads. Decide explicitly what is tagged before this goes anywhere near production, and coordinate with whoever owns the vendor contract.
• Don't fight Composer. Any attempt to install the bundle alongside modern symfony/* constraints fails at resolve time. Treat the repository as documentation, not a dependency.
• Plan the exit. TraceView is an end-of-life AppNeta/Broadcom line, and this package has no stars, no dependents, and no release cadence. The middleware surface you write is small — keep it vendor-neutral in shape (a start/tag/finish interface) so swapping to OpenTelemetry's PHP SDK later is a config change, not a re-instrumentation project. If TraceView is not already a mandated, contracted vendor, invest this same day of work in OpenTelemetry instead and keep the observability decision reversible.
• Revisit worker sizing. The agent is per-process: under FPM you pay initialization and memory per worker, and horizontal autoscaling multiplies per-host cost linearly. Surface that before a Kubernetes rollout, not on the first invoice.