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.

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.

Attribute Format

All attributes in the traces endpoint (on resources, scopes, spans, and span events) use the OpenTelemetry key-value array format:

[
  {
      "key" : "http.method",
      "value" : {
          "stringValue" : "GET"
      }
  },
  {
      "key" : "http.status_code",
      "value" : {
          "intValue" : 200
      }
  },
  {
      "key" : "error",
      "value" : {
          "boolValue" : true
      }
  }
]

Each attribute is an object with a key (string) and a value object containing exactly one typed field:

arrayValue

{
    "key": "tags",
    "value": {
        "arrayValue": {
            "values": [
                { "stringValue": "web" },
                { "stringValue": "production" }
            ]
        }
    }
}

kvlistValue

{
    "key": "http.request.headers",
    "value": {
        "kvlistValue": {
            "values": [
                { "key": "Content-Type", "value": { "stringValue": "application/json" } },
                { "key": "Accept", "value": { "stringValue": "text/html" } }
            ]
        }
    }
}

This differs from the errors endpoint, which uses flat key-value objects for attributes (e.g. { "http.method": "GET" }).

Responses

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

Success response:

{
    "message": "ok",
    "errors": {}
}

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
                        }
                    ]
                }
            ]
        }
    ]
}