boxel: Skill for Claude Code

Federated search query-shape diagnosis

A federated search is a QUERY (or POST) whose query travels in the request body. Access logs carry method, URL, status and timing and never bodies — so without this channel a search load is legible only as a rate: how many ran and how long each took, with nothing about what any of them asked for.

boxel:search-shape closes that. One flat JSON line per _federated-search request, emitted from the single call site in packages/realm-server/handlers/handle-search.ts, defined in packages/runtime-common/search-shape.ts. It is the search sibling of client-perf-diagnosis (browser telemetry) and capture-perf-diagnosis (capture telemetry), and shares their emit convention.

The module header in search-shape.ts defines what each member means. This skill is about querying the channel and the ways a reasonable query returns a wrong number; where it touches a field's meaning it does so only far enough to explain the consequence, and points at the header for the rest.

Where the lines come from

Every line is emitted by the realm-server, so service="realm-server" is complete — there is no worker-side emission. One line per request that reaches the handler and parses a query, on every path that answers: a fresh compute, each cache outcome, a 304, the time-budget 408, and an escaping 500.

Three things emit nothing at all, and the third is the one that bites:

• a request whose query fails to parse (a malformed body, a bad field path) — it never became a search;
• a request multiRealmAuthorization rejects;
• a search the admission gate sheds. searchAdmission (packages/realm-server/middleware/index.ts) answers an over-ceiling search with a 429 before the handler runs, and logs it on realm:search-admission instead.

That last one means this channel counts admitted searches, not arriving ones. Under exactly the saturation it exists to explain, the missing lines are the excess — so pair any spike with the shed count or you will read a ceiling as a plateau.