Traces API Reference :: Kloudfuse Docs

Traces API Reference

Find the datasource UID

List the Grafana datasources and take the UID of the tempo-type entry:

curl -s -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/grafana/api/datasources" | \
  python3 -c "import json,sys; print([d['uid'] for d in json.load(sys.stdin) if d['type']=='tempo'])"

Search traces

GET …​/api/search runs a TraceQL query and returns the matching traces with their matched span sets.

Parameters:

Parameter Type Required Description
q string Yes The TraceQL query.
start Unix seconds Yes Start of the time range.
end Unix seconds Yes End of the time range.
limit int No Maximum traces to return.

Response fields (per trace):

Field Description
traceID Hex trace identifier; use it with Retrieve a trace by ID.
rootServiceName Service of the trace’s root span.
rootTraceName Operation name of the root span.
startTimeUnixNano Trace start time, nanoseconds.
durationMs Whole-trace duration in milliseconds.
spanSets The spans that matched the query, with their attributes and a matched count.

Example: Search for server spans of a service

curl -s -G -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/grafana/api/datasources/proxy/uid/<ds-uid>/api/search" \
     --data-urlencode 'q={.service_name = "demo-python-service" && kind = server}' \
     --data-urlencode "start=$(date -u -v-15M +%s)" \
     --data-urlencode "end=$(date -u +%s)" \
     --data-urlencode "limit=1"

Retrieve a trace by ID

GET …​/api/traces/{traceID} returns the complete trace — every span with full attributes, in OTLP resource-span form. Use the traceID from a search result.

Parameters:

Parameter Type Required Description
{traceID} path Yes Hex trace ID from a search result.

Example: Fetch one trace

curl -s -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/grafana/api/datasources/proxy/uid/<ds-uid>/api/traces/ead84305013f7d5cead227e0928569d3"

List tag names

GET …​/api/search/tags lists the span and resource tags available for TraceQL conditions.

Example: List tags

curl -s -G -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/grafana/api/datasources/proxy/uid/<ds-uid>/api/search/tags" \
     --data-urlencode "start=$(date -u -v-15M +%s)" \
     --data-urlencode "end=$(date -u +%s)"

List tag values

GET …​/api/search/tag/{tagName}/values lists the values of one tag within the time range — the discovery step before writing a filter on that tag.

Parameters:

Parameter Type Required Description
{tagName} path Yes The tag to enumerate.
start, end Unix seconds Yes Time range to inspect.
q string No A TraceQL query to restrict the values (v2 endpoint: /api/v2/search/tag/{tagName}/values).

Example: Values of service_name

curl -s -G -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/grafana/api/datasources/proxy/uid/<ds-uid>/api/search/tag/service_name/values" \
     --data-urlencode "start=$(date -u -v-15M +%s)" \
     --data-urlencode "end=$(date -u +%s)"

Limitations