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

composer require adelinferaru/nestedflowtracker

Publish and run the migration:

php artisan vendor:publish --tag="flow-migrations"
php artisan migrate

Optionally publish the config:

php artisan vendor:publish --tag="flow-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.

use AdelinFeraru\NestedFlowTracker\Laravel\Facades\Flow;

$account = Flow::span('register user', function () use ($data) {
    $account = Flow::span('create account', fn () => Account::create($data));

    Flow::span('send welcome email', fn () => Mail::to($account)->send(new Welcome()));

    return $account;
});

This records a tree:

register user .................. 142ms
├─ create account .............. 38ms
└─ send welcome email .......... 95ms

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

flow()->span('charge card', fn () => $gateway->charge($card));

app(\AdelinFeraru\NestedFlowTracker\Core\FlowTracker::class)->span(/* ... */);

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.

use AdelinFeraru\NestedFlowTracker\Core\Drivers\PdoDriver;
use AdelinFeraru\NestedFlowTracker\Core\Drivers\PdoSchema;
use AdelinFeraru\NestedFlowTracker\Core\FlowConfig;
use AdelinFeraru\NestedFlowTracker\Core\FlowTracker;

$pdo = new PDO('sqlite:flows.sqlite');
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
PdoSchema::create($pdo);                                    // sqlite / mysql / pgsql

$flow = new FlowTracker(
    new FlowConfig(enabled: true, component: 'orders'),
    $events,                                                // any PSR-14 EventDispatcherInterface
    new PdoDriver($pdo),                                    // or BufferedPdoDriver for one bulk insert per flow
);

$flow->span('checkout', function ($span) use ($flow) {
    $flow->span('charge card', fn () => /* ... */);
});

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:

php examples/plain-php.php

checkout                        66.1 ms
   charge card                     43.1 ms
   reserve stock                   12.6 ms
   send confirmation email         10.0 ms  ⚠ failed

Enriching a span

The open span is passed to your callback:

Flow::span('import csv', function ($span) use ($rows) {
    $span->context = ['rows' => count($rows)];
    $imported = $this->import($rows);
    $span->result = ['imported' => $imported];
    return $imported;
});

Manual spans

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

Flow::start('long running process');
// ...
Flow::end(['result' => ['ok' => true]]);

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:

Http::withFlowTrace()->post('https://orders.internal/checkout', $payload);

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:

use AdelinFeraru\NestedFlowTracker\Core\TraceContext;

if ($ctx = TraceContext::parse($request->header('traceparent'))) {
    Flow::setTraceId($ctx->traceId);
}

Artisan commands

php artisan flow:show {trace}   # print a flow as a tree
php artisan flow:prune --days=30 # delete flow spans older than N days

Events

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

use AdelinFeraru\NestedFlowTracker\Core\Events\SpanFinished;

Event::listen(function (SpanFinished $event) {
    if ($event->span->duration > 1.0) {
        Log::warning("Slow span: {$event->span->name} ({$event->span->duration}s)");
    }
});

Automatic instrumentation

Opt in to record spans with zero manual calls:

FLOW_AUTO_HTTP=true    # a root span per HTTP request (web + api groups)
FLOW_AUTO_QUEUE=true   # a root span per queued job

• 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:

use AdelinFeraru\NestedFlowTracker\Core\Attributes\Trace;

class CheckoutController
{
    #[Trace('checkout')]                  // or #[Trace] to name it after the action
    public function store(Request $request) { /* … */ }
}

#[Trace]                                  // class-level: on a job (or every controller action)
class SendInvoice implements ShouldQueue { /* … */ }

• 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:

FLOW_VIEWER=true

• 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:

use Illuminate\Support\Facades\Gate;

Gate::define('viewFlow', fn ($user) => $user->isAdmin());

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):

GET {path}/api/flows               # recent flows; ?component=, ?status=, ?per_page=, ?page=
GET {path}/api/flows/{trace}       # one flow as a nested span tree

// GET /flow/api/flows/{trace}
{ "trace_id": "…", "spans": [ { "name": "checkout", "status": "ok", "duration": 0.19,
  "children": [ { "name": "charge card", "status": "ok", "duration": 0.08, "children": [] } ] } ] }

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

Storage drivers

Choose where finished spans go with flow.driver:

Driver	Stores spans as	Viewer / flow:*
database (default)	a tree in your database	✅
log	structured log lines (flow.log.channel)	—
null	discarded (API stays on)	—
otel	sent straight to an OTLP collector, no DB	—

FLOW_DRIVER=database   # database | log | null | otel

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.

FLOW_OTEL_ENABLED=true
FLOW_OTEL_ENDPOINT=http://localhost:4318   # spans are sent to {endpoint}/v1/traces

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

Env	Config key	Default	Description
FLOW_ENABLED	flow.enabled	true	Master switch. When off, span() runs your callback transparently and stores nothing.
FLOW_COMPONENT	flow.component	app	Name of this application/service, stored on every span.
FLOW_DRIVER	flow.driver	database	Storage driver: database / log / null / otel.
FLOW_BUFFER	flow.buffer	false	Buffer a flow and bulk-insert on completion (database driver).
FLOW_LOG_CHANNEL	flow.log.channel	null	Log channel for the log driver (null = default).
FLOW_CONNECTION	flow.connection	null	Connection for the flow_spans table (null = default).
FLOW_AUTO_HTTP	flow.auto.http	false	Auto root span per HTTP request.
FLOW_AUTO_QUEUE	flow.auto.queue	false	Auto root span per queued job.
FLOW_ATTRIBUTES	flow.attributes	true	Honor the #[Trace] attribute on actions/jobs.
FLOW_VIEWER	flow.viewer.enabled	false	Register the built-in viewer routes.
FLOW_VIEWER_PATH	flow.viewer.path	flow	URL prefix for the viewer.
FLOW_OTEL_ENABLED	flow.otel.enabled	false	Export completed flows to an OTLP/HTTP collector.
FLOW_OTEL_ENDPOINT	flow.otel.endpoint	null	Collector base URL (spans go to {endpoint}/v1/traces).

Performance

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

php artisan flow:benchmark --flows=300 --spans=5

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

Scenario	µs / span
disabled (flow.enabled=false)	~2
null driver (tracking, no storage)	~60
database driver (immediate)	~1030
database driver (flow.buffer=true)	~125

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

composer test
composer analyse

Credits

• Feraru Ioan Adelin
• All Contributors

License

MIT. Please see the license file for more information.