Requests

Flare can collect information about the requests being made to your application. This includes:

• The request method
• The request URL
• The body size & contents
• The user agent
• The IP address of the user
• The request headers
• The request cookies
• The request query parameters
• The request files
• The request session data

This functionality is enabled by default, but you can disable it by calling ignoreRequests() on the Flare config:

$config->ignoreRequests();

It is possible to filter out fields from the request body, headers, and the user's IP address. You can read more about this here.

Ignoring specific requests

You can drop traces for individual URLs, paths, or routes by passing patterns to collectRequests(). When a request matches one of these patterns, the trace is unsampled and no spans are sent for it.

$config->collectRequests(
    ignoredRoutes: ['horizon.*', 'telescope.*'],
    ignoredUrls: ['https://example.com/internal/*'],
    ignoredPaths: ['/health-check', '/metrics/*'],
);

Patterns are literal strings with * as a wildcard (the same syntax used by sampling rules). Routes are matched once the framework has resolved the route name, so route patterns are evaluated through deferred sampling.

Collecting requests

In our framework-specific versions of the Flare clients, requests are automatically traced to find performance issues.

In the framework-agnostic version of the package, your integration is responsible for calling the request recorder. The recorder accepts an attribute provider; use the helpers below for the common cases.

The trace itself is opened and closed through the lifecycle, not directly on the tracer. A typical request flow looks like this:

$flare->lifecycle->start();

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

// Handle your request

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

$flare->lifecycle->terminated();

recordStartFromGlobals() builds a PhpRequestAttributesProvider from the PHP superglobals ($_GET, $_POST, $_COOKIE, $_SERVER, and so on). For frameworks built on Symfony's HttpFoundation, use the Symfony helper instead:

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

For any other request object, implement RequestAttributesProvider and pass it to recordStart():

$flare->request()->recordStart(new YourRequestAttributesProvider($request));

Flare tries to group requests based on URLs. While this is useful, as soon as you have id's within your URL, this can be a problem.

For example, blog/1 and blog/2 are the same route; they show a blog post, yet due to their different id's, they will be grouped as different requests.

To group these requests together, supply a RouteAttributesProvider when ending the request (or call the routing recorder when your framework resolves the route):

use Spatie\FlareClient\AttributesProviders\PhpRouteAttributesProvider;

$flare->request()->recordEnd(
    routeAttributesProvider: new PhpRouteAttributesProvider('blog/{id}', method: 'GET'),
);

The class (or closure) that handled the request is captured through the entry point system. Most integrations do not need to set it manually: the routing recorder and the request providers fill it in. If you do need to populate it from a custom provider, implement EntryPointHandlerProvider alongside your RequestAttributesProvider.

You can also pass extra attributes alongside the standard ones:

$flare->request()->recordStart(
    new YourRequestAttributesProvider($request),
    attributes: [
        'server.port' => 80,
    ],
);

When ending the request, you can pass a response provider so the response status code, body size, and headers are recorded:

$flare->request()->recordEndFromSymfonyResponse($response);

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