docs(observability): correct TraceQL syntax in query reference and troubleshooting guide#3274
Open
marians wants to merge 3 commits into
Open
docs(observability): correct TraceQL syntax in query reference and troubleshooting guide#3274marians wants to merge 3 commits into
marians wants to merge 3 commits into
Conversation
…oubleshooting guide The TraceQL query reference and the troubleshooting how-to contained several invalid query constructs. Correct them against the current Grafana Tempo TraceQL spec (colon-scoped intrinsics, Tempo 2.3+, which GS v31+/v33+ clusters run): - Intrinsics now use colon scope: span:duration, trace:duration, span:name, span:kind, span:status, trace:rootService (were span.duration, trace.duration, span.name, span.kind, status, trace.root.service.name). - Attribute references keep dot scope (span.http.method, resource.service.name). - Remove the invalid `trace.` attribute scope and `parent.` prefix; express parent/child with structural operators (>, >>, <, <<, ~). - Replace invalid search functions: quantile() -> avg()/note on TraceQL metrics for percentiles; drop limit() (no such function); replace the select(trace.start_time > now() - 1h) time filter with the Grafana time range picker (TraceQL has no now()/time function). - Unquote enum values (span:status = error, span:kind = client/server). - Group error patterns by span:statusMessage (was span.status.message). Add the TraceQL terms `intrinsic(s)` and `spanset(s)` to the vale vocabulary. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
marians
force-pushed
the
traceql-accuracy-pass
branch
from
July 9, 2026 14:57
bae5b52 to
e7e6955
Compare
marians
commented
Jul 9, 2026
marians
commented
Jul 9, 2026
marians
commented
Jul 9, 2026
…ines Every by() stage is now followed by an aggregate and a comparison, and every aggregate carries a trailing comparison, matching the only forms the Tempo TraceQL spec documents (terminal by()/bare aggregates aren't shown as valid): - Group-a-service's-operations example groups by span:name (not the already-filtered resource.service.name) and adds | count() > 1. - Performance-analysis pattern pairs by() with avg(span:duration) > 1s. - Error-investigation and span-kind examples get trailing count() > 1. - Capacity-planning count() and the troubleshoot statusMessage grouping get trailing comparisons. - Fix alphabetical order of the spanset vocabulary entry. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
pipo02mix
approved these changes
Jul 13, 2026
pipo02mix
left a comment
pipo02mix
left a comment
Contributor
There was a problem hiding this comment.
I cannot judge the traceql commands but if those come from official docs I'd say LTGM
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does / why we need it
This is the owed TraceQL SME accuracy pass flagged during the team-atlas Diátaxis split (giantswarm/giantswarm#37089). The TraceQL query reference (formerly the "advanced TraceQL tutorial") and the troubleshooting how-to had accumulated several invalid query constructs that wouldn't parse or run against Tempo.
I verified every construct against the current Grafana Tempo TraceQL spec. The fixes assume colon-scoped intrinsics (Tempo 2.3+), which GS clusters supporting tracing (release v31+ alpha / v33+ full) run. Please sanity-check that version assumption — if any deployment is on pre-2.3 Tempo, the classic dotless intrinsics (
duration,traceDuration,status,rootServiceName) would be needed instead.Corrections
span.durationspan:durationtrace.durationtrace:durationspan.name,span.kind,statusspan:name,span:kind,span:statustrace.root.service.nametrace:rootServicespan.status.messagespan:statusMessagetrace.scopeparent.resource.service.name/parent.span.name>,>>,<,<<,~)| quantile(0.95)avg()/count()search aggregates; note that percentiles need a TraceQL metrics query| limit(100)limit()function)| select(trace.start_time > now() - 1h)now()/time function;select()only picks fields)status = "error"style /span.kind = "client"span:status = error,span:kind = clientAttribute references (
span.http.method,resource.service.name,span.db.system, …) correctly keep dot scope and are unchanged. Valid pipeline usage is now shown with comparisons (| count() > 3,| avg(span:duration) > 1s).Verified locally with
make lint-prose(no findings) andhugo --renderToMemory(relrefs resolve).Things to check/remember before submitting
last_review_datenot bumped: correcting syntax within an existing page, no structural change. (Reviewer: happy to bump if you'd prefer, since this is a genuine technical correction.)🤖 Generated with Claude Code