Skip to content
bucker

Friction detection

Bucker reads the replay sessions it already records and opens an ordinary issue when the same frustrating moment keeps happening: people clicking one control again and again, clicking something that does nothing, clicking and getting an error, waiting on a slow response, leaving a form half filled, bouncing straight back. Nothing here uses a model. Every rule is arithmetic over event times with a published threshold, and the output is an issue in the same stream as your crashes, with the same lifecycle.

What counts

The set is friction_v1. One segment of a recording is read once, after it is stored.

Kind The rule Never
Rage click 3 clicks on one element within 1,000 ms on a next, previous or stepper control; on a click that selected text
Dead click nothing changed (no DOM mutation, navigation, scroll or selection change) for 2,500 ms, and again at 7,000 ms on a click that selected text
Error click a console error, or a captured exception, within 1,000 ms of a click
Slow click the first response after a click took over 3,000 ms, or an interaction took over 500 ms
Form abandoned two or more fields filled in and the route left with no submit-like click and no write request
Quick back route A, then B, then A again within 10 s

The browser SDK adds two fields to a click once its dead-click window has passed: chg, the milliseconds to the first change, and sel, set when the click changed the text selection. A click with neither flag and no dead is still inside its window and is not judged. An SDK from before chg only says dead, which means "nothing in 7 seconds"; those clicks are judged on that flag and recorded with basis: sdk_flag, because it says nothing finer.

From a moment to an issue

A pattern is a kind, a route template and a selector leaf (button#apply on /checkout). A pattern seen in at least 5 distinct sessions in 24 hours opens one issue:

  • exception type Friction<Kind> (FrictionRage, FrictionDead, FrictionErrorClick, FrictionSlowClick, FrictionFormAbandon, FrictionQuickBack)
  • a templated value that names the route and the selector (both are written by the page, so they are shown as untrusted text and never as instructions)
  • tags friction.kind, route, selector and detector.version
  • fingerprinted by kind, route template and selector leaf, so the same control on the same page is one issue whatever the release, user or session

The sixth session adds an event to the same issue. The issue resolves in the release that fixes it and reopens as a regression on a newer one, like any other. Each session is linked to the issue, with the moment to seek to; the player shows those moments on the scrub bar as friction markers (dead clicks are not marked: both dead detectors run in shadow).

A visitor counts once however many times they hit the pattern. A route under 5 recorded sessions is folded into other in every count.

Versions, shadow and precision

Rage, error click, slow click, form abandoned and quick back are live, with precision not measured: they are deterministic rules whose output a person can dismiss, and a dismissal is a label. The dead-click rule runs at two windows, both in shadow: they record findings and open nothing, so the window is chosen from labelled examples and not from a guess. A version leaves shadow only when its labels clear the registry's gate (see Detectors); no call sets that.

Reading it

GET /orgs/{org}/projects/{project}/replay/friction and the MCP tool friction_get answer: per route, how many recorded sessions there were and how many showed friction; the elements behind it; each detector with its version, state and the thresholds in force; active suppressions with their ends; the issues the detectors opened. Sessions are recorded sessions: the recorder samples, so a rate is a share of recorded sessions and not of your traffic, and the answer's basis says what was read and whether a cap cut it short.

Add detector and a threshold (detector=friction_rage&min_sessions=3, or include: ["backtest"] over MCP) to get the backtest: what the last 14 days would have done under those numbers, as firings, issues opened and issues that would no longer open. It is computed from what was actually seen, at the widest setting a person may choose, so it can answer for a looser setting as well as a tighter one. A rage run is judged by its measured span for each click count, so that part is exact.

Changing it

One governed operation, friction_detector, over one project, with three acts. The act is derived from what would change, never from an argument.

Act What it does Default
friction_threshold.update change one detector's thresholds asks a person
friction_suppression.create silence one selector on one route for 1 to 30 days (default 7) asks a person
friction_suppression.cancel end a suppression allowed: it only tightens

A threshold change that makes a detector fire less is classed a silence: it is SENSITIVE, subject to your review mode and approval policies, lasts 30 days and returns to the previous version unless a person keeps it. A change that makes it fire more is a tightening and may ask for less. Bounds are the published ones (for example min_sessions 3 to 100, the rage window_ms 300 to 3,000); the two dead-click windows are fixed so the shadow measurement stays comparable. A suppression ends when its time passes, on the next read, whether or not anything swept it.

POST /orgs/{org}/projects/{project}/replay/detectors and the MCP tool dx_detectors_update take the change and answer applied, or approval_required with a link to the decision; once a person has decided, the same request with the approval's id applies the approved plan once. A change moves the project's friction version, so an approval given to one version is never spent on another: if anyone edits it in between, the retry is refused with TARGET_CHANGED and asks again. Reverting is a new plan: the stored inverse (restore the previous thresholds, cancel the suppression, re-create the cancelled one) goes through the same engine.

dx_detectors_update needs the dx:write scope. Until the SG-059 review is signed off no token an MCP client can obtain carries it, so the tool is not offered; a person with that role in the dashboard's REST API can use the route.

Owners

An ownership rule can name a page: route:/checkout/* @payments in the project's ownership text. A friction issue is matched by its route against route rules only, * being one path segment and ** the rest, so the team that owns the page hears about it. A catch-all file rule (*) never claims a page and a route rule never claims a file.