Lifecycle

Every trace must contain at least one container span. A container represents the entry point of your application's execution, the unit of work Flare uses to organize and display performance data.

Container Span Types

All other spans within a trace must be descendants of a container span. If a root span is not a container type, the trace will fail processing.

Application Lifecycle

An optional php_application span can wrap a container to capture the full framework lifecycle. When present, it must have at least one container-type descendant. The application lifecycle consists of the following phases:

php_application
├── php_application_registration
├── php_application_boot
├── php_request (container)
│   ├── php_global_before_middleware
│   ├── php_routing
│   ├── ...
│   └── php_response
└── php_application_terminating

When an application span is present, Flare adjusts the container's start time to include boot time, giving a complete picture of the request duration.

The application lifecycle spans are entirely optional. Long-running processes like Laravel Horizon or Octane boot once and then handle many requests or jobs. In these cases it makes sense to only send the container span (request or job) without wrapping it in an application span. A trace with just a root php_request or laravel_job is perfectly valid.

Nested Containers

Containers can be nested. For example, a request that dispatches a synchronous job will have two containers:

php_request (container)
├── php_query
└── laravel_job (container)
    ├── php_query
    └── redis_command

Each container defines its own boundary. Child spans are assigned to their nearest container ancestor.