Echelon Analytics — Privacy-First Web Analytics with WASM Bot Defense

4 min read Original article ↗

Mette-Maya-Marit — the Echelon Analytics seal of approval

Privacy-first, self-hosted web analytics with WebAssembly proof-of-work bot defense. Drop in a single script tag — clean data, no cookie banners, no bot spam.

Get Started GitHub

Why Echelon?

Google Analytics used to be the go-to. Then GA4 happened — bloated, confusing, way too heavy, and full of bot spam that distorts your statistics. Using it feels like opening Microsoft Word when all you want is a text editor. So I built my own for afroute.com and ripped it out when implementing Islets Spatial CMS. One thing led to another and now you're reading the Echelon Analytics site.

Echelon was built as a lightweight alternative for developers who want clean, accurate analytics without the overhead. One script tag, one SQLite file, zero external dependencies.

Why ea.js? →

WASM Bot Defense — Clean Data Without CAPTCHAs

Every tracker script embeds a runtime-generated WebAssembly module that browsers must solve before pageviews are accepted. The WASM blob regenerates from a random seed every 6 hours — each deployment produces unique bytecode that bot toolkits can't pre-compute. Combined with heuristic scoring (0–100), Cloudflare integration, burst detection, and UA blocklists, the result is clean analytics data without CAPTCHAs or third-party bot detection services. Learn more →

Portable Data — Your Analytics, Your Database

All data lives in a single SQLite file. Copy it to your laptop. Query it with DuckDB, Datasette, or any SQLite tool. Back it up with cp. No vendor lock-in, no proprietary formats, no data export requests. Raw visitor data is kept for 90 days alongside daily rollups for 2 years — you can re-analyze with different bot score thresholds at any time. Learn more →

MCP Server — AI Agents Query Your Analytics

A read-only Model Context Protocol server lets Claude Code, Claude Desktop, and other AI agents query your analytics directly. 9 read-only tools for overview, realtime, campaigns, experiments, and dashboard data. No raw SQL, no PII exposure. Ask your AI "how's my site doing?" and it fetches real data. Learn more →

Cookieless by Default

Daily-rotating HMAC hashes identify visitors without cookies. No cross-day tracking, no consent banners needed. GDPR/ePrivacy compliant out of the box.

Live Admin Dashboard

Real-time visitor monitoring, bot management, A/B experiments, UTM campaigns, performance metrics — all with a live stats bar and theming support.

🏷️ "Did you know Core Web Vitals, form submissions, scroll depth, outbound links, and file downloads are all tracked by default? Just add the script tag — no extra attributes needed." -🦭

Quick Start

git clone https://github.com/janit/ea.git
cd ea/echelon-analytics
deno task dev

Add to any site:

<script src="https://your-host/ea.js" data-site="my-site"></script>

That's it. Pageviews, bounces, and sessions are tracked automatically.

What You Get

Tracking

  • Auto-tracked pageviews, bounces, sessions
  • Click, scroll depth, hover, outbound link, and file download tracking
  • Core Web Vitals (LCP, CLS, INP) — on by default
  • Form submission tracking — on by default
  • Custom events: window.echelon.track("name", { key: "value" })
  • UTM campaign tracking with source/medium/content/term breakdown
  • A/B experiment tracking with variant allocation and significance testing
  • SPA-aware — automatic route change detection for React, Vue, Svelte, etc.

Bot Defense

  • Dynamic WASM proof-of-work — randomized every 6 hours, embedded in tracker
  • Heuristic scoring (0–100) — interaction timing, headers, geo, burst detection
  • Cloudflare bot score integration when deployed behind CF
  • Known bot UA blocklist (Googlebot, GPTBot, ClaudeBot, curl, etc.)
  • AI referrer classification (ChatGPT, Claude, Perplexity, Gemini)
  • Per-IP rate limiting on tracking endpoints

Admin Dashboard

  • Live dashboard with Now gauge, 60-minute and 24-hour trend charts
  • Recent visitors and events tables with real-time updates
  • Overview with KPIs, daily trends, top pages, devices, countries, referrers
  • Visitor views listing — filterable, sortable, paginated
  • Semantic events listing with type badges and filtering
  • Bot management with suspicious visitor detection and exclude/include controls
  • A/B experiments — create, manage, view conversion uplift
  • UTM campaigns — track and break down by source, medium, content
  • Performance metrics — CI/CD benchmark tracking with trends
  • Government-inspired design with navy and burgundy palette — built for visual integrity
  • Configurable timezone display for admin timestamps

Tech Stack

  • Runtime: Deno + Fresh 2.2.0 (Preact islands)
  • Database: SQLite via Deno's built-in node:sqlite (WAL mode)
  • Frontend: Preact + @preact/signals, Tailwind CSS v4
  • Build: Vite 7
  • Deploy: Docker-ready (multi-stage, non-root, health check)
docker build -f confs/Dockerfile -t echelon .
docker run -p 1947:1947 -v echelon-data:/app/data echelon

Documentation