Performance Monitoring Setup Guide

🎯 Overview

Automated performance monitoring with email alerts and data commits to repository.

What You Get:

  • 📧 Email alerts when TTFB > 1.5s or other performance issues
  • 📊 Weekly summary emails when everything is healthy
  • 🤖 Auto-committed performance logs for Claude analysis
  • 📈 Historical performance tracking in performance-logs/

🔧 Required GitHub Secrets

You need to add these secrets to your GitHub repository:

Go to: GitHub.com → Your Repo → Settings → Secrets and Variables → Actions

Required Secrets:

Secret Name Description Example Value
EMAIL_USERNAME Your Gmail address your.email@gmail.com
EMAIL_PASSWORD Gmail App Password abcd efgh ijkl mnop
ALERT_EMAIL Where to send alerts your.email@gmail.com
PAGESPEED_API_KEY Already set AIzaSyBfsVckRL...

📧 Gmail Setup for Email Alerts

Step 1: Enable 2-Factor Authentication

  1. Go to Google Account Security
  2. Turn on 2-Step Verification if not already enabled

Step 2: Create App Password

  1. Go to Google Account Security
  2. Click 2-Step Verification
  3. Scroll down to App passwords
  4. Click Select app → Other (custom name)
  5. Enter: Academic Website Monitor
  6. Click GENERATE
  7. Copy the 16-character password (looks like: abcd efgh ijkl mnop)

Step 3: Add Secrets to GitHub

# Go to your repo on GitHub.com
# Settings → Secrets and variables → Actions → New repository secret

EMAIL_USERNAME: your.email@gmail.com
EMAIL_PASSWORD: abcd efgh ijkl mnop  # The app password from step 2
ALERT_EMAIL: your.email@gmail.com    # Can be same as EMAIL_USERNAME

🚀 How It Works

Triggers:

  • After every deployment (automatic)
  • Every Monday at 9 AM UTC (scheduled)
  • Manual trigger (workflow_dispatch)

Process:

  1. Performance tests run (TTFB + PageSpeed API when available)
  2. Results committed to performance-logs/performance-YYYYMMDD-HHMMSS.log
  3. Email sent if issues detected (TTFB > 1.5s)
  4. Weekly summary sent every Monday if all healthy

Email Types:

🚨 Alert Email (Performance Issues):

Subject: ⚠️ Academic Website Performance Alert - wevbarker.co.uk

Performance regression detected!
- Homepage TTFB: 2.3s (threshold: 1.5s)
- Action needed: Check performance-logs/performance-20250906.log

Recommended: Pull latest changes and ask Claude to analyze.

📊 Weekly Summary (All Good):

Subject: 📊 Weekly Performance Report - wevbarker.co.uk

Your website performance is healthy! ✅
- All pages under TTFB thresholds
- Ready for academic use
- Performance data logged for trending

📈 Your Workflow

When You Get an Alert:

  1. Check email for performance alert details
  2. Pull latest changes: git pull origin master
  3. Ask Claude: “I got a performance alert, analyze the latest performance logs”
  4. Claude reads the committed log file and diagnoses issues
  5. Fix issues based on Claude’s recommendations

Weekly Monitoring:

  • Healthy weeks: Just get summary email, no action needed
  • Performance trends: Historical data building in performance-logs/
  • Academic calendar: Extra attention during busy periods (semester start, etc.)

🎯 Performance Thresholds

Alert Triggers:

  • TTFB > 1.5 seconds (immediate alert)
  • PageSpeed API errors (service issues)
  • Build failures (deployment problems)

Academic Standards:

  • Homepage: < 0.8s (student accessibility)
  • Course pages: < 1.0s (classroom access)
  • Papers/CV: < 0.6s (professional impression)

🔧 Testing Your Setup

Immediate Test:

# Trigger performance monitoring manually
# Go to: GitHub Actions → Performance Monitoring → Run workflow

Email Test:

# Force an alert by temporarily lowering threshold in performance-monitor.yml
# Change: if (( $(echo "$ttfb > 1.5" | bc -l) )); then
# To:     if (( $(echo "$ttfb > 0.1" | bc -l) )); then

Verify Commit:

git pull origin master
ls -la performance-logs/  # Should see new log files

📊 Example Performance Log Analysis

What Claude Will See:

performance-logs/performance-20250906-090045.log:
=== CURL TIMING: Homepage (https://wevbarker.co.uk/) ===
TTFB: 2.340s  # This triggers alert
Total: 2.567s
Size: 42KB

=== CURL TIMING: Publications (https://wevbarker.co.uk/publications/) ===  
TTFB: 0.456s  # This is healthy
Total: 0.523s
Size: 43KB

Claude’s Analysis: “I see the homepage TTFB jumped to 2.34s while other pages remain healthy at ~0.45s. This suggests a homepage-specific issue, likely a large asset or caching problem. Check for recently added images or scripts on the homepage.”

🎉 Benefits

For You:

  • ✅ Set-and-forget monitoring - No daily maintenance
  • ✅ Proactive alerts - Know about problems before users complain
  • ✅ AI-ready analysis - Claude can diagnose issues from committed logs
  • ✅ Academic focused - Thresholds set for teaching/research needs

For Your Users:

  • ✅ Better student experience - Fast loading course materials
  • ✅ Professional impression - Quick CV/publication access
  • ✅ Mobile friendly - Performance monitored across devices

The system is now ready to deploy! Just add the GitHub secrets and you’ll have professional performance monitoring for your academic website.