Merge branch 'feature/traffic-analytics'

README.md

@@ -171,7 +171,9 @@ for each provider (e.g. `CF_DNS_API_TOKEN` for `cloudflare`); `.env` is the plac
 - Several targets per port: round-robin load balancing with automatic failover.
 - Health checks (TCP connect or an HTTP path); unhealthy targets are skipped and shown in the UI.
 - Conflict detection (same ip/port/protocol, overlapping ranges, or `0.0.0.0` overlapping a specific IP).
-- Traffic totals and a 24-hour sparkline per port.
+- Traffic totals and a 24-hour sparkline per port, plus a **Traffic** chart per resource (and a
+  **Traffic overview** for the whole organization) with bytes in and out, connections and the
+  busiest visitor addresses. See *Traffic analytics* below.
 
 **HTTPS**: automatic Let's Encrypt certificates, optional port-80 redirect, `X-Forwarded-*`
 headers, Host rewrite, HTTPS to the backend, certificate status per port.
@@ -227,6 +229,24 @@ headers, Host rewrite, HTTPS to the backend, certificate status per port.
 - **`/metrics`** (Prometheus) when `HAMMERHEAD_METRICS_TOKEN` is set: edge/site/port/target/mail-check
   gauges, traffic counters, alerts firing. Off (404) otherwise.
 
+**Traffic analytics**
+- Every edge counts connections and bytes in and out per port, plus the ten busiest client addresses
+  per port, and sends them with its regular report (every 20 seconds). Hammerhead adds them up at
+  three resolutions: per minute (kept 48 hours), per hour (31 days) and, for visitor addresses, per
+  hour (7 days). Older rows are deleted by the same hourly clean-up as the logs.
+- The charts are on the Resources page: **Traffic** on a row, or **Traffic overview** for everything.
+  Pick an hour or 6 hours (per minute), a day, a week or a month (per hour). Visitor addresses cover
+  at most the last 7 days, and very small visitors may be missing because each report names ten.
+- `GET /api/orgs/{org}/traffic/{resource id or "all"}?range=1h|6h|24h|7d|30d` returns the series,
+  totals and busiest addresses as JSON, for scripts or your own dashboards.
+- **Traffic alerts** (Alerts → Traffic, per organization, off by default), delivered like every other
+  alert, with the same debounce:
+  - *Spike*: a port carried at least N times its usual traffic in the last 5 minutes, compared with
+    the average over the previous 6 hours. A port needs an hour of history, and the burst must be over
+    10 MB, so quiet ports don't page you.
+  - *Daily amount*: a port carried more than the set number of MB (in plus out) since midnight UTC.
+  Neither blocks traffic; they only tell you.
+
 **Mail egress (send your mail server's outgoing mail from the edge's IP)**
 - Receiving servers judge mail by the IP it comes from: its reverse DNS, your HELO name and your SPF
   record all have to agree. A mail server at home usually can't satisfy that (residential IP, port 25