tracking prototype

2025-08-13 14:22:40 +02:00
parent 6d2e54e7ad
commit 1546b0d0bc
7 changed files with 649 additions and 0 deletions
--- a/docs/tracking-api.md
+++ b/docs/tracking-api.md
@@ -0,0 +1,164 @@
+# Tracking API Documentation
+
+The tracking service provides analytics about endpoint usage with time-based filtering.
+
+## Authentication
+
+In production, all tracking endpoints require Bearer token authentication:
+```
+Authorization: Bearer <your-api-token>
+```
+
+## Endpoints
+
+### GET /api/tracking/stats
+
+Get endpoint statistics with optional time period filtering.
+
+**Query Parameters:**
+- `period` (optional): `day`, `week`, `month`, `year`, `all` (default: `all`)
+
+**Examples:**
+```bash
+# Get all-time stats
+curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats
+
+# Get last week's stats
+curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats?period=week
+
+# Get last 30 days
+curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats?period=month
+```
+
+**Response:**
+```json
+{
+  "stats": [
+    {
+      "endpoint": "/",
+      "method": "GET",
+      "hit_count": 245,
+      "unique_users": 89,
+      "last_access": "2025-08-13T10:30:00Z",
+      "first_access": "2025-08-06T14:22:00Z"
+    }
+  ],
+  "period": "week",
+  "total_endpoints": 8
+}
+```
+
+### GET /api/tracking/summary
+
+Get overall tracking summary for a time period.
+
+**Query Parameters:**
+- `period` (optional): `day`, `week`, `month`, `year`, `all` (default: `all`)
+
+**Examples:**
+```bash
+# Get today's summary
+curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/summary?period=day
+
+# Get yearly summary
+curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/summary?period=year
+```
+
+**Response:**
+```json
+{
+  "period": "day",
+  "total_hits": 1247,
+  "total_endpoints": 12,
+  "total_unique_users": 234,
+  "oldest_visit": "2025-08-13T00:15:00Z",
+  "newest_visit": "2025-08-13T23:45:00Z",
+  "tracking_active": true
+}
+```
+
+### GET /api/tracking/trends
+
+Get visit trends over time with configurable granularity.
+
+**Query Parameters:**
+- `granularity` (optional): `hour`, `day`, `week`, `month` (default: `day`)
+- `period` (optional): `24h`, `7d`, `30d`, `1y` (default: `7d`)
+
+**Examples:**
+```bash
+# Hourly trends for last 24 hours
+curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=hour&period=24h
+
+# Daily trends for last 30 days
+curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=day&period=30d
+
+# Weekly trends for last year
+curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=week&period=1y
+```
+
+**Response:**
+```json
+{
+  "trends": [
+    {
+      "time_bucket": "2025-08-13",
+      "hits": 567,
+      "unique_users": 123,
+      "unique_endpoints": 8
+    },
+    {
+      "time_bucket": "2025-08-12",
+      "hits": 445,
+      "unique_users": 98,
+      "unique_endpoints": 7
+    }
+  ],
+  "granularity": "day",
+  "period": "7d"
+}
+```
+
+### GET /api/tracking/visits
+
+Get recent individual visits with optional filtering.
+
+**Query Parameters:**
+- `limit` (optional): Number of visits to return (default: `50`)
+
+**Example:**
+```bash
+curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/visits?limit=20
+```
+
+**Response:**
+```json
+{
+  "visits": [
+    {
+      "user_hash": "a1b2c3d4e5f6...",
+      "endpoint": "/boxes",
+      "method": "GET",
+      "ip_address": "192.168.1.100",
+      "user_agent": "Mozilla/5.0...",
+      "referer": "https://google.com",
+      "timestamp": "2025-08-13T15:30:00Z"
+    }
+  ],
+  "count": 20
+}
+```
+
+## Benefits of This Approach
+
+1. **No Duplication**: Single source of truth in `user_visits` table
+2. **Flexible Querying**: Any time period can be queried on-demand
+3. **Rich Analytics**: Detailed trends and user behavior insights
+4. **Efficient Storage**: Only raw visits stored, stats calculated in real-time
+5. **Historical Analysis**: Can analyze any historical period without pre-aggregation
+
+## Performance Considerations
+
+- Indexes are created on `timestamp`, `endpoint`, and `user_hash` for fast queries
+- For very high traffic, consider adding materialized views for common time periods
+- The SQLite database handles thousands of requests efficiently with proper indexing