Sampling

Sending every trace your application produces gets expensive fast and rarely tells you anything new. Sampling lets you keep a representative slice of traffic and drop the rest. When a trace is dropped, no spans are collected or sent for it.

A sampled trace is not free. Recording spans, capturing query bindings, gathering request and response data, and serialising the trace before it is shipped all add overhead to the request, command, or job that produced it. We work hard to keep this overhead as small as possible, and unsampled traces stop almost all of the work before it starts, but on hot paths the difference between a sampled and an unsampled trace is still measurable. Picking a sample rate is therefore a trade-off between coverage and runtime cost.

Setting a sample rate

The simplest setup is a single rate that applies to every trace. The default is 10%. Change it with sampleRate():

$config->sampleRate(0.5); // 50% of all traces will be sent to Flare
$config->sampleRate(1.0); // 100%

For full-on or full-off, use the convenience helpers:

$config->alwaysSampleTraces();
$config->neverSampleTraces();

Sampling per kind of work

When you want more control than a single uniform rate, Flare can apply different rates to different kinds of work. Health checks can be sampled rarely, checkout flows aggressively, and noisy queue jobs can follow their own logic. Configure it with sampleTracesDynamic() and a list of rules:

use Spatie\FlareClient\Sampling\SamplingRule;

$config->sampleTracesDynamic(0.1, [
    SamplingRule::forPath('/health-check', 0.0),
    SamplingRule::forPath('/admin/*', 1.0),
    SamplingRule::forRoute('checkout.*', 1.0),
    SamplingRule::forCommand('horizon:work', 0.0),
    SamplingRule::forJob('App\\Jobs\\ProcessPayment', 1.0),
]);

The first argument is the base rate, used when no rule matches. Rules are evaluated in order, and the first one that matches wins.

Rule types

forRoute waits for routing middleware to match a route. forCommand waits for the command class to be resolved. usingDeferred waits for the same handler resolution before invoking its closure. Every other rule type runs the moment the request, job, or command starts. Flare aims to make the sampling decision as early as possible. See Deferred sampling for details.

Pattern syntax

Patterns are literal strings with * as a wildcard. Any other character is matched literally. There is no support for ?, character classes, or full regex.

SamplingRule::forPath('/api/*', 0.1);          // matches /api/users, /api/orders/123
SamplingRule::forJob('App\\Jobs\\*Email', 1.0); // matches SendWelcomeEmail, SendInvoiceEmail
SamplingRule::forCommand('horizon:*', 0.0);    // matches horizon:work, horizon:status

Closure rules

When a pattern is not expressive enough, use a closure:

SamplingRule::usingDeferred(function (EntryPoint $entryPoint) {
    if ($entryPoint->handlerName === LongRunningReportJob::class) {
        return 1.0;
    }

    return null; // No opinion: fall through to the next rule
});

The closure receives the EntryPoint and returns either a rate (0.0 to 1.0) or null to defer the decision to the next rule.

SamplingRule::using() is evaluated when the request, job, or command starts, so the entry point will not have a resolved handler yet. Use SamplingRule::usingDeferred() when you need to decide based on the route, command, or job class, and want to wait for the framework to resolve it.

Deferred sampling

Some rules cannot run when the trace starts. A web framework only knows the matched route after routing middleware runs, and a queue worker may only know the job class after it pulls the payload off the queue.

When a rule needs information that has not been resolved yet, the sampler defers its decision. The trace is sampled tentatively (so spans are still collected), and the sampler is re-evaluated as soon as the framework resolves the handler. The recorders trigger that re-evaluation automatically:

• The routing recorder calls re-evaluation in recordRoutingEnd, so forRoute rules can fire as soon as the route is known.
• The command recorder re-evaluates in recordStart, once the command class is set.
• The job recorder re-evaluates in recordStart (subtask mode only), once the job class is set.

If the sampler decides to drop the trace at re-evaluation time, the spans collected so far are discarded.

Custom rules

For reusable logic, write your own rule class. Extend SamplingRule, declare which entry-point types the rule applies to, and return a rate from getMatchedRate. Add the DeferredSamplerRule marker if your rule depends on the resolved handler.

use Spatie\FlareClient\Enums\EntryPointType;
use Spatie\FlareClient\EntryPoint\EntryPoint;
use Spatie\FlareClient\Sampling\DeferredSamplerRule;
use Spatie\FlareClient\Sampling\SamplingRule;

class AdminControllerRule extends SamplingRule implements DeferredSamplerRule
{
    public function __construct(
        protected string $pattern,
        protected float $rate,
    ) {
    }

    public function appliesTo(EntryPointType $entryPointType): bool
    {
        return $entryPointType === EntryPointType::Web;
    }

    public function getMatchedRate(EntryPoint $entryPoint): ?float
    {
        return str_starts_with($entryPoint->handlerName ?? '', $this->pattern)
            ? $this->rate
            : null;
    }
}

Pass instances to sampleTracesDynamic() alongside the built-in rules:

$config->sampleTracesDynamic(0.1, [
    new AdminControllerRule('App\\Http\\Controllers\\Admin\\', 1.0),
    SamplingRule::forPath('/health-check', 0.0),
]);

Continuing traces from upstream services

When a request reaches your application with a W3C traceparent header (or a job carries one in its payload), Flare extracts the traceId and parent span id so the trace stays connected to the upstream service. The sampler still decides whether the trace is recorded, and it now receives the upstream's sampling decision as a hint.

Each built-in sampler handles that hint differently:

• AlwaysSampler and NeverSampler ignore it (their name is the contract).
• RateSampler honors the upstream decision when present, otherwise it applies the configured rate. This keeps a continued trace consistent with its parent.
• DynamicSampler evaluates its rules first. A matching rule wins, even when the upstream said otherwise. If no rule matches, the upstream decision is honored, falling back to base_rate only when there is no parent.

This means a rule like SamplingRule::forJob(ProcessPayment::class, 1.0) will sample the job's trace regardless of whether the dispatching request was sampled. The trade-off is that a rule overriding the upstream decision produces a partial trace from the upstream perspective: the parent service has spans that no longer connect to a child trace, or the other way around.

Custom samplers

You can replace the sampler entirely. Implement the Sampler interface:

use Spatie\FlareClient\EntryPoint\EntryPoint;
use Spatie\FlareClient\Sampling\Sampler;

class AlwaysSampler implements Sampler
{
    public function __construct(protected array $config) {}

    public function shouldSample(EntryPoint $entryPoint, ?bool $parentSampled = null): bool
    {
        return true;
    }
}

$parentSampled carries the upstream sampling decision when the trace was started from a traceparent, or null when there is no parent. Use it to keep continued traces consistent with their parent, or ignore it to keep your sampler's behavior independent of upstream services.

Register the sampler with sampler(). The optional config array is passed to the constructor:

$config->sampler(AlwaysSampler::class, ['some_option' => true]);

If your sampler should support deferred sampling (so it can change its mind once a handler is resolved), implement DeferrableSampler instead. It adds three methods: isDeferred() to report whether the sampler is waiting for more information, reevaluate(EntryPoint $entryPoint) to make a final decision, and reset() to clear the deferred state. The DynamicSampler documented above is the reference implementation.