The TraceQL query layer for ClickHouse® software

TraceQL
At ClickHouse® database speed

Search by attributes, duration, status and trace structure while PulsusDB compiles TraceQL into index-aware ClickHouse® database read plans built for fast answers

traceql.queryTRACES
TraceQL{ resource.service.name = "api" && duration > 1s }
PLAN↓index + time pruning
CLICKHOUSE SQL
SELECT trace_id,
min(start_ts), max(end_ts)
FROM trace_spans
PREWHERE service = 'api'
AND start_ts BETWEEN $start AND $end
WHERE duration_ns > 1000000000
GROUP BY trace_id
Matching trace setsX-Pulsus-Explain: 1
TRACESTraceQLCLICKHOUSE DATABASESTATELESS QUERY LAYER
A familiar language with a different read path

Search spans attributes and relationships

PulsusDB stores trace data for the questions engineers ask. TraceQL filters can use span, resource, event, link and instrumentation attributes, then combine those spans through structural operators and trace-level context

01

Attribute search

Filter span and resource attributes alongside duration, status, kind, IDs and trace-level intrinsics

02

Trace structure

Express child, descendant, parent, ancestor and sibling relationships between matching spansets

03

Trace metrics

Run instant and range TraceQL metrics queries over the same stored spans used for search

04

Trace discovery

Fetch traces by ID, search with TraceQL and discover tag names and values through product-neutral APIs

From selector to compiled plan

See the query
See the SQL

Move from a simple selector to a complex expression and inspect the representative ClickHouse SQL shape PulsusDB produces at each level

01Simple TraceQL

Find traces by service

A resource service filter maps directly to the physical service column and becomes an early ClickHouse PREWHERE constraint

TRACEQLTrace search · newest matching traces
{ resource.service.name = "checkout" }
PLAN STAGES
  1. 01typed service column
  2. 02time pruning
  3. 03trace grouping
CLICKHOUSE SQLREPRESENTATIVE PLAN
SELECT trace_id, max(timestamp_ns) AS bound_ts
FROM trace_spans
PREWHERE service = 'checkout'
WHERE timestamp_ns >= {start} AND timestamp_ns < {end}
GROUP BY trace_id
ORDER BY bound_ts DESC, trace_id ASC
LIMIT 20
A narrow search over the ordered span storeX-Pulsus-Explain: 1
SQL is shortened for readability and uses named placeholders Read the query lowering reference ↗
From expression to efficient read

Plan the query
Protect the answer

PulsusDB only pushes work into the ClickHouse database when it can preserve the language’s semantics. Everything else remains the query engine’s job

01
FILTER

Narrow candidate spans

Use typed attributes, intrinsics and time bounds to build an index-aware candidate set

02
RELATE

Follow trace structure

Evaluate spanset operators against parent, child, ancestor, descendant and sibling relationships

03
ASSEMBLE

Return complete context

Group matching spans by trace and produce the search or metrics response your tooling expects

Product-neutral by default

The API surface
your tools need

Use PulsusDB’s documented API directly. Compatibility aliases remain optional, so the platform is not defined by another product’s routing conventions

See the compatibility matrix ↗
GET/api/traces/v1/searchTraceQL search
GET/api/traces/v1/trace/{traceId}Trace by ID
GET/api/traces/v1/metrics/query_rangeTrace metrics
One platform every signal

Keep following
the question

Move from one signal to the next without changing the observability data platform underneath