Skip to content
PulsusDB

Traces with TraceQL

import { Aside } from ‘@astrojs/starlight/components’;

PulsusDB stores spans for both exact trace retrieval and attribute-driven search. TraceQL is parsed into a plan that uses ClickHouse time ordering, service fields, and configured attribute indexes.

Fetch a trace

Section titled “Fetch a trace”
Terminal window
curl 'http://localhost:3100/api/traces/v1/trace/0123456789abcdef0123456789abcdef'

Search traces

Section titled “Search traces”
Terminal window
curl --get 'http://localhost:3100/api/traces/v1/search' \
  --data-urlencode 'q={ resource.service.name = "checkout" && duration > 1s }' \
  --data-urlencode 'start=1761901200' \
  --data-urlencode 'end=1761904800' \
  --data-urlencode 'limit=50'

Use bounded time ranges and selective service or attribute filters. Trace search first identifies matching spans and then assembles trace-level results.

Tag discovery

Section titled “Tag discovery”

Trace APIs include routes for discovering tag names and values. Use those routes to populate query builders instead of scanning trace results client-side.

Indexed attributes

Section titled “Indexed attributes”

At schema creation time, you can configure up to 16 bloom-filtered attributes:

Terminal window
PULSUS_TRACEQL_INDEXED_ATTRIBUTES='span.http.method,span.http.route,event.exception.type'

Names use span. or event. followed by a dot-separated key. Readers still return correct answers when their configuration differs from the schema, but eligible searches may become slower. Changing the schema-side list requires a rebuild.

Grafana compatibility

Section titled “Grafana compatibility”

Set PULSUS_COMPAT_ENDPOINTS=true before configuring a compatible trace datasource. Point it at the PulsusDB base URL and leave gRPC streaming search and streaming metrics disabled.