Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(wordpress): per-site traffic + error analytics (#25)

Juan Denis484aeb575a25
diff --git a/backend/app/api/wordpress.py b/backend/app/api/wordpress.py
index d2fd017e..a7e3693b 100644
--- a/backend/app/api/wordpress.py
+++ b/backend/app/api/wordpress.py
@@ -498,6 +498,23 @@ def detach_site_status_page(app_id):
return jsonify({'success': True, 'removed': removed}), 200
+@wordpress_bp.route('/sites/<int:app_id>/analytics', methods=['GET'])
+@jwt_required()
+def get_site_analytics(app_id):
+ """Per-site traffic + error analytics, parsed on-demand from the container's
+ Apache access log (visits / bandwidth / status codes / 404s / bots / top URLs)."""
+ from app.services.wp_analytics_service import WpAnalyticsService
+ current_user_id = get_jwt_identity()
+ user = User.query.get(current_user_id)
+ app = _resolve_app(app_id)
+ if not app:
+ return jsonify({'error': 'Application not found'}), 404
+ if user.role != 'admin' and app.user_id != current_user_id:
+ return jsonify({'error': 'Access denied'}), 403
+ result = WpAnalyticsService.get_traffic(app.name, request.args.get('hours', 24))
+ return jsonify(result), 200
+
+
@wordpress_bp.route('/sites/<int:app_id>/info', methods=['GET'])
@jwt_required()
def get_wordpress_info(app_id):
diff --git a/backend/app/services/wp_analytics_service.py b/backend/app/services/wp_analytics_service.py
new file mode 100644
index 00000000..1c1427a3
--- /dev/null
+++ b/backend/app/services/wp_analytics_service.py
@@ -0,0 +1,182 @@
+"""Per-site WordPress traffic + error analytics (#25).
+
+Docker-correct: managed WP sites are official ``wordpress:*-apache`` containers
+that send the Apache *combined* access log to the container's stdout, so
+``docker logs <container>`` is the source (the in-container access.log is a
+symlink to stdout — exec-cat'ing it yields nothing). Analytics is computed
+**on demand** over a recent window; there is no separate store, so history is
+bounded by the container's retained log (it resets when the container is
+recreated, e.g. on a PHP-version switch — see #24).
+
+Intentionally NOT derived from the default access log (deferred):
+- PHP fatals — need ``wp-content/debug.log``, which only exists once WP_DEBUG_LOG
+ is enabled (the per-site WP_DEBUG toggle is #30).
+- per-request response time / slow pages — need a ``%D`` LogFormat the official
+ image does not emit.
+- cache hit ratio — a cache-plugin concern surfaced by #22/#23, not the access log.
+"""
+
+import re
+import subprocess
+from collections import Counter
+from datetime import datetime, timedelta, timezone
+
+
+# Apache "combined" CustomLog (the official wordpress:*-apache default to stdout):
+# %h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i"
+_ACCESS_RE = re.compile(
+ r'^(?P<ip>\S+) \S+ \S+ \[(?P<time>[^\]]+)\] '
+ r'"(?P<request>[^"]*)" (?P<status>\d{3}) (?P<bytes>\S+) '
+ r'"(?P<referer>[^"]*)" "(?P<ua>[^"]*)"'
+)
+_BOT_RE = re.compile(
+ r'bot|crawl|spider|slurp|mediapartners|facebookexternalhit|embedly|bingpreview|monitor|wget|curl|python-requests',
+ re.IGNORECASE,
+)
+_APACHE_TIME_FMT = '%d/%b/%Y:%H:%M:%S %z'
+
+
+class WpAnalyticsService:
+ """On-demand per-site traffic/error analytics from the apache access log."""
+
+ MAX_HOURS = 168 # cap the window at 7 days
+ TAIL_CAP = 20000 # cap the docker-logs pull so a busy site can't blow up memory
+ LOG_TIMEOUT = 15 # seconds; bound the synchronous docker-logs pull (single-worker safety)
+
+ @classmethod
+ def get_traffic(cls, container_name, hours=24):
+ try:
+ hours = int(hours)
+ except (TypeError, ValueError):
+ hours = 24
+ hours = max(1, min(hours, cls.MAX_HOURS))
+
+ result = cls._empty(hours)
+ if not container_name:
+ result['note'] = 'No container is resolved for this site.'
+ return result
+
+ # Pull the access log straight from the container's stdout with a hard
+ # timeout so a busy site / hung daemon can't block the (single) worker.
+ # Reading only stdout cleanly separates the access log from the error_log
+ # (which Apache sends to stderr).
+ try:
+ proc = subprocess.run(
+ ['docker', 'logs', '--tail', str(cls.TAIL_CAP), '--since', f'{hours}h', container_name],
+ capture_output=True, text=True, timeout=cls.LOG_TIMEOUT,
+ )
+ except subprocess.TimeoutExpired:
+ result['note'] = 'Traffic log timed out — the site may be under heavy load; try a shorter window.'
+ return result
+ except (FileNotFoundError, OSError):
+ result['note'] = 'Traffic log is unavailable on this host (Docker is not reachable).'
+ return result
+
+ if proc.returncode != 0:
+ # e.g. "Error: No such container" — stopped / removed / on a remote agent.
+ result['note'] = 'Traffic log is unavailable — the container may be stopped or running on another host.'
+ return result
+
+ lines = (proc.stdout or '').splitlines()
+
+ # Pre-seed continuous hourly buckets so the chart x-axis has no gaps.
+ now_hour = datetime.now(timezone.utc).replace(minute=0, second=0, microsecond=0)
+ buckets = {now_hour - timedelta(hours=i): {'requests': 0, 'errors': 0}
+ for i in range(hours, -1, -1)}
+
+ ips = set()
+ total = 0
+ bytes_total = 0
+ bots = 0
+ not_found = 0
+ status_buckets = {'2xx': 0, '3xx': 0, '4xx': 0, '5xx': 0}
+ paths = Counter()
+
+ for raw in lines:
+ m = _ACCESS_RE.match(raw.strip())
+ if not m:
+ continue # error_log / PHP / non-access lines won't match
+ status = int(m.group('status'))
+ total += 1
+ ips.add(m.group('ip'))
+
+ b = m.group('bytes')
+ if b.isdigit():
+ bytes_total += int(b)
+
+ bucket = f'{status // 100}xx'
+ if bucket in status_buckets:
+ status_buckets[bucket] += 1
+ if status == 404:
+ not_found += 1
+ if _BOT_RE.search(m.group('ua')):
+ bots += 1
+
+ req_parts = m.group('request').split(' ')
+ path = req_parts[1] if len(req_parts) >= 2 else m.group('request')
+ paths[path.split('?', 1)[0]] += 1 # group by route; drop query strings (may carry tokens)
+
+ try:
+ t = datetime.strptime(m.group('time'), _APACHE_TIME_FMT).astimezone(timezone.utc)
+ hk = t.replace(minute=0, second=0, microsecond=0)
+ if hk in buckets:
+ buckets[hk]['requests'] += 1
+ if status >= 400:
+ buckets[hk]['errors'] += 1
+ except (ValueError, OverflowError):
+ pass
+
+ if total == 0:
+ result['note'] = (
+ f'No requests recorded in the last {hours}h — the site may be idle, '
+ 'stopped, or recently recreated (the access log resets on recreate).'
+ )
+ return result
+
+ errors = status_buckets['4xx'] + status_buckets['5xx']
+ result.update({
+ 'requests': total,
+ 'unique_visitors': len(ips),
+ 'bytes': bytes_total,
+ 'bytes_human': cls._human_bytes(bytes_total),
+ 'status': status_buckets,
+ 'not_found': not_found,
+ 'bot_requests': bots,
+ 'bot_pct': round(bots / total * 100, 1),
+ 'error_rate': round(errors / total * 100, 1),
+ 'top_paths': [{'path': p, 'count': c} for p, c in paths.most_common(10)],
+ 'series': [{'hour': k.isoformat(), 'requests': v['requests'], 'errors': v['errors']}
+ for k, v in sorted(buckets.items())],
+ 'note': None,
+ })
+ return result
+
+ @classmethod
+ def _empty(cls, hours):
+ now_hour = datetime.now(timezone.utc).replace(minute=0, second=0, microsecond=0)
+ series = [{'hour': (now_hour - timedelta(hours=i)).isoformat(), 'requests': 0, 'errors': 0}
+ for i in range(hours, -1, -1)]
+ return {
+ 'success': True,
+ 'window_hours': hours,
+ 'requests': 0,
+ 'unique_visitors': 0,
+ 'bytes': 0,
+ 'bytes_human': '0 B',
+ 'status': {'2xx': 0, '3xx': 0, '4xx': 0, '5xx': 0},
+ 'not_found': 0,
+ 'bot_requests': 0,
+ 'bot_pct': 0.0,
+ 'error_rate': 0.0,
+ 'top_paths': [],
+ 'series': series,
+ 'note': None,
+ }
+
+ @staticmethod
+ def _human_bytes(n):
+ size = float(n)
+ for unit in ('B', 'KB', 'MB', 'GB', 'TB'):
+ if size < 1024 or unit == 'TB':
+ return f'{size:.0f} {unit}' if unit == 'B' else f'{size:.1f} {unit}'
+ size /= 1024
diff --git a/docs/WORDPRESS_ROADMAP.md b/docs/WORDPRESS_ROADMAP.md
index c224e2e7..361ab820 100644
--- a/docs/WORDPRESS_ROADMAP.md
+++ b/docs/WORDPRESS_ROADMAP.md
@@ -229,11 +229,12 @@ The headline value of a managed platform, and the most net-new — but it leans
- **Reuse:** `php_service`, `system.js`.
- **Done when:** A site's PHP version and limits are editable per environment.
-### #25 — Per-site traffic / error / cache analytics `[L]` ❌
+### #25 — Per-site traffic / error / cache analytics `[L]` ❌ — ✅ Done (Docker-correct: on-demand apache access-log analytics; PHP-fatals / response-time / cache-ratio deferred)
- **Today:** All metrics are host/agent-keyed; API analytics covers only ServerKit's own API. No per-site visits/bandwidth/5xx/404/PHP-fatal.
- **Do:** An nginx access/error + `wp-content/debug.log` ingest pipeline keyed to each WP vhost → visits, bandwidth, bot %, top URLs, 5xx/404, PHP fatals, slow pages, cache hit ratio.
- **Reuse:** the existing log-tail / `metrics_history_service` aggregation patterns.
- **Done when:** The site dashboard shows per-site traffic and error analytics.
+- **Landed:** **Architectural pivot** — managed WP sites are `wordpress:*-apache` containers on `localhost:PORT` with **no per-site nginx**, so the roadmap's "nginx access log" premise doesn't hold; the official image symlinks Apache's access log to the container's **stdout**, making `docker logs` the Docker-correct source. New `WpAnalyticsService.get_traffic(container_name, hours)` pulls `docker logs --tail 20000 --since <h>` (**hard 15s timeout**, reads only **stdout** to separate the access log from the stderr error_log, `returncode`-checked so stopped/missing/remote-agent containers degrade to an accurate note) and parses the Apache *combined* log **on-demand** — no store / collector / migration. It returns requests, unique visitors, bandwidth, status distribution (2xx/3xx/4xx/5xx), 404s, bot %, error rate, top URLs (grouped by route — query strings stripped so visitor tokens aren't surfaced), and a continuous hourly requests/errors series. Route `GET /sites/<id>/analytics?hours=` (owner/admin-guarded), client `getSiteAnalytics`, and a new **Analytics tab** on the site detail (stat cards + a recharts requests/errors AreaChart + status codes + Top URLs) with graceful empty/timeout/unavailable states. This also supplies the 5xx/error-rate signal **#27**'s "error spike" rule needs. *(Deferred — not derivable from the default access log: **PHP fatals** need `wp-content/debug.log` via a WP_DEBUG toggle (#30); **response time / slow pages** need a `%D` LogFormat the official image doesn't emit; **cache hit ratio** is a cache-plugin concern (#22/#23). History is point-in-time over the retained container log (resets on container recreate) — a persistent time-series collector on the `metrics_history` pattern is a clean follow-up.)* Verified: backend `py_compile`, frontend lint-clean + production build, a 3-lens adversarial review (major fixed: docker-logs timeout + memory cap; minor: accurate unavailable note via `returncode`; query-string token stripping). Not runtime-exercised on a real Docker host (Windows dev).
### #26 — Per-site uptime + auto-incidents `[M]` 🟡 — ✅ Done (server-side health poller → bound status-page component with a real uptime % + auto-open/resolve incidents)
- **Today:** Status pages / uptime have no FK to a WP site; components are hand-typed with arbitrary `check_target`; `EnvironmentHealthService` outages don't open incidents.
diff --git a/frontend/src/pages/WordPressDetail.jsx b/frontend/src/pages/WordPressDetail.jsx
index da07439f..d9bbf0c1 100644
--- a/frontend/src/pages/WordPressDetail.jsx
+++ b/frontend/src/pages/WordPressDetail.jsx
@@ -1,6 +1,7 @@
import React, { useState, useEffect } from 'react';
import { useParams, useNavigate, Link } from 'react-router-dom';
-import { ExternalLink, Settings, RefreshCw, Plus, Database, GitBranch, Package, Palette, Archive, Trash2, Replace, ShieldCheck, FolderOpen, FileText, Lock, Copy, Zap, Activity, Globe, Layers } from 'lucide-react';
+import { ExternalLink, Settings, RefreshCw, Plus, Database, GitBranch, Package, Palette, Archive, Trash2, Replace, ShieldCheck, FolderOpen, FileText, Lock, Copy, Zap, Activity, Globe, Layers, BarChart3 } from 'lucide-react';
+import { ResponsiveContainer, AreaChart, Area, XAxis, YAxis, CartesianGrid, Tooltip } from 'recharts';
import useTabParam from '../hooks/useTabParam';
import wordpressApi from '../services/wordpress';
import api from '../services/api';
@@ -71,7 +72,7 @@ const DetailPageSkeleton = () => (
</div>
);
-const VALID_TABS = ['overview', 'environments', 'database', 'plugins', 'themes', 'php', 'git', 'backups', 'uptime'];
+const VALID_TABS = ['overview', 'environments', 'database', 'plugins', 'themes', 'php', 'git', 'backups', 'uptime', 'analytics'];
const WordPressDetail = () => {
const { id } = useParams();
@@ -348,6 +349,12 @@ const WordPressDetail = () => {
>
<Activity size={14} /> Uptime
</div>
+ <div
+ className={`app-detail-tab ${activeTab === 'analytics' ? 'active' : ''}`}
+ onClick={() => setActiveTab('analytics')}
+ >
+ <BarChart3 size={14} /> Analytics
+ </div>
</div>
{/* Clone Site Modal */}
@@ -392,6 +399,7 @@ const WordPressDetail = () => {
{activeTab === 'git' && <GitTab siteId={site.id} site={site} onUpdate={loadSite} />}
{activeTab === 'backups' && <BackupsTab siteId={site.id} />}
{activeTab === 'uptime' && <UptimeTab siteId={site.id} />}
+ {activeTab === 'analytics' && <AnalyticsTab siteId={site.id} />}
</ErrorBoundary>
</div>
</div>
@@ -624,6 +632,124 @@ const UptimeTab = ({ siteId }) => {
);
};
+// Analytics Tab — per-site traffic + error analytics (#25), parsed on-demand from
+// the apache container access log. PHP fatals, response time, and cache hit ratio
+// are not in the default access log (deferred to #30 / #22-#23).
+const ANALYTICS_PERIODS = [{ label: '24h', hours: 24 }, { label: '7d', hours: 168 }];
+
+const AnalyticsTab = ({ siteId }) => {
+ const toast = useToast();
+ const [data, setData] = useState(null);
+ const [loading, setLoading] = useState(true);
+ const [hours, setHours] = useState(24);
+
+ const load = React.useCallback(async () => {
+ setLoading(true);
+ try {
+ const res = await wordpressApi.getSiteAnalytics(siteId, hours);
+ setData(res);
+ } catch (err) {
+ toast.error(err.message || 'Failed to load analytics');
+ } finally {
+ setLoading(false);
+ }
+ }, [siteId, hours, toast]);
+
+ useEffect(() => { load(); }, [load]);
+
+ if (loading) return <div className="tab-loading"><p className="hint">Loading analytics...</p></div>;
+
+ const fmtHour = (iso) => {
+ const d = new Date(iso);
+ return hours <= 24
+ ? d.toLocaleTimeString([], { hour: '2-digit', hour12: false })
+ : d.toLocaleDateString([], { month: 'short', day: 'numeric' });
+ };
+ const clip = (p) => (p && p.length > 48 ? `${p.slice(0, 48)}…` : p);
+ const s = data?.status || {};
+
+ return (
+ <div className="app-overview-grid">
+ <div className="app-overview-left">
+ <div className="app-panel">
+ <div className="app-panel-header">Traffic ({hours <= 24 ? 'last 24 hours' : 'last 7 days'})</div>
+ <div className="app-panel-body">
+ <div className="app-detail-actions">
+ {ANALYTICS_PERIODS.map(p => (
+ <Button key={p.hours} variant={hours === p.hours ? 'default' : 'outline'} size="sm" onClick={() => setHours(p.hours)}>{p.label}</Button>
+ ))}
+ </div>
+ {data?.note && <p className="hint">{data.note}</p>}
+ <div className="app-info-grid">
+ <div className="app-info-item"><span className="app-info-label">Requests</span><span className="app-info-value">{(data?.requests ?? 0).toLocaleString()}</span></div>
+ <div className="app-info-item"><span className="app-info-label">Unique Visitors</span><span className="app-info-value">{(data?.unique_visitors ?? 0).toLocaleString()}</span></div>
+ <div className="app-info-item"><span className="app-info-label">Bandwidth</span><span className="app-info-value">{data?.bytes_human || '0 B'}</span></div>
+ <div className="app-info-item"><span className="app-info-label">Error Rate</span><span className="app-info-value">{data?.error_rate ?? 0}%</span></div>
+ <div className="app-info-item"><span className="app-info-label">Bot Traffic</span><span className="app-info-value">{data?.bot_pct ?? 0}%</span></div>
+ <div className="app-info-item"><span className="app-info-label">404s</span><span className="app-info-value">{(data?.not_found ?? 0).toLocaleString()}</span></div>
+ </div>
+ </div>
+ </div>
+
+ <div className="app-panel">
+ <div className="app-panel-header">Requests over time</div>
+ <div className="app-panel-body">
+ <ResponsiveContainer width="100%" height={220}>
+ <AreaChart data={data?.series || []} margin={{ top: 8, right: 8, left: -16, bottom: 0 }}>
+ <defs>
+ <linearGradient id="wpReq" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="5%" stopColor="#6366f1" stopOpacity={0.4} />
+ <stop offset="95%" stopColor="#6366f1" stopOpacity={0} />
+ </linearGradient>
+ <linearGradient id="wpErr" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="5%" stopColor="#ef4444" stopOpacity={0.4} />
+ <stop offset="95%" stopColor="#ef4444" stopOpacity={0} />
+ </linearGradient>
+ </defs>
+ <CartesianGrid strokeDasharray="3 3" stroke="#888" strokeOpacity={0.15} />
+ <XAxis dataKey="hour" tickFormatter={fmtHour} tick={{ fontSize: 11, fill: '#888' }} minTickGap={24} />
+ <YAxis allowDecimals={false} tick={{ fontSize: 11, fill: '#888' }} width={36} />
+ <Tooltip labelFormatter={fmtHour} />
+ <Area type="monotone" dataKey="requests" name="Requests" stroke="#6366f1" fill="url(#wpReq)" strokeWidth={2} />
+ <Area type="monotone" dataKey="errors" name="Errors" stroke="#ef4444" fill="url(#wpErr)" strokeWidth={2} />
+ </AreaChart>
+ </ResponsiveContainer>
+ </div>
+ </div>
+
+ <div className="app-panel">
+ <div className="app-panel-header">Status codes</div>
+ <div className="app-panel-body">
+ <div className="app-info-grid">
+ <div className="app-info-item"><span className="app-info-label">2xx</span><span className="app-info-value">{(s['2xx'] ?? 0).toLocaleString()}</span></div>
+ <div className="app-info-item"><span className="app-info-label">3xx</span><span className="app-info-value">{(s['3xx'] ?? 0).toLocaleString()}</span></div>
+ <div className="app-info-item"><span className="app-info-label">4xx</span><span className="app-info-value">{(s['4xx'] ?? 0).toLocaleString()}</span></div>
+ <div className="app-info-item"><span className="app-info-label">5xx</span><span className="app-info-value">{(s['5xx'] ?? 0).toLocaleString()}</span></div>
+ </div>
+ </div>
+ </div>
+
+ {data?.top_paths?.length > 0 && (
+ <div className="app-panel">
+ <div className="app-panel-header">Top URLs</div>
+ <div className="app-panel-body">
+ <div className="app-info-grid">
+ {data.top_paths.map((row, i) => (
+ <div className="app-info-item" key={i}>
+ <span className="app-info-label" title={row.path}>{clip(row.path)}</span>
+ <span className="app-info-value">{row.count.toLocaleString()}</span>
+ </div>
+ ))}
+ </div>
+ <p className="hint">Read live from the container access log; PHP fatals and response-time metrics are not captured by the default log.</p>
+ </div>
+ </div>
+ )}
+ </div>
+ </div>
+ );
+};
+
// Overview Tab
const OverviewTab = ({ site, onUpdate }) => {
const toast = useToast();
diff --git a/frontend/src/services/wordpress.js b/frontend/src/services/wordpress.js
index 642ee2a3..771d23e4 100644
--- a/frontend/src/services/wordpress.js
+++ b/frontend/src/services/wordpress.js
@@ -182,6 +182,9 @@ const wordpressApi = {
attachStatusPage: (siteId, pageId) => api.request(`${BASE_PATH}/${siteId}/status-page`, { method: 'POST', body: { page_id: pageId } }),
detachStatusPage: (siteId) => api.request(`${BASE_PATH}/${siteId}/status-page`, { method: 'DELETE' }),
+ // Traffic + error analytics (#25) — parsed on-demand from the apache access log.
+ getSiteAnalytics: (siteId, hours = 24) => api.request(`${BASE_PATH}/${siteId}/analytics?hours=${hours}`),
+
// Mint a one-time passwordless wp-admin login URL for the current operator.
autoLogin: (siteId) => api.request(`${BASE_PATH}/${siteId}/login`, {
method: 'POST'