Traces reference

Ingest

POST https://traces.siteqwality.com/v1/traces
Authorization: Bearer <api-key>
Content-Type: application/x-protobuf | application/json

Body: standard OTLP ExportTraceServiceRequest. Most OTel SDK exporters handle the format for you.

Span attribute conventions

SiteQwality renders standard OTel semantic-convention attributes natively. Stick to the standard names where possible:

HTTP

Attribute	Description
`http.method`	`GET`, `POST`, …
`http.url`	Full URL including query.
`http.target`	Path + query (e.g. `/api/users?id=123`).
`http.host`	Host header.
`http.status_code`	Numeric.
`http.user_agent`	UA string.
`http.request_content_length`	Bytes.
`http.response_content_length`	Bytes.

DB

Attribute	Description
`db.system`	`postgresql`, `mysql`, `redis`, `mongodb`.
`db.statement`	The SQL/query (consider scrubbing PII).
`db.operation`	`SELECT`, `INSERT`, `UPDATE`.
`db.name`	Database name.
`db.user`	Connection user.

Messaging

Attribute	Description
`messaging.system`	`kafka`, `sqs`, `rabbitmq`.
`messaging.destination`	Topic / queue.
`messaging.operation`	`send`, `receive`, `process`.

Resource attributes (per-service)

These should be set once on the OTel SDK init (Resource.create({...})) and apply to every span:

Attribute	Description
`service.name`	Required. Logical service name.
`service.version`	App version.
`service.instance.id`	Pod / VM identity.
`deployment.environment`	`prod`, `staging`.
`host.name`	Hostname.
`cloud.region`	`us-east-1`.

Span fields stored

Field	Description
`trace_id`	32-char hex; identifies the trace.
`span_id`	16-char hex; identifies the span.
`parent_span_id`	Empty for root spans.
`operation_name`	Span name.
`service_name`	From resource attributes.
`span_kind`	`server`, `client`, `producer`, `consumer`, `internal`.
`start_time`, `end_time`	RFC 3339.
`duration_ms`	Computed.
`status_code`	`OK` or `ERROR`.
`status_message`	Optional error message.
`attributes`	All custom + standard span attributes.
`resource_attributes`	All resource attributes.
`events[]`	Timestamped log-like events.
`links[]`	Cross-trace span references.

Search: `GET /traces/search`

Param	Description
`start_time`, `end_time`	RFC 3339 window.
`service_name`	Exact match.
`operation_name`	Exact match.
`min_duration_ms`, `max_duration_ms`	Range filter.
`status`	`ok` or `error`.
`search`	Free-text across span attributes.
`tags`	URL-encoded JSON object of span-attribute filters. See tag filters.
`limit` (default 50, max 200), `offset`	Pagination.
`sort_field`, `sort_order`	Order.

Response:

{
  "total": 1234,
  "traces": [
    {
      "trace_id": "...",
      "root_service": "api",
      "root_operation": "POST /checkout",
      "services": ["api", "billing", "db"],
      "span_count": 14,
      "duration_ms": 482.3,
      "error_count": 0,
      "start_time": "..."
    }
  ]
}

Tag filters

tags filters on span attributes. It takes a single URL-encoded JSON object, not repeated key=value pairs:

curl -G https://api.siteqwality.com/traces/search \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  --data-urlencode 'tags={"http.method":"GET","peer.service":"payments-db"}'

In the dashboard this is the Tag Filters input on the Trace Explorer: type http.method:GET and press Enter to add a filter pill.

Semantics, all of which matter:

Multiple keys are ANDed. Every pair must match.
Exact, case-sensitive string equality. No wildcards, no negation, no ranges.
Values must be JSON strings. {"http.status_code": 200} filters nothing; write {"http.status_code": "200"}.
Malformed JSON is ignored rather than rejected. A typo returns unfiltered results instead of an error, so if a filter appears to do nothing, check the JSON first.
Span attributes only. Resource attributes, including service.name, are not reachable this way. Use the dedicated service_name parameter for those.

tags is accepted by both GET /traces/search and GET /traces/timeline.

Timeline percentiles

GET /traces/timeline returns, per bucket: time, total, error, and the trace-duration percentiles p50_ms, p95_ms and p99_ms. The dashboard charts these as Latency percentiles.

Read them precisely:

They measure whole-trace duration (earliest span start to latest span end), not individual span duration.
A trace is attributed to the bucket containing its earliest span start.
A trace counts as errored if any span in it has an error status.
They are approximate. The underlying quantile is sampled, which is right for charts and wrong for contractual reporting.
Empty buckets return zeros, so a flat zero line means no traces, not fast traces.

Bucket width is derived from the time range and cannot be overridden.

Adjacent endpoints

Method	Path	Purpose
`GET`	`/traces/services`	Distinct services seen in window.
`GET`	`/traces/operations`	Distinct operations (optionally filtered by service).
`GET`	`/traces/timeline`	Bucketed counts (total + errors) for charting.
`GET`	`/traces/{trace_id}`	Full span tree.
`GET`	`/traces/{trace_id}/logs`	Logs tagged with this trace_id. `span_id` filter, `limit` default 100 / max 500. See correlating logs.
`GET`	`/traces/service-map`	Nodes + edges for the dependency graph.