Traces payload

Endpoint

POST https://ingress.flareapp.io/v1/traces

Headers

Authentication

Authenticate using your project's private API key in the x-api-token header. The public API key cannot be used for this endpoint.

Payload

The trace payload follows the OpenTelemetry protocol structure.

Resource Spans

Resource

A resource represents the entity producing telemetry data (your application/service). For a list of common resource attributes, see Resources.

Scope Spans

Scope

A scope represents the instrumentation library that produced the spans. Different libraries (e.g. your Flare client, a database recorder, a cache recorder) can each be their own scope within the same resource.

Spans

A span represents a single unit of work within a trace, such as an HTTP request, a database query, or a cache operation. Each span has a start time, end time, and optional attributes that describe the work being done. Spans can be nested using parentSpanId to form a tree structure that represents the full execution flow of a request.

A non-null parentSpanId on a non-container span must reference a span sent in the same payload. Flare resolves such a span's container by walking up the parent chain, so a parentSpanId pointing at a span Flare never received leaves that span out of the trace, and depending on processing order other spans in the same payload with it. The report is still accepted, so nothing signals the loss.

Container spans are the exception. A container may name a parent that lives in a different payload, which is how a queued job links back to the request that dispatched it, or how a browser_web_vital span links back to the pageload it belongs to.

Span Status

Status Codes

Span Events

Span events are nested inside their parent span. For the full list of span types and span event types with their attributes, see Events.

Span & Span Event Types

The span type is determined by the flare.span_type attribute on the span. The span event type is determined by the flare.span_event_type attribute on the span event. These attributes are stripped from the attributes before display.

Entry Point

The root container span of a trace (a php_request, php_command, laravel_job, browser_pageload, or browser_navigation) should carry flare.entry_point.* attributes describing the request, command, job, or browser page that the trace represents. The same attributes are used by errors and logs; see Entry points for the schema and per-scenario examples.

Attribute Format

All attributes in the traces endpoint use the OpenTelemetry typed attribute format. See Attribute Formats for the full format specification and value types.

Web Vitals

A browser client splits Core Web Vitals over two spans: whatever is final goes on the browser_pageload span, and the rest follows later on a browser_web_vital span backdated to the page's start. See Web vitals in the JavaScript protocol docs.

Responses

All responses include CORS headers (Access-Control-Allow-Origin: *) and return application/json.

Success response:

{}

Validation error responses include the field path and a description of the issue:

{
    "message": "The given data was invalid.",
    "errors": {
        "resourceSpans.0.scopeSpans.0.spans.0.traceId": [
            "The traceId field is required in this resourceSpan."
        ]
    }
}

Example

{
    "resourceSpans": [
        {
            "resource": {
                "attributes": [
                    { "key": "service.name", "value": { "stringValue": "My Application" } },
                    { "key": "service.version", "value": { "stringValue": "1.0.0" } },
                    { "key": "service.stage", "value": { "stringValue": "production" } },
                    { "key": "telemetry.sdk.language", "value": { "stringValue": "PHP" } },
                    { "key": "telemetry.sdk.name", "value": { "stringValue": "spatie/flare-client-php" } },
                    { "key": "telemetry.sdk.version", "value": { "stringValue": "1.0.0" } }
                ],
                "droppedAttributesCount": 0
            },
            "scopeSpans": [
                {
                    "scope": {
                        "name": "spatie/laravel-flare",
                        "version": "1.0.0"
                    },
                    "spans": [
                        {
                            "traceId": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
                            "spanId": "1234567890abcdef",
                            "parentSpanId": null,
                            "name": "GET /users",
                            "startTimeUnixNano": 1710252000000000000,
                            "endTimeUnixNano": 1710252000150000000,
                            "status": { "code": 0 },
                            "attributes": [
                                { "key": "flare.span_type", "value": { "stringValue": "php_request" } },
                                { "key": "http.request.method", "value": { "stringValue": "GET" } },
                                { "key": "http.route", "value": { "stringValue": "/users" } },
                                { "key": "http.response.status_code", "value": { "intValue": 200 } }
                            ],
                            "droppedAttributesCount": 0,
                            "events": [
                                {
                                    "name": "cache hit",
                                    "timeUnixNano": 1710252000050000000,
                                    "attributes": [
                                        { "key": "flare.span_event_type", "value": { "stringValue": "php_cache" } },
                                        { "key": "cache.operation", "value": { "stringValue": "get" } },
                                        { "key": "cache.result", "value": { "stringValue": "hit" } },
                                        { "key": "cache.key", "value": { "stringValue": "users.list" } }
                                    ]
                                }
                            ],
                            "droppedEventsCount": 0
                        },
                        {
                            "traceId": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
                            "spanId": "abcdef1234567890",
                            "parentSpanId": "1234567890abcdef",
                            "name": "select * from `users`",
                            "startTimeUnixNano": 1710252000060000000,
                            "endTimeUnixNano": 1710252000080000000,
                            "status": { "code": 0 },
                            "attributes": [
                                { "key": "flare.span_type", "value": { "stringValue": "php_query" } },
                                { "key": "db.system", "value": { "stringValue": "mysql" } },
                                { "key": "db.statement", "value": { "stringValue": "select * from `users`" } }
                            ],
                            "droppedAttributesCount": 0,
                            "events": [],
                            "droppedEventsCount": 0
                        }
                    ]
                }
            ]
        }
    ]
}