Application lifecycle

The Lifecycle class tells Flare when your application starts, registers, boots, runs, and terminates. Wiring it up is required for traces to be created, sampled, and flushed correctly. It is always active and cannot be disabled.

There are two modes of operation:

• Normal lifecycle: For typical HTTP requests or CLI commands that run from start to finish.
• Subtask lifecycle: For queue workers or long-running processes where a single process handles multiple tasks.

Normal lifecycle

A normal lifecycle tracks the full application run: starting, registering services, booting, running, and terminating.

Every application starts with the initialisation:

$flare->lifecycle->start();

If your application is part of a distributed system, you can pass a traceparent to continue an existing trace. A traceparent is a string defined by the W3C Trace Context specification (e.g. 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01) that carries a trace ID, parent span ID and sampling decision across service boundaries:

$flare->lifecycle->start(traceparent: $traceparent);

For each lifecycle event, you can also define an additional time when the event happened:

use Carbon\CarbonImmutable;
use Spatie\FlareClient\Time\TimeHelper;

$flare->lifecycle->start(
    timeUnixNano: TimeHelper::dateTimeToNano(CarbonImmutable::now()),
);

And add extra attributes to the event:

$flare->lifecycle->start(attributes: [
    'framework.version' => '12'
]);

When your application registers services in the container, you can keep track of it as follows:

$flare->lifecycle->register();

// Register services within the container

$flare->lifecycle->registered();

Next up, when your application is booting, you can keep track of it as such:

$flare->lifecycle->boot();

// Boot your application

$flare->lifecycle->booted();

Now it's time to run your application. Use the regular recorder methods to keep track of requests, jobs, commands, queries, and so on. See the requests, console commands, jobs and queues, and queries pages for details.

use Spatie\FlareClient\Time\TimeHelper;

$flare->request()->recordStartFromGlobals();

$flare->query()->record(
    sql: 'select * from users',
    duration: TimeHelper::milliseconds(300),
    bindings: ['id' => 1],
);

$flare->request()->recordEndFromDefined(statusCode: 200);

In the end, when your application runs and starts terminating, you can keep track of it as follows:

$flare->lifecycle->terminating();

// Terminate your application

$flare->lifecycle->terminated();

Calling terminated() ends the trace and flushes the collected data to Flare. See Flushing for details.

Subtask lifecycle

For queue workers or long-running HTTP processes, booting and registration aren't relevant for each individual task. Instead, you start and end subtasks, where each subtask gets its own trace:

// Process incoming tasks in a loop
while ($task = $queue->pop()) {
    $flare->lifecycle->startSubtask();

    // Process the task

    $flare->lifecycle->endSubtask();
}

When propagating traces from another service, you can pass the traceparent:

$flare->lifecycle->startSubtask(traceparent: $traceparent);

// Process the task

$flare->lifecycle->endSubtask();

Calling endSubtask() ends the subtask's trace and flushes its data to Flare. See Flushing for details.

Flushing

Flushing sends collected traces, spans, and logs to Flare. The lifecycle handles this automatically at the end of each run, so you don't need to call it yourself in most cases.

Flushing happens automatically when:

• terminated() is called at the end of a normal lifecycle.
• endSubtask() is called at the end of a subtask.
• The PHP process shuts down. The lifecycle registers a shutdown function in start() that flushes any data still in the queue. This is a safety net for cases where terminated() is never reached (for example, a fatal error or an early exit()).