How it Works

TinyPixel’s design is inspired by Fathom Analytics but provides more flexibility with controlling how frequently visitor data is cycled for privacy purposes.

# Data Flow: From Tracking to Insights

# 1. Data Collection

When a visitor loads a page on your tracked site, the TinyPixel tracking script collects basic analytics data:

• Page views: The page URL (hostname and pathname)
• Visitor identification: A hashed visitor ID (salted for privacy)
• Metadata: Browser type, device category, referrer, country (from IP)

This data is sent to your TinyPixel instance and stored in the ingestion database for processing.

# 2. Aggregation Pipeline

Raw events in the ingestion database are periodically aggregated into three time-based summary tables:

Granularity	Time Column	Update Frequency	Use Case
Hourly	time_bucket (datetime)	Every hour	Real-time trends and recent activity
Daily	date (date)	Daily (typically overnight)	Daily performance metrics
Weekly	week_start (date)	Weekly (typically Sunday)	Week-over-week comparisons and trends

Aggregation transforms raw page view data into summarized metrics, reducing storage requirements and enabling fast dashboard queries.

# 3. Dimension Analysis

Each aggregation includes breakdowns by visitor segments (dimensions):

• Global: Overall site statistics
• Country: Geographic breakdown (based on visitor IP)
• Browser: Browser type (Chrome, Firefox, Safari, etc.)
• Device Type: Desktop, mobile, or tablet
• Referrer Hostname: Referring domain for traffic source analysis

For example, a single aggregation period generates separate records for global stats, stats per country, stats per browser, and so on—enabling flexible filtering and comparison in the dashboard.

# Analytics Metrics

TinyPixel calculates the following metrics for each aggregation:

# Core Metrics

Metric	Description	Interpretation
Page Views	Raw count of every page load	Total page visits, including repeat visitors
Unique Pageviews	First view of a pathname per visitor (within salt cycle)	Number of distinct visitors to each page
Visits	Distinct visitors identified in the period	Total number of unique visitor sessions
Sessions	Activity periods separated by inactivity	Number of distinct browsing sessions (resets after 30 minutes of inactivity by default)
Bounced Count	Single-page sessions	Visitors who viewed only one page
Total Duration	Sum of time spent on page (in seconds)	Cumulative engagement time
Duration Count	Number of pageviews with duration data	Count of events with timing information

# Derived Metrics

• Average Duration = Total Duration ÷ Duration Count
• Bounce Rate = (Bounced Count ÷ Pageviews) × 100%

# Privacy: Salt Cycling and Visitor Hashing

TinyPixel maintains visitor privacy through a salting mechanism that periodically “forgets” visitor identities:

# How Salt Cycling Works

Each site has a configurable salt—a random value used to hash visitor identifiers. When the salt changes, visitors appear as new to the system because their hashed identifiers no longer match. This achieves privacy by preventing indefinite tracking of individuals.

You can configure your site’s salt rotation frequency to one of three options:

Duration	Rotation Cycle	Privacy Level	Accuracy Impact
Daily	Every 24 hours	Highest privacy	Lower accuracy for unique visitors; granular tracking impossible
Weekly	Every 7 days	Balanced	Good balance of privacy and accuracy; suitable for most use cases
Monthly	Every 30 days	Lowest privacy	Highest accuracy for trends; longer windows for understanding behavior

# Privacy vs. Accuracy Tradeoff

Shorter salt durations (daily):

• ✅ Stronger privacy—visitors cannot be tracked over extended periods
• ❌ Less accurate unique visitor counts—a single person appears as different visitors on different days
• ❌ Week-over-week comparisons are less reliable

Longer salt durations (weekly or monthly):

• ✅ More accurate analytics—the same visitor is recognized across multiple days/weeks
• ✅ Reliable trend analysis and growth metrics
• ❌ Weaker privacy—visitor behavior can be tracked for the duration of the salt

# Recommended Configuration

For most websites, weekly salt rotation strikes a good balance:

• Visitors can be recognized within a week, enabling accurate daily and weekly metrics
• Privacy is protected by re-hashing every 7 days
• Analysis of multi-day trends and campaigns becomes possible
• Long-term visitor tracking is prevented

Choose daily rotation if:

• Privacy is your absolute priority
• You only need high-level daily snapshots
• You’re analyzing traffic for compliance purposes

Choose monthly rotation if:

• You want the most accurate long-term analytics
• You’re running long-running campaigns or analyzing monthly trends
• Your visitors typically don’t expect strong privacy guarantees

# Data Retention and Cleanup

Analytics data is automatically cleaned up based on your configured retention policy. By default, TinyPixel retains statistics for 12 months. You can adjust this in your site settings to balance storage requirements with your analysis needs.

When the retention period expires:

• Hourly, daily, and weekly aggregates older than the cutoff are deleted
• Raw ingestion data (page views and visitors) is purged
• Storage usage remains bounded and predictable

# Admin Interface

System administrators manage site configuration, user access, and global settings through the admin panel. The admin interface is protected by HTTP Basic Auth and derived from your Rails secret key. See System Admin Guide for complete admin documentation.

---

For information about deploying and configuring TinyPixel, see Configuration.

# Architecture Overview

TinyPixel uses a dual-database architecture optimized for data collection and aggregation:

# Primary Database

The primary SQLite database stores all site configuration, user accounts, aggregated analytics, and system data. This database is designed for reads and queries, serving all dashboard requests and API endpoints.

# Ingestion Database

A separate SQLite database (ingestion.sqlite3) handles high-velocity analytics data collection. This database stores raw tracking events (pixel requests, page views, and visitor sessions) with minimal overhead. By separating collection from aggregation, TinyPixel can:

• Efficiently handle high-throughput tracking events
• Prevent write contention that could slow down dashboard queries
• Scale data collection independently from the analytics interface
• Provide clear separation of concerns between ingestion and analysis pipelines