Skip to content

docs(hunts): state what ships for scaling, smoothing and sigma - #1177

Merged
catinspace-au merged 4 commits into
mainfrom
docs/hunt-runner-scaling
Nov 16, 2026
Merged

catinspace-au merged 4 commits into
mainfrom
docs/hunt-runner-scaling

Conversation

@catinspace-au

Copy link
Copy Markdown
Contributor

Three data-plane pages overstate what shipped. Each opens with what's available in 2.2.2.

  • hunt-runner-scaling.md: removes the comparison with a scaler that never shipped. The page describes the shim, its cache-or-cold-hold fail-safe and the dfe-extras values. A starting runner or shim pod waits on the engine's readyz (dfe-common _waitfor.tpl). 2,303 words down to 1,577.
  • hunt-schedule-smoothing.md: smoothing is held back from 2.2.2 pending testing at higher volumes. It is coming in 2.2.3 as an opt-in beta behind hunts.smoothing.enabled (Adaptive hunt schedule smoothing: drift rate-hunt phases to flatten ClickHouse load #864). What ships is the hashed offset and the log_comment tagging.
  • SVGs from docs/data-plane/images/hunt_smoothing_figures.py replace the ASCII graphs. They are transparent with mid-grey ink for both themes. The maths is $$ LaTeX with pseudocode under each block. The docs site shows the maths as source until dfe-infra adds a maths renderer.
  • sigma.md: off by default behind sigma.enabled, held back until it's tested from feed to detection (XDR: ship sigma end to end in 2.2.2 (import, author, map, propagate, test) #887). The source mapping works. Providers, the catalogue and propagation are API-only. There are no stock ECS or CIM maps.

The three pages must match the 2.2.2 code. The figures must render on the site.

hunt-runner-scaling.md covers the shim design alone in 1,577 words. It says a starting pod waits for the engine.

hunt-schedule-smoothing.md starts with the release status: held back from 2.2.2. It describes an opt-in beta in 2.2.3 behind hunts.smoothing.enabled (#864). docs/data-plane/images/hunt_smoothing_figures.py draws the two ASCII graphs as SVGs. The maths is LaTeX with pseudocode under each block.

sigma.md starts with the release status: off behind sigma.enabled until it is tested from feed to detection (#887). It marks each unfinished part where it is described.
The maths section's callout says the maths is hand-written, scanned from a notebook and set in type.
@catinspace-au
catinspace-au marked this pull request as draft November 15, 2026 23:15
Smoothing is off by default. Turn it on with hunts.smoothing.enabled. Turning it off restores the hash offsets. It is not proven at PB/day.

The lease is held for one whole cycle, so the fleet runs one cycle per window. A move can come from any bucket above the mean. Hysteresis uses the curve's variance. The blurred tie-break moves a hunt away from similar hunts.

A move changes nothing a running hunt holds. Document three odd-window cases in place of two.

Add cost_quantile and horizon_max_seconds to the settings table. State which settings are fixed in code. Add the two gauges from the archive to the metrics.

Document three tests:

- Property tests on the maths.
- Tests against a real ClickHouse.
- The 30-hunt soak on a 3-replica ClickHouse.

Date the soak's flag-off and flag-on numbers. State what the soak does not prove.

Refs #864.
The How we know it works section documents the whole run. Across three hours with the flag on, summed peak memory per hour was 6.5, 5.0 and 3.3 GB against 8.1 GB with it off. The busiest bucket held 9, 7 and 8 queries against 12. The model's flatness fell from 23.7 to 2.3 over 34 moves.

Refs #864.
@catinspace-au
catinspace-au marked this pull request as ready for review November 16, 2026 05:15
@catinspace-au
catinspace-au merged commit b86fe8a into main Nov 16, 2026
19 checks passed
@catinspace-au
catinspace-au deleted the docs/hunt-runner-scaling branch November 16, 2026 05:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant