Performance Budget Monitoring: Catching Regressions Automatically

A performance budget is a set of explicit limits for performance metrics. Any build, deployment, or code change that exceeds the budget is flagged — or blocked — automatically. Performance budgets shift performance from "something we fix when it's bad" to "something we maintain continuously," catching regressions before they reach users.

What Is a Performance Budget?

A performance budget defines acceptable ranges for metrics that matter to user experience:

{
  "timings": [
    { "metric": "largest-contentful-paint", "budget": 2500 },
    { "metric": "first-contentful-paint", "budget": 1800 },
    { "metric": "cumulative-layout-shift", "budget": 0.1 },
    { "metric": "total-blocking-time", "budget": 200 }
  ],
  "resourceSizes": [
    { "resourceType": "script", "budget": 300 },
    { "resourceType": "image", "budget": 1000 },
    { "resourceType": "stylesheet", "budget": 100 },
    { "resourceType": "total", "budget": 2000 }
  ],
  "resourceCounts": [
    { "resourceType": "third-party", "budget": 20 }
  ]
}

When your build process measures current performance against these budgets, you get immediate feedback on regressions.

Setting Your Performance Budget

Start with Current Performance

Your first budget should reflect your current state (or your desired state if current is too poor):

1. Run Lighthouse or WebPageTest on your key pages
2. Record current values for LCP, FCP, TBT, CLS, and total page size
3. Set budget at current value (to prevent regression) or target value (to drive improvement)

Don't set aspirational budgets immediately. If your LCP is currently 4.2 seconds and you set a budget of 2.5 seconds, every build fails and the budget becomes noise. Start with "no regression" budgets, then tighten them as you improve.

Performance Budget by Page Type

Different pages have different performance profiles and users:

| Page Type | LCP Budget | TBT Budget | Page Size Budget | |-----------|-----------|-----------|----------------| | Homepage | 2500ms | 200ms | 1.5MB | | Product page | 2500ms | 300ms | 2MB | | Blog post | 2500ms | 150ms | 1MB | | Checkout | 3000ms | 400ms | 2.5MB | | Dashboard (authenticated) | 3500ms | 500ms | 3MB |

Resource Size Budgets

Resource size budgets prevent bundle bloat from accumulating silently:

| Resource Type | Budget | Rationale | |-------------|--------|-----------| | JavaScript (total) | 300KB (gzipped) | Above this, mobile parse time becomes significant | | CSS (total) | 100KB (gzipped) | Most sites don't need more | | Images (per page) | 1MB | Depends heavily on content | | Fonts | 100KB | 2-3 font files maximum | | Third-party scripts | 150KB | Often the biggest culprit |

Enforcing Budgets in CI/CD

Lighthouse CI Integration

Google's Lighthouse CI tool automates performance testing in your pipeline:

# .github/workflows/performance.yml
name: Performance Budget Check
on: [pull_request]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Lighthouse CI
        run: npm install -g @lhci/cli
      
      - name: Deploy preview (or use staging URL)
        run: |
          # Build and deploy to preview environment
          npm run build && npm run deploy:preview
        
      - name: Run Lighthouse CI
        run: lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

// lighthouserc.json
{
  "ci": {
    "collect": {
      "urls": [
        "https://preview.yoursite.com",
        "https://preview.yoursite.com/products",
        "https://preview.yoursite.com/checkout"
      ],
      "numberOfRuns": 3
    },
    "assert": {
      "preset": "lighthouse:recommended",
      "assertions": {
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
        "total-blocking-time": ["warn", { "maxNumericValue": 200 }],
        "resource-summary:script:size": ["error", { "maxNumericValue": 307200 }]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

Bundle Size Budgets with bundlesize

For JavaScript bundle size specifically, bundlesize or size-limit can enforce budgets at build time:

// package.json
{
  "scripts": {
    "check-size": "bundlesize"
  },
  "bundlesize": [
    { "path": "./dist/js/*.js", "maxSize": "300 kB" },
    { "path": "./dist/css/*.css", "maxSize": "100 kB" }
  ]
}

WebPageTest API Integration

For more realistic lab testing including actual network conditions:

# Run WebPageTest via API in CI
curl "https://www.webpagetest.org/runtest.php" \
  --data-urlencode "url=https://staging.yoursite.com" \
  --data "k=${WPT_API_KEY}" \
  --data "f=json" \
  --data "location=Dulles:Chrome"

Continuous Production Monitoring

CI/CD budget enforcement prevents regressions at deployment time. But production performance can also degrade due to:

• A/B test changes
• Third-party script updates (outside your control)
• Content changes (larger images added via CMS)
• Traffic pattern changes

Continuous monitoring in production catches these post-deployment regressions. AzMonitor runs performance checks on a schedule and alerts when metrics exceed your budget thresholds:

# AzMonitor performance budget alerts
performance_monitors:
  - page: https://yoursite.com
    budget:
      lcp: 2500ms
      cls: 0.1
    alert_channels: [slack-performance, engineering-email]
    check_frequency: 6_hours
    locations: [us-east, eu-west]

Handling Budget Failures

When a budget fails in CI/CD:

1. Don't merge — Treat budget failures like failing tests
2. Investigate the change — Which PR introduced the regression? What changed?
3. Fix or adjust — Fix the regression, or if the budget was wrong, adjust it with justification
4. Document exceptions — If you must exceed the budget temporarily, document why

When a budget alert fires in production:

1. Check what changed recently (deployments, CMS content changes, third-party updates)
2. Measure from multiple locations to confirm it's not a false positive
3. Trace the cause and revert or fix

Performance Budget Culture

Performance budgets only work if the team respects them. Build a performance-conscious culture by:

• Reviewing Lighthouse scores in every PR (not blocking, but visible)
• Celebrating performance improvements in team channels
• Including performance in engineering postmortems
• Setting performance OKRs alongside feature delivery OKRs

Set up continuous performance monitoring with AzMonitor alongside your CI/CD budget enforcement. Together, they give you coverage at both deployment time and post-deployment.

Related: Core Web Vitals monitoring for the specific metrics to include in your budget.