CodcompassCodcompass
← Back to Blog
DevOps2026-05-12·81 min read

Migrating Off Google Analytics: Umami vs Plausible vs Fathom

By Alan West

Decoupling Analytics: A Practical Guide to Privacy-First Tracking Infrastructure

Current Situation Analysis

Modern web applications accumulate third-party dependencies that silently degrade performance and expand the security attack surface. Analytics tracking is a primary offender. The default implementation of legacy platforms injects heavy runtime libraries, enforces cookie consent workflows, and creates opaque data pipelines that teams rarely audit. This problem is frequently misunderstood because engineering organizations treat analytics as a "set-and-forget" utility rather than a critical infrastructure component.

The reality is that every external script represents a trust boundary. Recent supply chain incidents across the JavaScript ecosystem have demonstrated how compromised packages or third-party CDNs can inject malicious payloads into production environments. When a tracking script loads, it executes in the same origin as your application, granting it access to the DOM, local storage, and network requests. From a performance standpoint, the tax is measurable: legacy tracking libraries routinely exceed 50KB gzipped, while modern privacy-compliant alternatives operate in the 1–2KB range. This difference directly impacts Time to Interactive and Cumulative Layout Shift.

Furthermore, the absence of persistent cookies eliminates mandatory consent banners in GDPR and CCPA jurisdictions. Fewer modal interruptions correlate with reduced bounce rates and improved conversion funnels. Teams that fail to audit their tracking stack are essentially trading security, performance, and user trust for marginal data granularity they rarely utilize in decision-making. The shift toward privacy-first tracking is not merely ideological; it is an architectural optimization that reduces operational overhead, simplifies compliance, and hardens the application against third-party compromise.

WOW Moment: Key Findings

When evaluating tracking architectures, the trade-offs become immediately visible when measuring payload size, data ownership, compliance friction, and operational complexity. The following comparison isolates the core metrics that dictate infrastructure decisions:

Approach Script Payload Data Ownership Compliance Overhead Operational Complexity
Legacy Cloud (GA4) ~50-80 KB Vendor-held High (consent gates) Low (managed)
Managed Privacy Cloud ~1-2 KB Vendor-held Low (cookieless) Low (managed)
Self-Hosted Open Source ~2 KB Self-owned Minimal Medium (infra upkeep)

This finding matters because it reframes analytics from a marketing dependency to an infrastructure choice. The payload reduction directly improves Core Web Vitals. Data ownership shifts liability and eliminates vendor lock-in. Compliance overhead drops significantly when cookies are eliminated at the source. Operational complexity is the only meaningful trade-off for control, and modern container orchestration has reduced that barrier to near-zero. Teams that adopt privacy-first tracking typically report a 15-30% reduction in initial page load time and a measurable decrease in support tickets related to consent management.

Core Solution

Migrating away from legacy analytics requires a structured approach that isolates business logic from provider-specific APIs. The most robust pattern is a facade abstraction that normalizes events, handles routing changes, and provides a single point of configuration.

Step 1: Architect a Unified Tracking Facade

Instead of scattering provider-specific calls throughout the codebase, implement a TypeScript interface that abstracts the underlying SDK. This prevents vendor lock-in and simplifies future migrations.

// analytics-facade.ts
export interface TrackingEvent {
  name: string;
  properties?: Record<string, string | number | boolean>;
}

export interface TrackingProvider {
  trackPageView(path: string): void;
  trackEvent(event: TrackingEvent): void;
  initialize(config: Record<string, unknown>): void;
}

export class AnalyticsFacade {
  private provider: TrackingProvider | null = null;

  constructor(provider: TrackingProvider) {
    this.provider = provider;
  }

  init(config: Record<string, unknown>): void {
    this.provider?.initialize(config);
  }

  recordPageView(path: string): void {
    this.provider?.trackPageView(path);
  }

  recordEvent(name: string, props?: Record<string, unknown>): void {
    this.provider?.trackEvent({ name, properties: props as Record<string, string | number | boolean> });
  }
}

Step 2: Implement Provider Adapters

Each tracking service exposes a different API surface. Adapters translate the facade's normalized calls into provider-specific payloads.

// providers/umami-adapter.ts
declare global {
  interface Window { umami?: { track: (name: string, data?: Record<string, unknown>) => void } }
}

export class UmamiAdapter implements TrackingProvider {
  initialize(config: Record<string, unknown>): void {
    // Configuration is handled via the script tag's data-website-id attribute.
    // No runtime initialization required.
  }

  trackPageView(path: string): void {
    // Umami auto-tracks pageviews, but manual triggers are needed for SPAs
    if (typeof window !== 'undefined' && window.umami) {
      window.umami.track('pageview', { url: path });
    }
  }

  trackEvent(event: TrackingEvent): void {
    if (typeof window !== 'undefined' && window.umami) {
      window.umami.track(event.name, event.properties);
    }
  }
}

Step 3: Integrate with Client-Side Routing

Legacy scripts automatically detect URL changes. Modern single-page applications require explicit hooks. Attach the facade to your router's navigation events.

// router-integration.ts
import { AnalyticsFacade } from './analytics-facade';
import { UmamiAdapter } from './providers/umami-adapter';

const tracker = new AnalyticsFacade(new UmamiAdapter());

// Example: React Router v6 integration
import { useLocation } from 'react-router-dom';
import { useEffect } from 'react';

export function useAnalyticsTracker(tracker: AnalyticsFacade) {
  const location = useLocation();

  useEffect(() => {
    tracker.recordPageView(location.pathname + location.search);
  }, [location, tracker]);
}

Step 4: Deploy Self-Hosted Infrastructure

Self-hosting eliminates third-party trust dependencies and provides full data control. The following architecture uses PostgreSQL for persistence and implements health checks to prevent race conditions during container startup.

# docker-compose.analytics.yml
services:
  analytics-app:
    image: ghcr.io/umami-software/umami:postgresql-latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://analytics_user:${DB_PASSWORD}@analytics-db:5432/analytics_prod
      DATABASE_TYPE: postgresql
      APP_SECRET: ${APP_SECRET}
      TRACKER_SCRIPT_NAME: analytics.js
    depends_on:
      analytics-db:
        condition: service_healthy
    networks:
      - analytics-net

  analytics-db:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: analytics_prod
      POSTGRES_USER: analytics_user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - analytics-pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U analytics_user -d analytics_prod"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - analytics-net

volumes:
  analytics-pgdata:

networks:
  analytics-net:
    driver: bridge

Architecture Rationale:

  • Facade Pattern: Decouples application code from provider APIs. If you switch from Umami to Plausible, only the adapter changes.
  • SPA Routing Hooks: Ensures accurate pageview counts in client-rendered applications where the browser does not perform full reloads.
  • Localhost Binding (127.0.0.1:3000:3000): Prevents direct external access to the dashboard. Traffic must flow through a reverse proxy, enabling TLS termination and rate limiting.
  • Health Checks: Guarantees the database is accepting connections before the application container attempts to initialize, eliminating startup crashes.

Pitfall Guide

1. SPA Navigation Blind Spots

Explanation: Privacy-focused scripts auto-track traditional multi-page applications but miss route changes in React, Vue, or Svelte apps. Relying on default behavior results in underreported traffic. Fix: Explicitly trigger pageview events on router state changes. Use framework-specific navigation guards or location listeners to ensure every virtual route is recorded.

2. Event Schema Drift

Explanation: Each vendor expects different payload structures. Plausible uses a props wrapper, Fathom expects flat strings, and Umami accepts arbitrary objects. Direct find-and-replace migrations break data continuity. Fix: Normalize all events through the facade before dispatch. Map legacy gtag properties to a unified schema, then transform them inside the provider adapter.

3. Content-Security-Policy Breakage

Explanation: Removing legacy domains and introducing new tracking endpoints triggers CSP violations. Browsers block the script, and tracking silently fails. Fix: Audit script-src and connect-src directives. Add the new tracking domain and any required beacon endpoints. Use strict-dynamic or nonces if your application relies on inline scripts.

4. Parallel Tracking Misalignment

Explanation: Running legacy and new tracking simultaneously shows divergent metrics. Privacy tools intentionally filter bot traffic, fingerprinting, and duplicate sessions, causing apparent data loss. Fix: Accept the delta as accurate. Use parallel tracking only for validation, not for historical comparison. Document the filtering behavior to align stakeholder expectations.

5. Database Retention Misconfiguration

Explanation: Self-hosted instances accumulate data indefinitely. Without retention policies, PostgreSQL tables grow unbounded, degrading query performance and increasing storage costs. Fix: Implement automated partitioning or scheduled cleanup jobs. Configure the application's built-in retention settings to archive or delete raw events older than 12-24 months while preserving aggregated metrics.

6. Over-Engineering Server-Side Proxies

Explanation: Teams often build Node.js or Go proxies to forward analytics events, believing it improves privacy or performance. This adds latency, increases infrastructure cost, and duplicates functionality already handled by client-side beacons. Fix: Stick to direct client-to-server communication unless regulatory requirements mandate IP anonymization at the edge. If proxying is necessary, use a lightweight reverse proxy like Nginx or Traefik rather than a custom application layer.

7. Ignoring Bot Filtering

Explanation: Privacy-focused tools rely on client-side heuristics and server-side pattern matching to exclude automated traffic. Misconfigured instances may still log crawler requests, skewing conversion metrics. Fix: Enable built-in bot filtering. Cross-reference traffic spikes with known crawler user agents. Implement server-side IP allowlists if the application is internal-only.

Production Bundle

Action Checklist

  • Audit codebase for legacy tracking calls: Search for gtag, dataLayer, and analytics wrapper functions to establish a migration baseline.
  • Implement a unified tracking facade: Abstract provider APIs behind a TypeScript interface to prevent vendor lock-in.
  • Map custom events to normalized schema: Translate legacy event names and properties into a consistent structure before dispatch.
  • Update Content-Security-Policy headers: Add new tracking domains to script-src and connect-src directives to prevent runtime blocks.
  • Deploy self-hosted instance with health checks: Use Docker Compose with PostgreSQL health probes to ensure reliable startup sequencing.
  • Configure database retention policies: Schedule automated pruning or partitioning to prevent unbounded storage growth.
  • Validate parallel tracking delta: Run both systems for 7-14 days, compare daily pageviews, and document expected filtering differences.
  • Remove legacy scripts and consent banners: Decommission old tracking code and eliminate unnecessary cookie modals after validation.

Decision Matrix

Scenario Recommended Approach Why Cost Impact
Solo developer / side project Self-hosted Umami Zero licensing fees, full data control, MIT license allows unrestricted modification Infrastructure cost only (VPS + storage)
Small business / no DevOps capacity Plausible Cloud Managed hosting, AGPL transparency, cookieless compliance out-of-the-box Monthly subscription (~$9-$29/mo)
Enterprise / strict data residency Self-hosted Umami + Air-gapped DB Complete isolation from third-party networks, customizable retention and encryption Higher operational overhead, no SaaS fees
Marketing-heavy / ad conversion tracking Legacy Cloud (GA4) Required for Google Ads integration, audience building, and cross-platform attribution Free tier available, but high privacy/compliance cost

Configuration Template

// analytics.config.ts
import { AnalyticsFacade } from './analytics-facade';
import { UmamiAdapter } from './providers/umami-adapter';

export const analyticsConfig = {
  provider: new UmamiAdapter(),
  init: (config: Record<string, unknown>) => {
    const facade = new AnalyticsFacade(new UmamiAdapter());
    facade.init(config);
    return facade;
  }
};

// Usage in application entry point
import { analyticsConfig } from './analytics.config';

const tracker = analyticsConfig.init({
  websiteId: process.env.VITE_UMAMI_SITE_ID,
  scriptUrl: process.env.VITE_UMAMI_SCRIPT_URL
});

export default tracker;

# /etc/nginx/conf.d/analytics-proxy.conf
server {
    listen 443 ssl http2;
    server_name analytics.internal.example.com;

    ssl_certificate /etc/letsencrypt/live/analytics.internal.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/analytics.internal.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Rate limiting for dashboard access
        limit_req zone=analytics_dashboard burst=10 nodelay;
    }

    location /script.js {
        proxy_pass http://127.0.0.1:3000/script.js;
        add_header Cache-Control "public, max-age=86400, immutable";
    }
}

Quick Start Guide

  1. Provision infrastructure: Run docker compose -f docker-compose.analytics.yml up -d to start the PostgreSQL and application containers. Verify health status with docker compose ps.
  2. Configure environment variables: Create a .env file containing DB_PASSWORD and APP_SECRET. Generate a cryptographically secure secret using openssl rand -hex 32.
  3. Deploy reverse proxy: Install Nginx or Caddy, apply the provided configuration template, and obtain TLS certificates via Let's Encrypt. Point your subdomain DNS record to the server IP.
  4. Inject tracking script: Add <script defer src="https://analytics.internal.example.com/script.js" data-website-id="YOUR_SITE_ID"></script> to your application's HTML head or framework layout component.
  5. Validate data flow: Open the dashboard at https://analytics.internal.example.com, navigate through your application, and confirm pageviews and custom events appear within 30 seconds.