-
-
Notifications
You must be signed in to change notification settings - Fork 23
Feature Guide Analytics
View traffic metrics, geographic distribution, and blocked request details for your proxy hosts.
The Analytics page (/analytics) provides a real-time view of traffic flowing through your proxy hosts. Data is parsed from Caddy's structured access logs and stored in ClickHouse, a columnar database optimised for fast aggregation over millions of rows. Data is automatically retained for 90 days via ClickHouse TTL.
Key metrics displayed at the top:
- Total requests in the selected time range
- Unique client IPs
- Blocked request percentage (geo blocking + WAF)
- Bytes served
An interactive time-series chart showing request volume over the selected period. The chart splits traffic into allowed and blocked requests so you can spot anomalies.
Select from preset ranges or define a custom window:
| Preset | Window |
|---|---|
| 1h | Last hour |
| 12h | Last 12 hours |
| 24h | Last 24 hours |
| 7d | Last 7 days |
| 30d | Last 30 days |
| Custom | Pick start and end date/time |
An interactive world map showing request volume by country. Countries are colour-coded by traffic density. Click a country to see its request count and breakdown.
Requires MaxMind GeoLite2 databases. See Feature Guide Geo Blocking for GeoIP setup.
Pie chart showing HTTP vs HTTPS request distribution with percentages.
Parsed user agent statistics showing the most common browsers, crawlers, and tools:
- Browsers: Chrome, Firefox, Safari, Edge, Opera, etc.
- Crawlers: Googlebot, Bingbot, etc.
- Tools: curl, Python requests, wget, etc.
A paginated table of blocked requests showing:
- Timestamp
- Client IP and country
- Requested host and URI
- Block reason (geo blocking or WAF rule)
This combines data from both the geo blocker and the WAF.
Select one or more proxy hosts to scope the analytics view. By default, all hosts are included.
All charts and tables update when you change the time range. The selected range is preserved in the URL for bookmarking.
Analytics uses a dedicated ClickHouse container for storage. The log parser reads Caddy's access logs every 30 seconds and inserts events into ClickHouse. All analytics API queries run against ClickHouse, keeping the main SQLite database free for application config and auth.
| Component | Storage |
|---|---|
| Traffic events | ClickHouse (traffic_events) |
| WAF events | ClickHouse (waf_events) |
| Log parser state (file offsets) | SQLite |
| App config, users, proxy hosts | SQLite |
Data retention: 90 days, enforced automatically by ClickHouse TTL. No manual cleanup needed.
Configuration: Set CLICKHOUSE_PASSWORD in your .env file. See Environment Variables Reference#ClickHouse Analytics for all options.
ClickHouse is optional and controlled via the clickhouse Docker Compose profile. It is enabled by default in .env.example.
Add to your .env:
COMPOSE_PROFILES=clickhouse
CLICKHOUSE_PASSWORD=your-clickhouse-password # openssl rand -base64 32Then start (or restart) the stack:
docker compose up -dRemove clickhouse from COMPOSE_PROFILES (or leave the variable unset). The web container starts normally without ClickHouse. The Analytics page will show a banner explaining that ClickHouse is not enabled and how to enable it.
When analytics is disabled, the logging-disabled banner on the Proxy Hosts page is also suppressed — there is no point warning about logging if there is nowhere to store the data.
To enable both analytics and automatic GeoIP updates:
COMPOSE_PROFILES=clickhouse,geoipupdate
CLICKHOUSE_PASSWORD=your-clickhouse-password
GEOIPUPDATE_ACCOUNT_ID=your-account-id
GEOIPUPDATE_LICENSE_KEY=your-license-key- Feature Guide WAF
- Feature Guide Geo Blocking
- Feature Guide Proxy Hosts
- Environment Variables Reference
Need help? Open an issue with details about what you expected to see.