Skip to content

Performance Budget Orchestrator

Enterprise performance budget management with automated monitoring, Core Web Vitals tracking, and comprehensive performance optimization recommendations for web applications and APIs.

Overview

The Performance Budget Orchestrator provides comprehensive performance monitoring and budget enforcement capabilities, helping teams maintain optimal application performance through automated testing, real-time monitoring, and actionable optimization guidance.

Key Features

⚡ Performance Metrics

  • Core Web Vitals - LCP, FID, CLS, FCP, TTFB, TTI
  • Loading Performance - Resource loading times and optimization
  • Runtime Performance - JavaScript execution and interaction metrics
  • Network Analysis - Bandwidth usage and optimization opportunities
  • Resource Budgets - File sizes, request counts, and optimization

🎯 Budget Types

  • Time-based Budgets - Loading and interaction timing thresholds
  • Size-based Budgets - Resource size limitations (JS, CSS, images)
  • Quantity-based Budgets - Request count and resource quantity limits
  • Custom Metrics - Business-specific performance indicators

📊 Testing Platforms

  • Desktop - High-performance desktop environment testing
  • Mobile - Mobile device performance simulation
  • Tablet - Tablet-specific performance characteristics
  • API - Backend service performance monitoring

API Endpoints

Create Performance Budget

POST /budgets
Content-Type: application/json

{
  "name": "Mobile LCP Budget",
  "description": "Largest Contentful Paint budget for mobile users",
  "budget_type": "time_based",
  "metric_name": "largest-contentful-paint",
  "threshold": 2.5,
  "unit": "seconds",
  "severity": "error",
  "platform": "mobile",
  "enabled": true,
  "conditions": {
    "network_speed": "4g",
    "device_type": "phone"
  }
}

Response: 

{
  "message": "Performance budget created",
  "budget": {
    "id": "budget_123",
    "name": "Mobile LCP Budget",
    "metric_name": "largest-contentful-paint",
    "threshold": 2.5,
    "severity": "error",
    "platform": "mobile",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Run Performance Test

POST /test
Content-Type: application/json

{
  "url": "https://myapp.com",
  "platform": "mobile",
  "name": "Homepage Performance Test",
  "config": {
    "test_duration": 60,
    "network_throttling": "4g",
    "cpu_throttling": 4,
    "cache_disabled": false,
    "screenshot": true,
    "video_recording": true
  }
}

Response: 

{
  "message": "Performance test started",
  "test_run_id": "test_456",
  "status": "running",
  "estimated_completion": "2025-01-15T10:33:00Z"
}

Get Test Results

GET /test/{test_run_id}

Response: 

{
  "id": "test_456",
  "url": "https://myapp.com",
  "platform": "mobile",
  "status": "completed",
  "start_time": "2025-01-15T10:30:00Z",
  "end_time": "2025-01-15T10:32:30Z",
  "duration": 150,
  "score": 78.5,
  "metrics": [
    {
      "metric_name": "largest-contentful-paint",
      "value": 2.8,
      "unit": "seconds",
      "timestamp": "2025-01-15T10:32:00Z"
    },
    {
      "metric_name": "first-contentful-paint", 
      "value": 1.2,
      "unit": "seconds",
      "timestamp": "2025-01-15T10:32:00Z"
    }
  ],
  "violations": [
    {
      "budget_id": "budget_123",
      "metric_name": "largest-contentful-paint",
      "actual_value": 2.8,
      "budget_threshold": 2.5,
      "severity": "error",
      "impact_score": 85.2,
      "recommendations": [
        "Optimize images and use next-gen formats",
        "Implement lazy loading for below-fold content",
        "Reduce server response times"
      ]
    }
  ],
  "recommendations": [
    "Focus on reducing Largest Contentful Paint",
    "Optimize critical rendering path",
    "Consider implementing a CDN"
  ],
  "artifacts": [
    "lighthouse-report-test_456.json",
    "screenshot-test_456.png",
    "trace-test_456.json"
  ]
}

List Budget Violations

GET /violations?limit=20&resolved=false

Response: 

{
  "violations": [
    {
      "id": "violation_789",
      "budget_id": "budget_123", 
      "test_run_id": "test_456",
      "metric_name": "largest-contentful-paint",
      "actual_value": 2.8,
      "budget_threshold": 2.5,
      "severity": "error",
      "timestamp": "2025-01-15T10:32:00Z",
      "url": "https://myapp.com",
      "platform": "mobile",
      "impact_score": 85.2,
      "resolved": false
    }
  ]
}

Usage Examples

Basic Performance Testing

# Run performance test
unacode performance test \
  --url "https://myapp.com" \
  --platform "mobile" \
  --lighthouse \
  --generate-report

# Create performance budget
unacode performance create-budget \
  --name "Core Web Vitals Mobile" \
  --metric "largest-contentful-paint" \
  --threshold 2.5 \
  --platform "mobile" \
  --severity "error"

# Monitor budget violations
unacode performance check-violations \
  --severity "error,warning" \
  --unresolved-only

Python Integration

import asyncio
from unacode.orchestrators import PerformanceBudgetOrchestrator

async def comprehensive_performance_monitoring():
    orchestrator = PerformanceBudgetOrchestrator()

    # Create Core Web Vitals budgets
    cwv_budgets = [
        {
            "name": "LCP Mobile Budget",
            "metric_name": "largest-contentful-paint",
            "threshold": 2.5,
            "platform": "mobile",
            "severity": "error"
        },
        {
            "name": "FID Budget",
            "metric_name": "first-input-delay", 
            "threshold": 0.1,
            "platform": "mobile",
            "severity": "error"
        },
        {
            "name": "CLS Budget",
            "metric_name": "cumulative-layout-shift",
            "threshold": 0.1,
            "platform": "mobile",
            "severity": "error"
        }
    ]

    # Create budgets
    for budget_config in cwv_budgets:
        budget = await orchestrator.create_performance_budget(budget_config)
        print(f"Created budget: {budget.name}")

    # Run performance tests on key pages
    test_urls = [
        "https://myapp.com",
        "https://myapp.com/products",
        "https://myapp.com/checkout",
        "https://myapp.com/profile"
    ]

    test_results = []
    for url in test_urls:
        result = await orchestrator.run_performance_test(
            url=url,
            platform=TestPlatform.MOBILE,
            test_config={
                "network_throttling": "4g",
                "cpu_throttling": 4,
                "lighthouse_audit": True,
                "playwright_metrics": True
            }
        )
        test_results.append(result)
        print(f"Tested {url}: Score {result.score}")

    # Generate performance report
    return generate_performance_report(test_results)

CI/CD Integration

# .github/workflows/performance.yml
name: Performance Budget Monitoring
on: [push, pull_request, schedule]

jobs:
  performance-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Deploy to Staging
        run: |
          # Deploy app to staging environment
          ./deploy-staging.sh

      - name: Run Performance Tests
        run: |
          unacode performance test \
            --url "${{ env.STAGING_URL }}" \
            --platform "mobile" \
            --lighthouse \
            --budget-check \
            --fail-on-violation \
            --severity-threshold "error"

      - name: Performance Budget Check
        run: |
          # Check for budget violations
          unacode performance check-violations \
            --exit-code \
            --severity "error,warning" \
            --report-format "github-actions"

      - name: Upload Performance Report
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: performance-report
          path: performance-report.html

Advanced Monitoring Setup

async def setup_continuous_monitoring():
    orchestrator = PerformanceBudgetOrchestrator()

    # Create comprehensive budget suite
    budget_configs = [
        # Core Web Vitals
        {"name": "LCP Desktop", "metric": "largest-contentful-paint", "threshold": 2.5, "platform": "desktop"},
        {"name": "LCP Mobile", "metric": "largest-contentful-paint", "threshold": 2.5, "platform": "mobile"},
        {"name": "FID", "metric": "first-input-delay", "threshold": 0.1, "platform": "mobile"},
        {"name": "CLS", "metric": "cumulative-layout-shift", "threshold": 0.1, "platform": "mobile"},

        # Resource Budgets
        {"name": "JS Bundle Size", "metric": "javascript-size", "threshold": 300, "unit": "KB"},
        {"name": "CSS Size", "metric": "css-size", "threshold": 100, "unit": "KB"},
        {"name": "Image Size", "metric": "images-size", "threshold": 500, "unit": "KB"},
        {"name": "Total Requests", "metric": "total-requests", "threshold": 50, "unit": "count"},

        # Performance Metrics
        {"name": "Time to Interactive", "metric": "time-to-interactive", "threshold": 5.0, "platform": "mobile"},
        {"name": "Speed Index", "metric": "speed-index", "threshold": 4.0, "platform": "mobile"},
        {"name": "TTFB", "metric": "time-to-first-byte", "threshold": 0.8, "platform": "mobile"}
    ]

    # Create all budgets
    budgets = []
    for config in budget_configs:
        budget = await orchestrator.create_performance_budget(config)
        budgets.append(budget)

    # Setup monitoring for critical pages
    monitoring_schedule = {
        "https://myapp.com": {"frequency": "hourly", "platforms": ["desktop", "mobile"]},
        "https://myapp.com/products": {"frequency": "4hours", "platforms": ["mobile"]},
        "https://myapp.com/checkout": {"frequency": "2hours", "platforms": ["mobile", "desktop"]},
    }

    return {
        "budgets": budgets,
        "monitoring_schedule": monitoring_schedule,
        "total_budgets": len(budgets)
    }

Core Web Vitals Optimization

Largest Contentful Paint (LCP)

# LCP optimization recommendations
lcp_optimizations = {
    "server_optimization": [
        "Reduce server response times (TTFB)",
        "Use CDN for static assets",
        "Optimize database queries",
        "Enable HTTP/2 and compression"
    ],
    "resource_optimization": [
        "Optimize images (WebP, AVIF formats)",
        "Implement lazy loading",
        "Preload critical resources",
        "Remove unused CSS and JavaScript"
    ],
    "rendering_optimization": [
        "Eliminate render-blocking resources",
        "Optimize Critical Rendering Path",
        "Use resource hints (dns-prefetch, preconnect)",
        "Minimize Critical Resource Depth"
    ]
}

First Input Delay (FID)

# FID optimization strategies
fid_optimizations = {
    "javascript_optimization": [
        "Reduce JavaScript execution time",
        "Split large bundles with code splitting",
        "Remove unused JavaScript",
        "Use Web Workers for heavy computations"
    ],
    "interaction_optimization": [
        "Optimize event handlers",
        "Use passive event listeners",
        "Debounce expensive operations",
        "Implement efficient DOM updates"
    ]
}

Cumulative Layout Shift (CLS)

# CLS optimization techniques
cls_optimizations = {
    "layout_stability": [
        "Include size attributes on images and videos",
        "Reserve space for ad slots",
        "Avoid inserting content above existing content",
        "Use CSS aspect-ratio for responsive media"
    ],
    "font_optimization": [
        "Use font-display: swap",
        "Preload critical fonts", 
        "Use system fonts as fallbacks",
        "Avoid invisible text during font swaps"
    ]
}

Performance Budget Templates

E-commerce Site

{
  "budgets": [
    {
      "name": "Homepage LCP",
      "metric": "largest-contentful-paint",
      "threshold": 2.5,
      "platform": "mobile"
    },
    {
      "name": "Product Page Load",
      "metric": "first-contentful-paint", 
      "threshold": 1.5,
      "platform": "mobile"
    },
    {
      "name": "Checkout Performance",
      "metric": "time-to-interactive",
      "threshold": 4.0,
      "platform": "mobile"
    },
    {
      "name": "Bundle Size",
      "metric": "javascript-size",
      "threshold": 400,
      "unit": "KB"
    }
  ]
}

Content/Media Site

{
  "budgets": [
    {
      "name": "Article LCP",
      "metric": "largest-contentful-paint", 
      "threshold": 2.0,
      "platform": "mobile"
    },
    {
      "name": "Image Budget",
      "metric": "images-size",
      "threshold": 800,
      "unit": "KB"
    },
    {
      "name": "Video Loading",
      "metric": "video-load-time",
      "threshold": 3.0,
      "platform": "mobile"
    }
  ]
}

Real-time Monitoring

WebSocket Integration

// Real-time performance monitoring
const ws = new WebSocket('ws://localhost:8083/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === 'budget_violation') {
    console.warn('Performance budget violated!', data);
    showPerformanceAlert(data.violation);
  }

  if (data.type === 'test_complete') {
    console.log('Performance test completed', data);
    updatePerformanceDashboard(data.results);
  }
};

function showPerformanceAlert(violation) {
  alert(`Performance Alert: ${violation.metric_name} exceeded budget by ${violation.impact_score}%`);
}

Alert Configuration

# Configure performance alerts
alert_config = {
    "webhooks": [
        {
            "url": "https://hooks.slack.com/services/...",
            "events": ["budget_violation", "performance_regression"],
            "severity_filter": ["error", "warning"]
        }
    ],
    "email_alerts": {
        "enabled": True,
        "recipients": ["dev-team@company.com"],
        "severity_threshold": "error",
        "digest_frequency": "daily"
    },
    "dashboard_notifications": {
        "enabled": True,
        "auto_dismiss": False,
        "sound_alerts": True
    }
}

Dashboard Features

The integrated dashboard provides:

  • Performance Score Tracking - Real-time performance scores and trends
  • Budget Violation Management - Identify and prioritize performance issues
  • Core Web Vitals Monitoring - Dedicated CWV tracking and optimization
  • Resource Budget Analysis - Monitor file sizes and request counts
  • Trend Analysis - Historical performance data and regression detection
  • Optimization Recommendations - AI-powered performance improvement suggestions

Server Configuration

# Start the performance budget server
python -m unacode.master_orchestrators.performance_budget_orchestrator \
  --host 0.0.0.0 \
  --port 8083 \
  --config performance_budget_config.json

# Access the dashboard
open http://localhost:8083/dashboard

Best Practices

1. Budget Definition

  • Set realistic but ambitious performance targets
  • Create separate budgets for different user contexts (mobile/desktop)
  • Include both technical and business metrics

2. Monitoring Strategy

  • Monitor critical user journeys frequently
  • Set up alerts for performance regressions
  • Track performance impact of deployments

3. Optimization Workflow

  • Prioritize Core Web Vitals improvements
  • Focus on highest-impact performance issues first
  • Implement performance-aware development practices

4. Team Integration

  • Include performance budgets in code review process
  • Provide developer education on performance optimization
  • Establish performance champions within teams

Ready to maintain optimal application performance? Start with the Quick Start Guide or explore the API Documentation for integration details.