Search execution trace

When adaptive_search.execution_trace=true, a standard document search response includes a top-level search_execution object:

{
  "search_execution": {
    "schema_version": 1,
    "adaptive": false,
    "from_cache": false,
    "planner": "legacy",
    "intent": "not_evaluated",
    "difficulty": "not_evaluated",
    "final_strategy": "hybrid",
    "stages": [
      {
        "order": 1,
        "name": "request_parse",
        "category": "request",
        "status": "executed",
        "algorithm": "json_and_query_parameters",
        "duration_us": 42,
        "candidates_in": 0,
        "candidates_out": 0
      }
    ]
  }
}

Stages are appended when their underlying operation completes. order values are strictly increasing and durations use a monotonic clock. Depending on the request, stages can include request parsing, validation, cache lookup, distributed fanout, lexical or vector retrieval, candidate merge, fusion, rerank, filtering, module weighting, sorting, facets, aggregations, grouping, pagination, projection, highlighting, suggestions, and response serialization.

Status values are planned, executed, skipped, degraded, cached, or failed. Phase 1 normally records executed operations; optional detailed tracing may add skipped stages in a later API revision.

The vector retrieval algorithm is reported as brute_force, matching the current exact-scan implementation. No ANN backend is advertised.

Privacy

Query text is absent by default. It appears only when the server has include_query_text=true and the request sends include_search_query_text=true. Query text is bounded and JSON-escaped.

The trace never includes raw vectors, generated embeddings, API keys, authorization headers, remote embedding credentials, embedded security filters, or internal document contents.

Cache hits

The response cache stores a finalized response, including its original trace. On a cache hit:

• from_cache becomes true;
• the cache_lookup stage becomes cached;
• its duration is measured for the current request;
• stored stages keep their original duration and receive details.timing_scope="original_execution" and details.cached_snapshot="true".

This prevents cached retrieval and ranking durations from being presented as new measurements.

Capability discovery

GET /etc?include=search_capabilities returns cache-safe, non-sensitive availability metadata. Phase 1 reports:

• supported_planners: ["legacy"];
• supported_fusion_methods: ["linear", "rrf"];
• vector_backends_available: ["brute_force"];
• adaptive_ranking_status: "not_implemented".

The endpoint contains no query history or per-request traces.