Add search query to TraceFilters

[thorrester]

Pull Request

Short Summary

Moves the Lucene-style search query (q) from a URL query parameter into TraceFilters as a first-class query: Option<String> field. All three trace endpoints (/paginated, /facets, /spans/filters) previously accepted ?q=<dsl> alongside a JSON body — now the DSL string travels in the body with everything else.

Context

The old design split search state across two transport mechanisms: structured filters in the POST body, freetext DSL in the URL. That meant the server needed a dedicated SearchQ extractor, a merge_q_into_filters function to stitch them together, and the client had to parse the query string, then mutate the resulting struct field-by-field to apply overrides. It was fiddly and the URL param was invisible to any caller building TraceFilters directly.

Before:

// client: parse DSL, then override each field manually
let mut filters = TraceFilters::parse(q)?;
if let Some(start_time) = start_time { filters.start_time = Some(start_time); }
// ... 5 more fields

// server: separate extractor, then merge
async fn paginated_traces(
    Query(search): Query<SearchQ>,
    Json(body): Json<TraceFilters>,
) -> ... {
    let body = merge_q_into_filters(search.q, body)?;

After:

// client: struct literal, query is just another field
let filters = TraceFilters {
    query: Some(q.to_string()),
    start_time,
    end_time,
    ..Default::default()
};

// server: single extractor, normalize in place
async fn paginated_traces(
    Json(body): Json<TraceFilters>,
) -> ... {
    let body = normalize_trace_filters(body)?;

normalize_trace_filters reads body.query, parses it into a FilterClause, merges parsed fields into the body (body fields win on conflict), then clears query before passing the struct downstream. The DSL query field is consumed at the boundary — nothing downstream sees it.

Python stubs and PyO3 bindings updated to expose query on TraceFilters.__init__.

File	Change
crates/scouter_types/src/trace/sql.rs	Adds query: Option<String> field to TraceFilters
crates/scouter_server/src/api/routes/trace/route.rs	Removes SearchQ, ?q= params, renames merge fn to normalize_trace_filters
crates/scouter_client/src/http/client.rs	Replaces parse-then-mutate with struct literal
crates/scouter_server/tests/api/trace.rs	Updates tests to set query in body, removes URL helper
py-scouter/python/scouter/_scouter.pyi	Adds query param to TraceFilters stub
py-scouter/python/scouter/stubs/tracing.pyi	Same
py-scouter/tests/integration/test_trace_filters.py	Adds round-trip test for query field

Is this a Breaking Change?

Yes. The ?q= query parameter is removed from all three trace endpoints. Any caller passing ?q=<dsl> directly to the HTTP API must move the DSL string into the request body as "query": "<dsl>".

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.57%. Comparing base (c99f2c3) to head (4e95557).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #294   +/-   ##
=======================================
  Coverage   76.57%   76.57%           
=======================================
  Files          26       26           
  Lines         918      918           
=======================================
  Hits          703      703           
  Misses        215      215           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.