Storage V2 gRPC Layer: Query Parameter Safety#
internal/storage/v2/grpc/handler.go implements the jaeger.storage.v2.TraceReader gRPC service. The Handler struct wraps a tracestore.Reader and translates incoming gRPC requests into the internal storage model. Three RPCs handle trace search โ FindTraces, FindTraceSummaries, and FindTraceIDs โ all delegating query conversion to a shared helper, toTraceQueryParams.
toTraceQueryParams: Shared Conversion and Validation#
toTraceQueryParams converts a proto *storage.TraceQueryParameters into a tracestore.TraceQueryParams. It handles all query fields and applies the following validation at the gRPC storage layer:
- Filter finalization: Calls
expressionproto.CallFromProtoandtracestore.FinalizeFilter; returnscodes.InvalidArgumenton error . SearchDepthbounds: Rejects negative values or values exceedingMaxSearchDepth(10000) withcodes.InvalidArgument. Note thatSearchDepth == 0is passed through as-is (meaning "backend default") โ it is not replaced with a default at this layer.- Pagination: Copies
Paginationfrom the wire message only ift.GetPagination() != nil, keepingnilpagination distinct from an empty one. - Filter/predicate exclusivity: Calls
query.EnsureFilterStandsAlone()to enforce that a structured filter (RFC 0005) cannot coexist with legacy predicate fields. GetFilter()/GetPagination()via proto getters: Uses proto-safe getters throughout, so aniltop-level*TraceQueryParametersresults inGetFilter()returningnil(no panic). However, field access liket.SearchDepthandt.ServiceNameare direct dereferences โ iftisnil, these still panic (see Known Issues below).
Attribute conversion is handled by convertKeyValueListToMap, which safely skips any nil KeyValue entries or entries with a nil Value before dispatching to setValueToMap. The setValueToMap function supports all AnyValue types (string, bool, int, double, bytes, array, kvlist) and handles nested nil entries defensively .
Contrast with the query-service layer: The higher-level querysvc layer (querysvc/conversion.go) applies DefaultSearchDepth = 100 when SearchDepth == 0 and no pagination is set , enforces time-range presence and ordering , and clamps PageSize to MaxPageSize . The gRPC storage handler intentionally does not repeat these checks โ per its own doc comment, "converting a query toward what the reader supports is the query service's job (ADR-013)" .
Known Issues and Historical Bugs#
Nil Query Causes a Panic#
All three request types define Query as an optional pointer (*TraceQueryParameters) in proto3. If a client omits Query, toTraceQueryParams receives nil and panics on direct field accesses like t.SearchDepth and t.ServiceName before the filter/getter path runs. The companion toSpanQueryParams does have a nil guard that returns codes.InvalidArgument, "missing query" โ toTraceQueryParams does not. The fix is the same nil check at the top of the function.
SearchDepth: 0 Fails on In-Memory Storage#
Proto3 cannot distinguish an omitted field from an explicit zero. A client that leaves search_depth unset causes toTraceQueryParams to forward SearchDepth: 0 to the backend. The in-memory backend explicitly rejects non-positive values with errInvalidSearchDepth. Other backends (Elasticsearch, Cassandra, Badger) silently default to 100 internally, so this only surfaces in the default all-in-one configuration. This was tracked in Issue #9099. The querysvc layer's toReaderQuery() now applies DefaultSearchDepth = 100 before reaching storage for paths that go through it , but callers that bypass querysvc and hit the gRPC storage server directly are still at risk if they omit search_depth.
Error Taxonomy#
internal/storage/v2/api/tracestore/errors.go defines the two refusal families used throughout the layer:
ErrInvalidQueryโ malformed query (maps tocodes.InvalidArgument/ HTTP 400)errors.ErrUnsupportedโ well-formed query unsupported by this backend (maps tocodes.Unimplemented/ HTTP 501)
Notable sentinels: ErrPaginationInvalid (e.g., SearchDepth + Pagination together), ErrPaginationUnsupportedByFindTraces (paginating FindTraces is structurally impossible since the streaming response carries no continuation token field).
Related Changes and Key References#
- PR #8603 โ Aligned
FindTraceIDsto use its ownFindTraceIDsRequestproto type (previously reusedFindTracesRequest), fixing a protocol inconsistency and bumpingjaeger-idlv0.7.1 โ v0.8.0. - PR #9067 โ Merged
FindTraceSummariesinto the mandatorytracestore.Readerinterface ; backends that cannot produce summaries natively embedUnsupportedTraceSummaries, yieldingerrors.ErrUnsupported, which the handler translates tocodes.Unimplemented.
| File | Purpose |
|---|---|
internal/storage/v2/grpc/handler.go | Handler, all RPCs, toTraceQueryParams, convertKeyValueListToMap |
internal/storage/v2/api/tracestore/reader.go | Reader interface, TraceQueryParams, MaxSearchDepth, MaxPageSize, Pagination |
internal/storage/v2/api/tracestore/errors.go | ErrInvalidQuery, ErrPaginationInvalid, ErrPaginationUnsupportedByFindTraces, and other refusal sentinels |
cmd/jaeger/internal/extension/jaegerquery/querysvc/conversion.go | Higher-level toReaderQuery() โ applies DefaultSearchDepth, clamps page size, enforces time-range rules |