Repository source: docs/concepts/usage_reports.md
Usage reports
Purpose: Show the operator where people (first of all the operator) take several clicks to reach a place that could be one click away, from logs visitors record in their own browser and choose to upload.
Scenario: With the "Usage reports" flag on (FORUM_USAGE_REPORTS_ENABLED, off by default), a visitor opens Tools → Usage Log and turns recording on. The browser then records each page view and each link or button click: the page kind (route words kept, every other path segment replaced by *, queries dropped), the part of the page clicked, the control's name (its data-tab, data-tone or data-action, else its label cut to 40 characters), the destination page kind for links, form submits, and the seconds between entries. It never reads typed text, keeps at most 2,000 lines from the last 30 days, and records nothing on the Usage Log page itself. The visitor reads the log as sentences or as the exact text, and can copy or clear it, or upload exactly that text. The upload is stored with the signed-in session's username, or anonymously; refusals are 413 (over 100 KB), 400 (not a usage log), 429 (10 uploads per client per hour, with Retry-After), 503 (store over 50 MB, nothing deleted), and 403 cross-site or for non-members on a members-only site. A root operator opens Tools → Usage Reports and sees click counts and journeys: the clicks between stops (a pause of 20 seconds or more, or a form submit), grouped by start and end, with a start and end never seen in one click shown first as a shortcut idea. ?uploader=<username> or ?uploader=anonymous narrows the page to one uploader. Everyone else gets 403. With the flag off, both tools leave the launcher and the Tools bar, the pages return 404, and no recorder script loads.
Sources: recorder (source unavailable), log page script (source unavailable), page kinds (source unavailable), log format (source unavailable), report store (source unavailable), journeys (source unavailable), controller (source unavailable), log page (source unavailable), summary page (source unavailable), browser test (source unavailable), end-to-end test (source unavailable), export exclusion test (source unavailable).
Presentation: both pages use one table of readable names (UsageNames): page kinds become short names ("Thread", "Board", tool names from the Tools registry), and control names drop their hook prefixes ("tab:account" → "You menu", "tool:flags" → "Feature Flags"); anything unlisted shows raw, and every name keeps its raw form on hover. Usage Log opens with a status card and the latest steps as sentences, with "paused" dividers at journey stops; the exact text Upload sends sits behind a "Show exact text" disclosure. Usage Reports shows uploader pills, three tiles, "Shortcut ideas" cards first (from → to, the usual clicks as steps), and Most clicked as a ranked list, in one column on phones. Sources: names (source unavailable).
Storage: reports live only in a private SQLite file, state/private/usage_reports.sqlite3 by default or USAGE_REPORTS_DATABASE_PATH in private config, apart from forum content and private messages. Backup archives take only the content repository's committed tree, and the offline snapshot reads only the public read model, so neither can include reports (content snapshot export). Upload windows hold a SHA-256 of the client's address and user agent, never the raw values, and are pruned after an hour. Reports are kept until an operator removes them; there is no in-app deletion yet.