Heatmaps without session replay

When I said in the introduction post that session replay is a line Tracely won't cross, the obvious follow-up was: so what about heatmaps? Heatmap products are usually built on replay infrastructure — record everything, render the aggregate view from the recordings. Tracely does it the other way around: aggregate at the source, so there's nothing to replay.

A grid, not a recording

When the heatmap toggle is on for a site, the tracker listens for clicks and maps each one onto a 40×40 grid laid over the full document — click coordinates divided by the page's width and height, floored into a cell index from 0 to 39 on each axis. That cell increment is the entire signal. No element selectors, no DOM capture, no coordinates finer than one-fortieth of the page.

The tracker buffers these counts client-side and flushes at most every five seconds (and on tab hide or unload), sending up to 200 cells per batch to the ingest endpoint along with the page's document dimensions. The server stores daily bucket rows: site, path, date, grid cell, hit count, viewport size. Aggregated before it ever leaves the browser, aggregated again at rest.

What the dashboard does with it

The Heatmaps screen lets you pick a path — busiest paths by click volume first — and renders the grid as a heat overlay. You can segment by device class, cut on viewport width: desktop at 1024px and up, tablet from 768 to 1023, mobile below that.

Because the grid spans the full scrollable page, vertical position doubles as scroll-depth signal. The dashboard splits clicks into vertical quarters of the page and, once a path has at least 20 clicks in the window, generates a plain-language insight — for example, that most engagement lands in the top quarter and content lower down gets little interaction, or the opposite: visitors scroll deep and down-page content is pulling its weight. Below the 20-click floor it stays quiet rather than narrating noise.

Retention is bounded by design

Heatmap buckets are the one dataset in Tracely with aggressive, non-negotiable pruning. A scheduled command, tracely:prune-heatmap-buckets, runs daily and deletes bucket rows older than the retention window. The default is 90 days, configurable via TRACELY_HEATMAP_BUCKETS_RETENTION_DAYS (the tracely.heatmap_buckets.retention_days config key) — but the code clamps it to a minimum of 31 days, so a typo in an env file can't silently truncate retention to a week. Heatmaps answer "where do people click on this page lately"; there's no legitimate question that needs cell-level click data from last year.

The backdrop problem

A heat grid over a blank canvas is useless — you need to see the page under it. The replay-based products get this for free from captured DOM. Tracely instead takes a reference snapshot server-side: a queue worker drives headless Chromium (via Browsershot) to the page's public URL and stores a full-page JPEG, captured at a 1365×900 window by default, which the dashboard aligns under the grid.

The important property: the snapshot comes from the server visiting your public page, never from a visitor's browser. Nothing a visitor sees — their session, their account data, their form input — can appear in it. The capture also refuses to run against URLs whose host doesn't belong to the site or that resolve to private network addresses, so the feature can't be bent into fetching something it shouldn't. Click counts and snapshots are independent, too; an authenticated page can have heatmap data with no backdrop, and that's fine.

The result isn't a replay product, and it isn't trying to be — you can see what Tracely deliberately doesn't collect for the fuller version of that argument. It answers the question heatmaps are actually good for — where does attention cluster on this page — with a dataset boring enough to be indefensible to misuse.