Jaeger API v3 Query Handling#
Jaeger's API v3 exposes trace-search operations over two transport paths โ gRPC and HTTP (gRPC-gateway) โ both under cmd/jaeger/internal/extension/jaegerquery/internal/apiv3/. The two paths share a querysvc.TraceQueryParams model but previously diverged in how they parsed and validated parameters, particularly SearchDepth. As of PR #9612, search-query validation is centralized in querysvc so all API paths (gRPC, HTTP, MCP, etc.) behave identically.
Key Source Files#
| File | Purpose |
|---|---|
apiv3/grpc_handler.go | gRPC handler: FindTraces, FindTraceSummaries, GetTrace, GetDependencies |
apiv3/http_gateway.go | HTTP gateway delegating to parseFindTracesQuery |
apiv3/query_parser.go | HTTP query-string parser; wire-translation only, no validation |
querysvc/conversion.go | TraceQueryParams.toReaderQuery() โ all validation and defaults |
querysvc/service.go | DefaultSearchDepth = 100, prepareSearchQuery |
internal/storage/v2/memory/tenant.go | In-memory backend: findTraceAndIds, validTrace, validSpan |
Query Parameter Flow#
Every API path translates its wire format into a querysvc.TraceQueryParams, then calls querysvc.prepareSearchQuery, which invokes TraceQueryParams.toReaderQuery() before dispatching to storage. Validation occurs once in toReaderQuery, not in the individual handlers.
HTTP path โ parseFindTracesQuery reads URL query parameters and translates them into querysvc.TraceQueryParams. It explicitly does not apply defaults or enforce constraints โ the code comment at lines 157โ160 delegates that responsibility entirely to the query service. It supports canonical camelCase params (query.searchDepth) and deprecated snake_case aliases (query.search_depth, query.num_traces) via the getQueryParam helper.
gRPC path โ the gRPC handler similarly converts proto fields to querysvc.TraceQueryParams and forwards to prepareSearchQuery. No per-handler defaults are applied.
SearchDepth: Validation and Defaults#
toReaderQuery enforces these rules on every search regardless of transport:
| Rule | Behavior |
|---|---|
StartTimeMin or StartTimeMax is zero | ErrInvalidQuery: both bounds required |
StartTimeMin >= StartTimeMax | ErrInvalidQuery: min must precede max |
SearchDepth > MaxSearchDepth | ErrInvalidQuery: must be in [0, MaxSearchDepth] |
SearchDepth == 0 and no pagination | Apply DefaultSearchDepth (100) |
SearchDepth != 0 with pagination | ErrPaginationInvalid: mutually exclusive |
DurationMin or DurationMax negative | ErrInvalidQuery |
DefaultSearchDepth = 100 is declared in querysvc/service.go and applies to both gRPC and HTTP callers that omit the field.
Historical note: Before PR #9612, each handler applied its own defaults inconsistently โ the HTTP path had defaultSearchDepth = 100 in the parser, gRPC passed 0 through to storage, and the MCP tool used 10. This caused transport-specific failures on the in-memory backend (see below) and was the motivation for centralizing validation.
In-Memory Backend: SearchDepth Enforcement#
The in-memory store's findTraceAndIds enforces a hard constraint at the storage layer:
SearchDepth == 0โ returnserrInvalidSearchDepthSearchDepth > config.MaxTracesโ returnserrInvalidSearchDepth
This is the point of failure when a zero-depth query reaches the backend directly. Other backends (Elasticsearch, Cassandra, Badger) silently default to 100 internally, so the error historically only surfaced in the default all-in-one configuration using the memory backend. The query-service-level default now prevents SearchDepth=0 from ever reaching storage for unpaginated queries.
After the depth check passes, findTraceAndIds walks the ring buffer backwards from mostRecent, collecting up to SearchDepth traces that pass validTrace .
In-Memory Backend: Span Filtering (validSpan)#
validSpan checks these predicates in order (AND semantics โ a trace matches only if a single span satisfies all conditions simultaneously):
| Predicate | Query field | Notes |
|---|---|---|
| Operation name | OperationName | Exact match on span.Name() |
| Start time window | StartTimeMin / StartTimeMax | Inclusive bounds |
| Duration | DurationMin / DurationMax | Span duration |
error attribute | Attributes["error"] | error=true โ StatusCodeError; error=false โ not Error (includes Unset) |
span.status | Attributes["span.status"] | Exact OTel status string |
span.kind | Attributes["span.kind"] | Span kind string |
scope.name / scope.version | Attributes["scope.*"] | Instrumentation scope |
resource.* prefix | Attributes["resource.X"] | Matched only against resource attributes |
| Generic attributes | Other Attributes keys | Checked across span, scope, resource, events, and links |
When query.Filter is set (structured filter expression), the legacy predicate path is bypassed entirely and matchesFilter is evaluated instead. Filter and ServiceName/OperationName/Attributes are mutually exclusive โ enforced by the query service before any reader sees the query.
Related PRs and Issues#
| Reference | Topic |
|---|---|
| PR #9612 | Centralized search-query validation in querysvc; removed per-handler defaults |
| PR #8633 | Introduced defaultSearchDepth=100 in HTTP parser (pre-#9612 fix) |
| PR #8438 | Earlier proposal for HTTP 400 / InvalidArgument on SearchDepth<=0 (closed) |
| Issue #9099 | SearchDepth=0 over gRPC fails on in-memory storage |
| Issue #9156 | Nil Query in storage v2 gRPC layer causes panic |