Introduction

Flare allows you to run performance monitoring on your application. This means you can see how long certain parts of your code take to execute.

To do this, we'll follow the Open Telemetry tracing standard. Let's give you a quick introduction:

An application always starts a trace for every request, command or job. A sampler decides whether a trace will be sampled based on the sampling rate and a randomiser. When a trace is sampled, spans will be recorded for the trace. A span is a work unit executed within a trace. A span can have a parent span, which means that the span is executed within the timeframe of another span. A span always has a start and end time. Whenever a time-based event happens within a span (with only a single timestamp and no specific start or end time), then we'll call such an event a span event. Sometimes a trace is distributed over multiple machines/services, think a request triggering a queued job. In such a case, the application sends the trace_id, span_id and sampling decision to the next server/service to continue the trace, we call this propagation.

That's it, you're now a tracing expert!

Enabling performance monitoring

Performance monitoring is enabled by default.

Starting traces

You can start a trace by using the lifecycle:

$flare->lifecycle->start();

Now it's time to run your application and additional spans, more on that later.

When your application exits, you should end the lifecycle as such:

$flare->lifecycle->terminated();

This will close the trace and send it to Flare.

The lifecycle manages trace creation, sampling decisions and flushing data automatically. It also supports distributed tracing via traceparents and subtask-based lifecycles for queue workers. You can read more about the lifecycle here.

Collecting spans & span events

We've got a complete chapter on collecting data for Flare, from queries to logs to external HTTP calls. While it is technically possible to create your own spans and span events, we recommend using the built-in data collectors.

For example, tracing a query is as simple as:

use Spatie\FlareClient\Time\TimeHelper;

$config->collectQueries();

$flare->query()->record(
    sql:'SELECT * FROM users WHERE id = ?',
    duration: TimeHelper::milliseconds(300),
    bindings: [1],
    databaseName: 'Flare',
    driverName: 'mysql'
);

When recording this span, the end time will be the current time, and the start time will be the current time minus the duration.

Notice the TimeHelper? Open telemetry collects the duration in nanoseconds, but PHP can only keep track of milliseconds. The TimeHelper will convert the milliseconds to nanoseconds for you.

We have excellent documentation on traces, spans, span events, and propagation. You can read it here.

Disabling performance monitoring

Sometimes you might not want to enable performance monitoring for your application. This can be done as such:

$config->trace(false);