Skip to content

HabitaNexus/monorepo / skills/system-reliability-engineering/load-testing-performance

load-testing-performance

Unverified

scripts/python/capacity_calculator.py

View on GitHub
#!/usr/bin/env python3
"""
Capacity Planning Calculator

Calculate capacity requirements and resource planning based on metrics.

Usage:
    python capacity_calculator.py --current-users 1000 --peak-users 1500
    python capacity_calculator.py --target-users 5000 --calculate-resources
"""

import argparse
import sys
from dataclasses import dataclass
from typing import Dict, Optional


@dataclass
class CapacityMetrics:
    """Capacity metrics for planning."""
    current_users: int
    peak_users: int
    avg_request_per_user_per_sec: float
    avg_response_time_ms: float
    error_rate: float
    current_throughput_rps: float
    max_throughput_rps: float


class CapacityPlanner:
    """Capacity planning calculator."""

    def __init__(self, metrics: CapacityMetrics, current_instances: int = 3):
        """
        Initialize capacity planner.

        Args:
            metrics: Capacity metrics
            current_instances: Current number of instances
        """
        self.metrics = metrics
        self.current_instances = current_instances

    def calculate_capacity_headroom(self) -> float:
        """Calculate current capacity headroom (0.0 to 1.0)."""
        if self.metrics.max_throughput_rps == 0:
            return 0.0
        utilization = self.metrics.current_throughput_rps / self.metrics.max_throughput_rps
        return max(0.0, 1.0 - utilization)

    def estimate_max_users(self, target_error_rate: float = 0.01) -> int:
        """
        Estimate maximum users with acceptable error rate.

        Args:
            target_error_rate: Maximum acceptable error rate

        Returns:
            Estimated maximum users
        """
        if self.metrics.current_throughput_rps == 0:
            return 0

        # Simple estimation: assume linear scaling until error rate threshold
        users_at_max = int(
            self.metrics.peak_users *
            (self.metrics.max_throughput_rps / self.metrics.current_throughput_rps)
        )
        return users_at_max

    def calculate_resources_needed(
        self,
        target_users: int,
        target_error_rate: float = 0.01
    ) -> Dict:
        """
        Calculate resources needed for target user count.

        Args:
            target_users: Target number of users
            target_error_rate: Maximum acceptable error rate

        Returns:
            Dictionary with resource requirements
        """
        if self.metrics.max_throughput_rps == 0:
            return {
                "error": "max_throughput_rps cannot be zero"
            }

        current_users_per_instance = (
            self.metrics.peak_users / self.current_instances
            if self.current_instances > 0 else 0
        )

        required_rps = target_users * self.metrics.avg_request_per_user_per_sec
        required_instances = int(
            required_rps / self.metrics.max_throughput_rps
        ) + 1  # Add buffer

        scaling_factor = (
            required_instances / self.current_instances
            if self.current_instances > 0 else float('inf')
        )

        return {
            "target_users": target_users,
            "required_instances": required_instances,
            "required_rps": required_rps,
            "current_instances": self.current_instances,
            "scaling_factor": scaling_factor,
            "current_users_per_instance": current_users_per_instance,
            "target_users_per_instance": target_users / required_instances if required_instances > 0 else 0,
        }

    def generate_report(self) -> str:
        """Generate capacity planning report."""
        headroom = self.calculate_capacity_headroom()
        max_users = self.estimate_max_users()

        report = []
        report.append("=" * 60)
        report.append("CAPACITY PLANNING REPORT")
        report.append("=" * 60)
        report.append("")
        report.append(f"Current Users: {self.metrics.current_users}")
        report.append(f"Peak Users: {self.metrics.peak_users}")
        report.append(f"Current Throughput: {self.metrics.current_throughput_rps:.2f} req/s")
        report.append(f"Max Throughput: {self.metrics.max_throughput_rps:.2f} req/s")
        report.append(f"Capacity Headroom: {headroom * 100:.1f}%")
        report.append(f"Estimated Max Users: {max_users}")
        report.append(f"Current Instances: {self.current_instances}")
        report.append("")

        return "\n".join(report)


def main():
    """CLI entry point."""
    parser = argparse.ArgumentParser(
        description="Capacity Planning Calculator",
        formatter_class=argparse.RawDescriptionHelpFormatter
    )

    parser.add_argument("--current-users", type=int, default=1000, help="Current number of users")
    parser.add_argument("--peak-users", type=int, default=1500, help="Peak number of users")
    parser.add_argument("--avg-rps-per-user", type=float, default=0.5, help="Average requests per user per second")
    parser.add_argument("--avg-response-time", type=float, default=100.0, help="Average response time (ms)")
    parser.add_argument("--error-rate", type=float, default=0.01, help="Current error rate")
    parser.add_argument("--current-throughput", type=float, default=500.0, help="Current throughput (req/s)")
    parser.add_argument("--max-throughput", type=float, default=1000.0, help="Max throughput per instance (req/s)")
    parser.add_argument("--current-instances", type=int, default=3, help="Current number of instances")

    parser.add_argument("--target-users", type=int, help="Calculate resources for target users")
    parser.add_argument("--report", action="store_true", help="Generate capacity report")

    args = parser.parse_args()

    metrics = CapacityMetrics(
        current_users=args.current_users,
        peak_users=args.peak_users,
        avg_request_per_user_per_sec=args.avg_rps_per_user,
        avg_response_time_ms=args.avg_response_time,
        error_rate=args.error_rate,
        current_throughput_rps=args.current_throughput,
        max_throughput_rps=args.max_throughput,
    )

    planner = CapacityPlanner(metrics, current_instances=args.current_instances)

    if args.report:
        print(planner.generate_report())

    if args.target_users:
        resources = planner.calculate_resources_needed(args.target_users)
        print("\nResource Requirements:")
        print("=" * 60)
        for key, value in resources.items():
            if isinstance(value, float):
                print(f"  {key}: {value:.2f}")
            else:
                print(f"  {key}: {value}")

    if not args.report and not args.target_users:
        # Default: show report
        print(planner.generate_report())

    return 0


if __name__ == "__main__":
    exit(main())
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall