Flare Flare Laravel Laravel PHP PHP JavaScript JavaScript React React Vue Vue Protocol Protocol

Entry Points

Every error, trace, and log record sent to Flare describes work that was initiated by some kind of entry point. The entry point is the request, command, or job that started the unit of work, and Flare uses it to filter, group, and aggregate telemetry across all three endpoints.

The entry point is expressed as a small set of attributes on the payload. The same attributes appear on errors, on the root span of a trace, and on log records that are correlated to a request, command, or job.

Types

Flare recognizes three entry point types.

Type Description
web An incoming HTTP request
cli A command-line invocation
queue A queued job being processed

If the type is not provided, Flare defaults to web.

Attributes

Set the following attributes on the payload to describe the entry point.

Attribute Description
flare.entry_point.type Entry point type: web, cli, or queue. Defaults to web if not provided
flare.entry_point.value The raw entry point value: full URL for web, command with arguments for CLI, job class for queue
flare.entry_point.handler.identifier A groupable identifier: route pattern for web (e.g. GET /users/{userId}), command name for CLI, job name for queue
flare.entry_point.handler.name The handler: controller, command class, job class, or null
flare.entry_point.handler.type The kind of handler, prefixed with the language or framework (see below)

Only type and value are required. The handler attributes are optional and may be omitted (or sent as null) when the framework has not resolved a handler yet, or when there is no handler concept (for example, a plain PHP script or a closure-based job).

Handler type values

flare.entry_point.handler.type is a short string that tells Flare what kind of handler ran. It is prefixed with the language or framework so a single Flare project can mix handlers from different stacks.

handler.type handler.name example When
laravel_controller UsersController Invokable controller
laravel_controller BlogController@index Multi-action controller
laravel_closure routes/web.php Closure route
laravel_view users.index View route
laravel_redirect /new-path Redirect route
livewire_component App\Livewire\Dashboard Livewire class component
livewire_sfc pages.dashboard Livewire single-file component
laravel_command App\Console\Commands\WorkCommand Artisan command class
laravel_job App\Jobs\SendWelcomeEmail Queued job
php_closure Closure Closure job or command
php_script worker.php Plain PHP script
php_function handleRequest Function-based handler

If you build a Flare client for another language or framework, pick a stable prefix (e.g. symfony_controller, node_route) and reuse it consistently.

Examples per scenario

Scenario type value handler.identifier handler.name handler.type
Web (controller) web https://example.com/users/123 GET /users/{userId} UsersController laravel_controller
Web (multi-action) web https://example.com/blog/hello GET /blog/{slug} BlogController@index laravel_controller
Web (closure) web https://example.com/health GET /health routes/web.php laravel_closure
Web (view route) web https://example.com/welcome GET /welcome users.index laravel_view
Web (Livewire) web https://example.com/dashboard GET /dashboard App\Livewire\Dashboard livewire_component
Web (Livewire SFC) web https://example.com/dashboard GET /dashboard pages.dashboard livewire_sfc
Web (no router) web https://example.com/users/123 GET /users/123 null null
CLI (command) cli horizon:work --queue=high horizon:work App\Console\Commands\WorkCommand laravel_command
CLI (plain PHP) cli php worker.php --daemon worker.php null php_script
Queue (job) queue App\Jobs\SendWelcomeEmail App\Jobs\SendWelcomeEmail App\Jobs\SendWelcomeEmail laravel_job
Queue (closure) queue Closure Closure null php_closure

Where the attributes appear

Errors

For error reports, entry point attributes go directly in the root attributes object alongside other resource and scope attributes. They are not nested under a separate event.

Traces

For traces, the entry point attributes belong on the root container span (php_request, php_command, or php_job). They identify the work the trace represents.

When an application uses an optional php_application wrapper around the container, the attributes still belong on the container itself, not on the wrapper.

Logs

For logs, entry point attributes may be added to a log record when the record is produced inside a request, command, or job. This lets logs be filtered alongside errors and traces from the same source.

Resolving the handler later

The handler is often unknown when work begins. A web framework only learns which controller handles a request after routing middleware runs, and a queue worker may only know the job class once it pulls a payload off the queue.

Flare clients are expected to resolve the entry point in two passes:

  1. Set type and value as soon as the work starts (e.g. when the request comes in or the worker picks up a job).
  2. Fill in the handler attributes once the framework resolves a controller, command, or job class.

The reference PHP client implements this with the EntryPoint value object and EntryPointResolver. The handler attributes are added in place once setHandler() is called, and any sampling decisions that depend on the handler can be re-evaluated at that point.

Subtask entry points

A trace can describe nested work with multiple containers (for example, a request that dispatches a synchronous job, see Lifecycle). Each container is its own unit of work and has its own entry point attributes on the container span.

The framework integrator decides whether a job or command running inside an existing trace becomes a subtask of that trace or starts a new root trace. Either is valid; the protocol only requires that each container span carries its own entry point attributes.

Introduction Resources