Usage Statistics¶
User Guide¶
Track page views, downloads, and visitor analytics with geographic data, bot filtering, and comprehensive reporting dashboards.
Overview¶
┌─────────────────────────────────────────────────────────────────────┐
│ USAGE STATISTICS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ VIEWS DOWNLOADS VISITORS GEOGRAPHY │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ Page File Unique Country │
│ Visits Downloads Users Location │
│ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ DASHBOARDS & │ │
│ │ REPORTS │ │
│ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Key Features¶
┌─────────────────────────────────────────────────────────────────────┐
│ STATISTICS FEATURES │
├─────────────────────────────────────────────────────────────────────┤
│ 📊 PAGE VIEW TRACKING │
│ • Automatic tracking of record views │
│ • Track views by repository and item │
│ • Unique visitor counting │
│ │
│ 📥 DOWNLOAD TRACKING │
│ • Track file downloads │
│ • Digital object download counts │
│ • Top downloaded items reports │
│ │
│ 🌍 GEOGRAPHIC DATA │
│ • Visitor location by country │
│ • City-level data (with GeoIP) │
│ • Regional distribution maps │
│ │
│ 🤖 BOT FILTERING │
│ • Automatic bot/spider detection │
│ • 30+ pre-configured patterns │
│ • Custom bot rules │
│ │
│ 📈 DASHBOARDS & REPORTS │
│ • Interactive charts │
│ • Date range filtering │
│ • CSV export for all reports │
│ │
│ ⚡ PRE-AGGREGATION │
│ • Daily and monthly rollups │
│ • Fast dashboard performance │
│ • Configurable retention │
└─────────────────────────────────────────────────────────────────────┘
How to Access¶
Main Navigation¶
Main Menu
│
▼
Admin
│
▼
Statistics ───────────────────────────────────────┐
│ │
├──▶ Dashboard (overview & charts) │
│ │
├──▶ Views (page view trends) │
│ │
├──▶ Downloads (download statistics) │
│ │
├──▶ Top Items (most popular) │
│ │
├──▶ Geographic (visitor locations) │
│ │
└──▶ Settings (configure tracking) │
Dashboard¶
Main Statistics Dashboard¶
┌─────────────────────────────────────────────────────────────────────┐
│ STATISTICS DASHBOARD │
├─────────────────────────────────────────────────────────────────────┤
│ Period: [Last 30 Days ▼] From: [2026-01-01] To: [2026-01-30] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Total Views │ │ Downloads │ │ Visitors │ │
│ │ 24,567 │ │ 3,421 │ │ 8,234 │ │
│ │ ↑ 12.5% │ │ ↑ 8.3% │ │ ↑ 15.2% │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ VIEWS OVER TIME │
│ │
│ 1500│ ╱╲ │
│ │ ╱╲ ╱ ╲ ╱╲ │
│ 1000│ ╱ ╲ ╱ ╲╱ ╲ │
│ │ ╱ ╲ ╱ ╲ │
│ 500│╱ ╲╱ ╲ │
│ │ │
│ 0└────────────────────────────────────── │
│ Jan 1 Jan 15 Jan 30 │
│ │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ TOP 5 ITEMS TOP COUNTRIES │
│ ┌────────────────────────┬───────┐ ┌──────────────┬───────┐ │
│ │ Historical Photos │ 2,341 │ │ South Africa │ 45.2% │ │
│ │ Council Minutes 1950 │ 1,876 │ │ USA │ 18.7% │ │
│ │ Maps Collection │ 1,234 │ │ UK │ 12.3% │ │
│ │ Family Archives │ 987 │ │ Germany │ 5.8% │ │
│ │ Heritage Building │ 654 │ │ Australia │ 4.2% │ │
│ └────────────────────────┴───────┘ └──────────────┴───────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Views Report¶
Viewing Page Statistics¶
Go to Statistics → Views
┌─────────────────────────────────────────────────────────────────────┐
│ VIEWS REPORT │
├─────────────────────────────────────────────────────────────────────┤
│ Period: [2026-01-01] to [2026-01-30] Group by: [Daily ▼] │
│ [Apply] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ VIEWS CHART │ │
│ │ │ │
│ │ ── Total Views ── Unique Visitors │ │
│ │ │ │
│ │ 1200│ │ │
│ │ │ ╱╲ │ │
│ │ 800│ ╱ ╲ ╱╲ │ │
│ │ │ ╱ ╲ ╱ ╲ │ │
│ │ 400│ ╱ ╲__╱ ╲___ │ │
│ │ │ │ │
│ │ 0└──────────────────────────── │ │
│ │ W1 W2 W3 W4 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ DATA TABLE │
│ ┌──────────────┬────────────┬─────────────┐ │
│ │ Period │ Total │ Unique │ │
│ ├──────────────┼────────────┼─────────────┤ │
│ │ 2026-01-01 │ 856 │ 423 │ │
│ │ 2026-01-02 │ 923 │ 512 │ │
│ │ 2026-01-03 │ 1,102 │ 634 │ │
│ │ 2026-01-04 │ 789 │ 401 │ │
│ │ ... │ ... │ ... │ │
│ └──────────────┴────────────┴─────────────┘ │
│ │
│ [Export CSV] │
│ │
└─────────────────────────────────────────────────────────────────────┘
Downloads Report¶
Tracking File Downloads¶
Go to Statistics → Downloads
┌─────────────────────────────────────────────────────────────────────┐
│ DOWNLOADS REPORT │
├─────────────────────────────────────────────────────────────────────┤
│ Period: [2026-01-01] to [2026-01-30] [Apply] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ DOWNLOADS OVER TIME TOP DOWNLOADED ITEMS │
│ ┌────────────────────────┐ ┌──────────────────────────────┐│
│ │ │ │ # Title Downloads ││
│ │ ▓▓ │ ├──────────────────────────────┤│
│ │ ▓▓ ▓▓ │ │ 1 Annual Report.pdf 523 ││
│ │ ▓▓ ▓▓ ▓▓ ▓▓ │ │ 2 Photo Album.zip 412 ││
│ │ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ │ │ 3 Heritage Map.tif 387 ││
│ │ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ │ │ 4 Council Minutes.pdf 298 ││
│ │ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ │ │ 5 Audio Recording.mp3 245 ││
│ └────────────────────────┘ └──────────────────────────────┘│
│ W1 W2 W3 W4 W5 W6 │
│ │
│ [Export CSV] │
│ │
└─────────────────────────────────────────────────────────────────────┘
Top Items Report¶
Most Viewed Records¶
Go to Statistics → Top Items
┌─────────────────────────────────────────────────────────────────────┐
│ TOP ITEMS │
├─────────────────────────────────────────────────────────────────────┤
│ Period: [2026-01-01] to [2026-01-30] │
│ Type: [Views ▼] Limit: [50 ▼] [Apply] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────┬──────────────────────────────────┬────────────┬──────────┐│
│ │ # │ Title │ Repository │ Views ││
│ ├────┼──────────────────────────────────┼────────────┼──────────┤│
│ │ 1 │ Historical Photographs 1920-1950 │ City Arch │ 2,341 ││
│ │ 2 │ Council Minutes Volume 1 │ Muni Arch │ 1,876 ││
│ │ 3 │ Maps of the Cape Colony │ Nat Arch │ 1,234 ││
│ │ 4 │ Smith Family Papers │ Private │ 987 ││
│ │ 5 │ Heritage Building Plans │ City Arch │ 654 ││
│ │ 6 │ Newspaper Clippings Collection │ Library │ 623 ││
│ │ 7 │ Audio Recordings 1960s │ Nat Arch │ 589 ││
│ │ 8 │ Letters and Correspondence │ Private │ 534 ││
│ │ 9 │ Military Records WW2 │ Def Arch │ 478 ││
│ │ 10 │ Church Registers │ Church │ 423 ││
│ └────┴──────────────────────────────────┴────────────┴──────────┘│
│ │
│ Showing 1-10 of 50 [Export CSV] │
│ │
└─────────────────────────────────────────────────────────────────────┘
Geographic Report¶
Visitor Locations¶
Go to Statistics → Geographic
┌─────────────────────────────────────────────────────────────────────┐
│ GEOGRAPHIC STATISTICS │
├─────────────────────────────────────────────────────────────────────┤
│ Period: [2026-01-01] to [2026-01-30] [Apply] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ VISITORS BY COUNTRY │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ South Africa ████████████████████████████████████ 45.2% │ │
│ │ USA █████████████████ 18.7% │ │
│ │ UK ████████████ 12.3% │ │
│ │ Germany █████ 5.8% │ │
│ │ Australia ████ 4.2% │ │
│ │ Netherlands ███ 3.1% │ │
│ │ Canada ██ 2.4% │ │
│ │ France ██ 2.1% │ │
│ │ Other █████ 6.2% │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ DETAILED DATA │
│ ┌────────────────┬────────────┬─────────────┬───────────────────┐│
│ │ Country │ Visitors │ Views │ Downloads ││
│ ├────────────────┼────────────┼─────────────┼───────────────────┤│
│ │ South Africa │ 3,721 │ 11,234 │ 1,543 ││
│ │ USA │ 1,539 │ 4,632 │ 624 ││
│ │ UK │ 1,012 │ 3,045 │ 412 ││
│ │ Germany │ 477 │ 1,432 │ 198 ││
│ │ Australia │ 345 │ 1,038 │ 143 ││
│ └────────────────┴────────────┴─────────────┴───────────────────┘│
│ │
│ [Export CSV] │
│ │
└─────────────────────────────────────────────────────────────────────┘
Note: Geographic data requires MaxMind GeoLite2 database. See Settings for setup.
Repository Statistics¶
Per-Repository Reports¶
Click on any repository name to view detailed statistics:
┌─────────────────────────────────────────────────────────────────────┐
│ REPOSITORY: City Archives │
├─────────────────────────────────────────────────────────────────────┤
│ Period: [2026-01-01] to [2026-01-30] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Total Views │ │ Downloads │ │ Visitors │ │
│ │ 8,456 │ │ 1,234 │ │ 2,567 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ TOP ITEMS IN THIS REPOSITORY │
│ ┌────┬──────────────────────────────────────────┬───────────────┐│
│ │ # │ Title │ Views ││
│ ├────┼──────────────────────────────────────────┼───────────────┤│
│ │ 1 │ Historical Photographs 1920-1950 │ 2,341 ││
│ │ 2 │ Heritage Building Plans │ 654 ││
│ │ 3 │ Street Maps Collection │ 523 ││
│ │ 4 │ Council Correspondence 1940s │ 412 ││
│ │ 5 │ Public Works Documents │ 387 ││
│ └────┴──────────────────────────────────────────┴───────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────┘
Settings¶
Configure Statistics¶
Go to Statistics → Settings
┌─────────────────────────────────────────────────────────────────────┐
│ STATISTICS SETTINGS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ TRACKING OPTIONS │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ☑ Track page views │ │
│ │ ☑ Track downloads │ │
│ │ ☑ Track unique visitors │ │
│ │ ☐ Track search queries │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ BOT FILTERING │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ☑ Enable bot filtering │ │
│ │ ☑ Log filtered requests (for debugging) │ │
│ │ │ │
│ │ [Manage Bot List] (30 patterns configured) │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ PRIVACY │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ☑ Anonymize IP addresses (GDPR compliance) │ │
│ │ Retention: [90 ▼] days for raw events │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ GEOIP │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Database Path: /usr/share/GeoIP/GeoLite2-City.mmdb │ │
│ │ Status: ✓ Installed (Last updated: 2026-01-15) │ │
│ │ │ │
│ │ [Test GeoIP] [Update Database] │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ [Save Settings] │
│ │
└─────────────────────────────────────────────────────────────────────┘
Bot Filtering¶
Managing Bot Patterns¶
Go to Statistics → Settings → Manage Bot List
┌─────────────────────────────────────────────────────────────────────┐
│ BOT FILTER LIST │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ CONFIGURED PATTERNS │
│ ┌──────────────────┬────────────────────────┬──────────┬────────┐│
│ │ Name │ Pattern │ Category │ Status ││
│ ├──────────────────┼────────────────────────┼──────────┼────────┤│
│ │ Googlebot │ Googlebot|googlebot │ Search │ ✓ On ││
│ │ Bingbot │ bingbot|msnbot │ Search │ ✓ On ││
│ │ Yandex │ YandexBot │ Search │ ✓ On ││
│ │ Facebook │ facebookexternalhit │ Social │ ✓ On ││
│ │ Twitter │ Twitterbot │ Social │ ✓ On ││
│ │ Archive.org │ archive.org_bot │ Archive │ ✓ On ││
│ │ SEMrush │ SemrushBot │ SEO │ ✓ On ││
│ │ ... │ ... │ ... │ ... ││
│ └──────────────────┴────────────────────────┴──────────┴────────┘│
│ │
│ ADD NEW PATTERN │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Name: [________________] │ │
│ │ Pattern: [________________] (regex) │ │
│ │ Category: [Crawler ▼] │ │
│ │ │ │
│ │ [Add Pattern] │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Exporting Data¶
CSV Export¶
All reports support CSV export for external analysis:
┌─────────────────────────────────────────────────────────────────────┐
│ EXPORT OPTIONS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Report Type: [Views ▼] │
│ │
│ Date Range: From: [2026-01-01] To: [2026-01-30] │
│ │
│ Group By: ○ Day ○ Week ● Month │
│ │
│ Include: ☑ Total views │
│ ☑ Unique visitors │
│ ☑ Country breakdown │
│ ☐ Item-level detail │
│ │
│ [Download CSV] │
│ │
└─────────────────────────────────────────────────────────────────────┘
CLI Commands¶
Aggregate Statistics¶
# Run all aggregations (recommended for daily cron)
php symfony statistics:aggregate --all
# Daily aggregation only
php symfony statistics:aggregate --daily
# Monthly aggregation
php symfony statistics:aggregate --monthly
# Cleanup old raw events (keep 90 days)
php symfony statistics:aggregate --cleanup --days=90
# Backfill missing daily aggregates (30 days)
php symfony statistics:aggregate --backfill=30
Generate Reports¶
# Summary report (default)
php symfony statistics:report
# Views report
php symfony statistics:report --type=views
# Downloads report
php symfony statistics:report --type=downloads
# Top items report
php symfony statistics:report --type=top_items --limit=100
# Geographic report
php symfony statistics:report --type=geographic
# Custom date range
php symfony statistics:report --start=2026-01-01 --end=2026-01-31
# Export to CSV
php symfony statistics:report --type=views --format=csv --output=/tmp/views.csv
# JSON output
php symfony statistics:report --type=summary --format=json
Cron Setup¶
Recommended Cron Jobs¶
# Aggregate daily statistics at 2am
0 2 * * * cd /usr/share/nginx/archive && php symfony statistics:aggregate --daily
# Monthly aggregation on 1st of month at 3am
0 3 1 * * cd /usr/share/nginx/archive && php symfony statistics:aggregate --monthly
# Weekly cleanup of old raw events (Sunday 4am)
0 4 * * 0 cd /usr/share/nginx/archive && php symfony statistics:aggregate --cleanup
GeoIP Setup¶
Installing MaxMind GeoLite2¶
- Register for a free account:
-
Visit: https://www.maxmind.com/en/geolite2/signup
-
Download the database:
-
Download: GeoLite2-City.mmdb
-
Install the database:
-
Verify in Settings:
- Go to Statistics → Settings
- GeoIP status should show "Installed"
Understanding the Data¶
How Statistics Are Collected¶
┌─────────────────────────────────────────────────────────────────────┐
│ DATA COLLECTION FLOW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ User visits page │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ Bot Check │──── Bot detected ───▶ Event logged but excluded │
│ └──────┬──────┘ │
│ │ Human │
│ ▼ │
│ ┌─────────────┐ │
│ │ GeoIP │──── Look up location from IP │
│ │ Lookup │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ RAW EVENT STORED │ │
│ │ • Object ID, Type │ │
│ │ • IP Address (anonymized if configured) │ │
│ │ • User Agent │ │
│ │ • Country, City │ │
│ │ • Timestamp │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ Nightly aggregation │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ DAILY/MONTHLY AGGREGATES │ │
│ │ • Total views per day/month │ │
│ │ • Unique visitors │ │
│ │ • Per-object totals │ │
│ │ • Per-country totals │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Data Retention¶
┌─────────────────────────────────────────────────────────────────────┐
│ DATA RETENTION │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ RAW EVENTS (ahg_usage_event) │
│ └── Retained: 90 days (configurable) │
│ └── Then: Deleted by cleanup job │
│ │
│ DAILY AGGREGATES (ahg_statistics_daily) │
│ └── Retained: Indefinitely │
│ └── Small footprint, fast queries │
│ │
│ MONTHLY AGGREGATES (ahg_statistics_monthly) │
│ └── Retained: Indefinitely │
│ └── Long-term trend analysis │
│ │
└─────────────────────────────────────────────────────────────────────┘
Troubleshooting¶
| Issue | Solution |
|---|---|
| No statistics showing | Check if tracking is enabled in Settings |
| Bot traffic included | Enable bot filtering, update bot patterns |
| No geographic data | Install MaxMind GeoLite2 database |
| Dashboard slow | Run statistics:aggregate --all to build aggregates |
| Data not current | Ensure daily cron job is running |
| Export fails | Check write permissions on export directory |
Privacy Compliance¶
GDPR/POPIA Features¶
┌─────────────────────────────────────────────────────────────────────┐
│ PRIVACY FEATURES │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ✓ IP Anonymization │
│ • Stores hashed IPs instead of raw addresses │
│ • Cannot be reversed to identify individuals │
│ │
│ ✓ Configurable Retention │
│ • Set how long raw events are kept │
│ • Automatic cleanup via cron job │
│ │
│ ✓ Aggregate-Only Reporting │
│ • Reports show totals, not individual visits │
│ • No personal data in exports │
│ │
│ ✓ Bot Filtering │
│ • Excludes automated traffic │
│ • More accurate human visitor counts │
│ │
└─────────────────────────────────────────────────────────────────────┘
Related Features¶
- Audit Trail - Track who accessed what
- Privacy Plugin - Data subject requests
- Reports Dashboard - General reporting