Spec

Analytics

Counts page views by country so I can see where traffic comes from. Admin-only page at /admin/analytics (a link from the admin page and the menu).

What is recorded

One row per page view: when, which page, and the two-letter country code. Nothing else. No IP address, user agent, cookie or visitor id is stored, so a row cannot be tied to a person or used to follow a visitor between pages.

The country comes from the visitor's IP address, looked up in a local GeoIP file (DB-IP "IP to Country Lite", a free monthly download) and then discarded. When the country can't be worked out, the row says ?? and the page shows "Unknown".

What counts

Page views reported by the page itself: js/visit.js posts to api/visit once a page has loaded in a browser (and after each in-page navigation), and the server counts the page in that request's Referer, without its language prefix. Bots that fetch pages without running JavaScript, most of them, even the ones claiming to be a browser, are never counted. (Until 2026-11-19 every page served was counted, so earlier numbers are mostly bots.)

Not counted either: reports from another site (the browser's Sec-Fetch-Site must be same-origin, and the Referer on this host), the login, registration, members and admin pages, anything with a bot-like user agent (headless browsers, monitors), and the signed-in admin's own visits. Each address can report 120 views a minute at most.

How it works

  • A small middleware (VisitAnalyticsMiddleware) runs after each request and drops the visit in a queue. A background service (VisitRecorder) writes the queue to the Visits table in batches, so a page never waits on the database. If the queue is ever full, extra visits are dropped instead of slowing visitors down.
  • CountryResolver does the lookup. It can also trust a country header from a proxy (Analytics:CountryHeader, for example CF-IPCountry behind Cloudflare), which is off unless configured.
  • AnalyticsReader runs the queries for the page and checks the Admin role on every call, like time tracking.
  • The Visits table is created by SchemaUpgrades with idempotent SQL, because EnsureCreated does not add tables to a database that already exists.

The page

Pick a period (7, 30, 90 days or 12 months). It shows the total, views by country with a share and a bar, the top 15 pages, and a per-day total (UTC days). The page credits DB-IP.com, which its licence requires.

Running it

  • Production: make geoip in stacks/jonathanmccaffrey downloads the GeoIP file; the compose file mounts it. Run it monthly, then restart the app.
  • Locally: with no GeoIP file configured every visit shows as Unknown. To see real countries, download the file and set Analytics:GeoIpDatabase to its path with dotnet user-secrets.

Not done yet

  • Old rows are never deleted. If the table grows large, add a monthly roll-up and delete the raw rows.
  • Referrers, devices and unique visitors are deliberately not tracked.