Download the PHP package adelinferaru/nestedflowtracker without Composer

NestedFlowTracker

adelinferaru.github.io/nestedflowtracker

A zero-infra flow tracer. Wrap any block of code in a span; it gets timed and stored as a tree in your own database, with nested sub-operations recorded as children. A single flow can span multiple applications via a shared trace_id.

No collectors, no external backend — unlike OpenTelemetry you need no infrastructure, and unlike Telescope it traces your business flows (not framework internals) and works in production.

Requires PHP 8.1+. As of 3.0 the package is split into a framework-agnostic Core (only PSR-3/14/17/18 dependencies) and a Laravel adapter (auto-discovered on Laravel 10, 11, 12, or 13; L13 needs PHP 8.3+). Use either side independently.

Installation

Publish and run the migration:

Optionally publish the config:

Upgrading from 2.x

3.0 is namespace-only: behaviour, config keys, env vars, the flow_spans schema and the artisan commands are all unchanged. composer update plus a search-and-replace on imports usually does it. The full namespace table lives in changelog.md. The most common moves:

• AdelinFeraru\NestedFlowTracker\Facades\Flow → …\Laravel\Facades\Flow
• AdelinFeraru\NestedFlowTracker\Models\FlowSpan → …\Laravel\Eloquent\FlowSpan
• AdelinFeraru\NestedFlowTracker\Events\SpanFinished → …\Core\Events\SpanFinished
• AdelinFeraru\NestedFlowTracker\TraceContext → …\Core\TraceContext

Usage

The recommended API is span(): it opens a span, runs your callback, and closes it automatically — even if the callback throws. It returns the callback's value untouched.

This records a tree:

You can also use the flow() helper or resolve the service from the container:

Without Laravel

Construct Core\FlowTracker yourself and drive it directly. Any PSR-3 logger / PSR-14 dispatcher work; the package ships PDO-backed storage drivers, a PSR-18 OTLP exporter, and a null driver.

Other Core drivers: LogDriver(LoggerInterface) (PSR-3), NullDriver, and OtelDriver (wraps the PSR-18/17 Core\Otel\OtelExporter). All implement Core\Drivers\SpanDriver — bring your own if you want a different backend.

A complete runnable round trip — trace a flow (including a failed span), store it in SQLite, read the tree back with plain SQL — lives in examples/plain-php.php:

Enriching a span

The open span is passed to your callback:

Manual spans

When you cannot wrap the work in a closure, open and close spans manually (LIFO — the innermost open span is closed first):

Across applications (W3C Trace Context)

Flows propagate across services via the standard traceparent header (our trace_id is already a 32-hex W3C trace id).

Outbound — add the current trace to an HTTP client call:

Inbound — with flow.auto.http enabled, an incoming traceparent is read automatically and the request's root span continues the upstream trace. Doing it manually:

Artisan commands

Events

SpanStarted and SpanFinished are dispatched as spans open and close, so you can react to them (e.g. log slow spans):

Automatic instrumentation

Opt in to record spans with zero manual calls:

• HTTP: every request gets a root span named like GET users/{id}, with the method, path and response status in its context; it's marked failed on a 5xx response or an exception. Any manual Flow::span() calls during the request automatically nest underneath it.
• Queue: every processed job gets a root span (job: App\Jobs\...); failed jobs are recorded as failed. Each job is an isolated trace.

Both default to off, so installing the package never silently writes spans.

The #[Trace] attribute

Annotate a route action (or a whole controller) or a queued job to wrap it in a span — the attribute is the opt-in, no other code or config:

• Route actions are wrapped via middleware on the web/api groups; with FLOW_AUTO_HTTP on, the action span nests under the request's root span. 5xx responses mark the span failed.
• Queued jobs with the attribute are traced even when FLOW_AUTO_QUEUE is off — per-job opt-in instead of all-jobs. Failed jobs record the exception.
• PHP attributes are metadata, not decorators — there's no engine-level interception, so the attribute works where the package owns the call site (actions and jobs). For arbitrary service methods, wrap with Flow::span().
• Detection costs one cached reflection lookup per request/job. Kill switch: FLOW_ATTRIBUTES=false.

Viewer

A small built-in UI to browse recorded flows as timed trees — no build step, no assets to compile. Enable it and visit /flow:

• Index (/flow) — recent flows with their component, status and duration; filter by component/status.
• Detail (/flow/{trace}) — the flow rendered as a collapsible tree with duration bars and failed spans highlighted.

Access control: the viewer is reachable automatically in the local environment. In any other environment you must define a viewFlow gate to grant access:

Publish the views to customize them: php artisan vendor:publish --tag="flow-views".

JSON API

The viewer also exposes a read API (same enable flag + viewFlow gate):

For token-based/stateless API clients, set flow.viewer.middleware to ['api'].

Storage drivers

Choose where finished spans go with flow.driver:

The viewer, the artisan commands, and the flow.otel export below are database-only features (they read from the flow_spans table). The log, null, and otel drivers are emit-only.

OpenTelemetry export

Already running an OpenTelemetry Collector, Jaeger, or Grafana Tempo? Ship completed flows there too — no OTel SDK required, we just POST OTLP-JSON. When a flow's root span closes, the whole trace is exported on a queue.

This is the database path: spans are stored and exported. If you don't want to store them at all, use the otel storage driver above (FLOW_DRIVER=otel), which sends spans straight to the collector with no database.

Upgrading from an earlier 2.x? Re-publish and run migrations after upgrading: php artisan vendor:publish --tag="flow-migrations" && php artisan migrate. Run a queue worker so exports happen off the request.

Configuration

Performance

Tracking costs nothing when off and little when on — measure it for your setup:

Indicative per-span overhead (300 flows × 6 spans, in-memory SQLite — your database and hardware will differ, the database figure especially):

The immediate database cost is dominated by the two writes per span. Buffered mode (FLOW_BUFFER=true) holds a whole flow in memory and bulk-inserts it in a single query when the flow completes — roughly 8× faster here. The trade-off: spans are only persisted once the flow completes (a crash mid-flow loses it), so it's off by default. flow_spans is indexed on trace_id, span_id, component, status, and created_at.

Testing

Credits

• Feraru Ioan Adelin
• All Contributors

License

MIT. Please see the license file for more information.