#!/usr/bin/env python3 """Render grade-5 scaling evidence as SVG, CSV and Markdown.""" import argparse import csv import html import json from pathlib import Path STYLE = """ text { font-family: Inter, Segoe UI, sans-serif; fill: #eceef0; } .title { font-size: 26px; font-weight: 650; } .subtitle { font-size: 14px; fill: #aeb2b8; } .label { font-size: 14px; fill: #c8cbd0; } .small { font-size: 12px; fill: #a2a5aa; } .grid { stroke: #34373d; stroke-width: 1; } .axis { stroke: #747981; stroke-width: 1.5; } .line { fill: none; stroke: #f4f5f6; stroke-width: 3; } .line2 { fill: none; stroke: #92979f; stroke-width: 3; } .point { fill: #f4f5f6; } .point2 { fill: #92979f; } .bar { fill: #d7d9dc; } .bar2 { fill: #777c84; } .bar3 { fill: #4c5057; } .threshold { stroke: #8f949c; stroke-width: 2; stroke-dasharray: 7 5; } """ def svg(title, subtitle, body, width=1120, height=620): return f""" {html.escape(title)} {html.escape(subtitle)} {body} """ def grid(maximum, left, top, width, height, suffix=""): maximum = maximum or 1 parts = [] for step in range(6): value = maximum * step / 5 y = top + height - height * step / 5 parts.append(f'') parts.append(f'{value:.0f}{suffix}') return parts def phase_map(report): return {phase["name"]: phase for phase in report["phases"]} def saturation_graph(report, output): phases = sorted( (phase for phase in report["phases"] if phase["kind"] == "saturation"), key=lambda phase: phase["concurrency"], ) left, top, width, height = 90, 110, 940, 390 max_rps = max(phase["successful_rps"] for phase in phases) * 1.1 max_p95 = max(phase["successful_latency_ms"]["p95"] for phase in phases) * 1.1 parts = grid(max_rps, left, top, width, height) points_rps, points_p95 = [], [] for index, phase in enumerate(phases): x = left + width * index / max(1, len(phases) - 1) y_rps = top + height - height * phase["successful_rps"] / max_rps y_p95 = top + height - height * phase["successful_latency_ms"]["p95"] / max_p95 points_rps.append(f"{x:.1f},{y_rps:.1f}") points_p95.append(f"{x:.1f},{y_p95:.1f}") parts.append(f'') parts.append(f'') parts.append(f'{phase["concurrency"]}') parts.append(f'{phase["successful_rps"]:.0f}') parts.append(f'') parts.append(f'') parts.append(f'Concurrency') parts.append(f'white: RPS · gray: p95 normalized') parts.append(f'Successful requests per second') output.write_text(svg( "Saturation curve", "Two API replicas; 1 CPU total; 16 total DB connections; PostgreSQL limited to 1 CPU", "\n".join(parts), ), encoding="utf-8") def comparison_graph(report, kind, output): phases = sorted( (phase for phase in report["phases"] if phase["kind"] == kind), key=lambda phase: phase["replicas"], ) left, top, width, height = 90, 110, 940, 370 max_rps = max(phase["successful_rps"] for phase in phases) * 1.15 parts = grid(max_rps, left, top, width, height) slot = width / len(phases) for index, phase in enumerate(phases): bar_width = min(150, slot * 0.52) x = left + index * slot + (slot - bar_width) / 2 bar_height = height * phase["successful_rps"] / max_rps y = top + height - bar_height parts.append(f'') parts.append(f'{phase["successful_rps"]:.1f} RPS') parts.append(f'{phase["replicas"]} replica(s)') parts.append(f'p95 {phase["successful_latency_ms"]["p95"]:.1f} ms') parts.append(f'errors {phase["error_ratio"]*100:.3f}%') if kind == "fixed": title = "Fixed total API budget" subtitle = "1 CPU · 512 MiB · 16 DB connections split across 1, 2 and 4 replicas" else: title = "Growing API budget" subtitle = "Each replica adds 0.5 CPU · 256 MiB · 8 DB connections; PostgreSQL remains at 1 CPU" output.write_text(svg(title, subtitle, "\n".join(parts)), encoding="utf-8") def bottleneck_graph(report, output): phases = sorted( (phase for phase in report["phases"] if phase["kind"] == "growth"), key=lambda phase: phase["replicas"], ) services = ("api", "postgres", "load-balancer", "frontend", "redis") left, top, width, height = 90, 110, 940, 370 maximum = max( phase["resources"].get(service, {}).get("cpu_percent_avg", 0) for phase in phases for service in services ) * 1.15 or 1 parts = grid(maximum, left, top, width, height) slot = width / len(phases) colors = ("bar", "bar2", "bar3", "bar3", "bar3") for phase_index, phase in enumerate(phases): group_left = left + phase_index * slot bar_width = min(48, slot / 6) for service_index, service in enumerate(services): value = phase["resources"].get(service, {}).get("cpu_percent_avg", 0) x = group_left + slot * 0.12 + service_index * (bar_width + 9) bar_height = height * value / maximum y = top + height - bar_height parts.append(f'') parts.append(f'{value:.0f}') parts.append(f'{service[:3]}') parts.append(f'{phase["replicas"]} replica(s)') parts.append(f'Average aggregate CPU, %') output.write_text(svg( "Where scaling stops", "Aggregate service CPU during the proportional-growth series (api · postgres · HAProxy · frontend · redis)", "\n".join(parts), ), encoding="utf-8") def improvement_graph(report, output): phases = phase_map(report) baseline = phases["growth-r4"] improved = phases["improved-db-cpu-r4"] pair = [baseline, improved] left, top, panel_width, height = 90, 120, 390, 340 parts = [] panels = [ ("Successful RPS", "successful_rps", left), ("p95 latency, ms", "p95", 630), ] for title, metric, panel_left in panels: values = [ phase["successful_rps"] if metric == "successful_rps" else phase["successful_latency_ms"]["p95"] for phase in pair ] maximum = max(values) * 1.2 or 1 parts.append(f'{title}') for index, (phase, value) in enumerate(zip(pair, values)): bar_width = 120 x = panel_left + 35 + index * 185 bar_height = height * value / maximum y = top + height - bar_height parts.append(f'') parts.append(f'{value:.1f}') parts.append(f'PG {1 if index == 0 else 2} CPU') analysis = report["analysis"]["improvement"] parts.append(f'RPS change: {analysis["rps_change_percent"]:+.2f}% · p95 change: {analysis["p95_change_percent"]:+.2f}% · confirmed: {str(analysis["confirmed"]).lower()}') output.write_text(svg( "Confirmed improvement", "Four API replicas unchanged; only the PostgreSQL CPU limit changes from 1 to 2", "\n".join(parts), ), encoding="utf-8") def write_csv(report, destination): with (destination / "measurements.csv").open("w", newline="", encoding="utf-8") as stream: fields = [ "phase", "kind", "replicas", "concurrency", "elapsed_seconds", "successful_requests", "failed_requests", "error_ratio", "successful_rps", "p50_ms", "p95_ms", "p99_ms", "api_cpu_avg", "postgres_cpu_avg", "load_balancer_cpu_avg", "frontend_cpu_avg", "redis_cpu_avg", ] writer = csv.DictWriter(stream, fieldnames=fields) writer.writeheader() for phase in report["phases"]: writer.writerow({ "phase": phase["name"], "kind": phase["kind"], "replicas": phase["replicas"], "concurrency": phase["concurrency"], "elapsed_seconds": phase["elapsed_seconds"], "successful_requests": phase["successful_requests"], "failed_requests": phase["failed_requests"], "error_ratio": phase["error_ratio"], "successful_rps": phase["successful_rps"], "p50_ms": phase["successful_latency_ms"]["p50"], "p95_ms": phase["successful_latency_ms"]["p95"], "p99_ms": phase["successful_latency_ms"]["p99"], "api_cpu_avg": phase["resources"].get("api", {}).get("cpu_percent_avg"), "postgres_cpu_avg": phase["resources"].get("postgres", {}).get("cpu_percent_avg"), "load_balancer_cpu_avg": phase["resources"].get("load-balancer", {}).get("cpu_percent_avg"), "frontend_cpu_avg": phase["resources"].get("frontend", {}).get("cpu_percent_avg"), "redis_cpu_avg": phase["resources"].get("redis", {}).get("cpu_percent_avg"), }) with (destination / "timeseries.csv").open("w", newline="", encoding="utf-8") as stream: fields = ["phase", "second", "successful", "failed"] writer = csv.DictWriter(stream, fieldnames=fields) writer.writeheader() for phase in report["phases"]: for second, counts in phase["per_second"].items(): writer.writerow({"phase": phase["name"], "second": second, **counts}) with (destination / "resources.csv").open("w", newline="", encoding="utf-8") as stream: fields = ["phase", "t", "service", "containers", "cpu_percent", "memory_mib"] writer = csv.DictWriter(stream, fieldnames=fields) writer.writeheader() for phase in report["phases"]: for snapshot in phase["resource_samples"]: for service, values in snapshot["services"].items(): writer.writerow({ "phase": phase["name"], "t": snapshot["t"], "service": service, **values, }) def markdown_summary(report, output): method = report["methodology"] analysis = report["analysis"] improvement = analysis["improvement"] lines = [ "# Lab 3 grade-5 scaling experiment", "", f"Generated: {report['environment']['utc_started_at']}.", "", "## Hypothesis", "", report["hypothesis"], "", "## Reproduction", "", f"- workload: {method['workload']};", f"- phase duration: {method['duration_seconds_per_phase']} s;", f"- comparison concurrency: {method['comparison_concurrency']};", f"- saturation sweep: {method['saturation_concurrency']};", f"- fixed budget: {method['fixed_total_budget']};", f"- growth series: {method['growth_budget']};", f"- saturation rule: {method['saturation_rule']};", f"- host: {report['environment']['logical_cpu_count']} logical CPU, {report['environment']['host_memory_mib']} MiB RAM;", f"- Docker {report['environment']['docker_engine']}, Compose {report['environment']['docker_compose']};", "- command: `make grade5-experiment`; warmup runs before every changed profile.", "", "## Measurements", "", "| Phase | Replicas | Concurrency | RPS | Errors | p50 ms | p95 ms | p99 ms | PG CPU avg | API CPU avg |", "| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |", ] for phase in report["phases"]: latency = phase["successful_latency_ms"] resources = phase["resources"] lines.append( f"| {phase['name']} | {phase['replicas']} | {phase['concurrency']} | " f"{phase['successful_rps']} | {phase['failed_requests']} ({phase['error_ratio']*100:.3f}%) | " f"{latency['p50']} | {latency['p95']} | {latency['p99']} | " f"{resources.get('postgres', {}).get('cpu_percent_avg', 'n/a')} | " f"{resources.get('api', {}).get('cpu_percent_avg', 'n/a')} |" ) saturation = analysis["saturation_point"] lines += ["", "## Conclusion", ""] if saturation: lines.append( f"The first saturation signal appears at concurrency {saturation['concurrency']}: " f"RPS changes by {saturation['rps_gain_percent']:+.2f}% while p95 changes by " f"{saturation['p95_growth_ratio']:.2f}x versus concurrency {saturation['previous_concurrency']}." ) else: lines.append("The configured sweep did not locate a saturation point by the declared rule.") lines += [ "", f"Observed bottleneck classification: `{analysis['observed_bottleneck']}`.", "", f"The PostgreSQL CPU change produced {improvement['rps_change_percent']:+.2f}% RPS and " f"{improvement['p95_change_percent']:+.2f}% p95; confirmed improvement: " f"`{str(improvement['confirmed']).lower()}`.", "", f"After the improvement the remaining bottleneck classification is " f"`{analysis['remaining_bottleneck_after_improvement']}`.", "", "## Graphs", "", "![Saturation](01-saturation.svg)", "", "![Fixed budget](02-fixed-total.svg)", "", "![Growing budget](03-resource-growth.svg)", "", "![Bottleneck](04-bottleneck.svg)", "", "![Improvement](05-improvement.svg)", "", "## Raw data and limits", "", "Raw aggregates are in `measurements.csv`; one-second request buckets are in " "`timeseries.csv`; every resource sample is in `resources.csv`; complete metadata and " "applied limits are in `results.json`.", "", ] lines.extend(f"- {item}" for item in report["limitations"]) lines.append("") output.write_text("\n".join(lines), encoding="utf-8") def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("results", nargs="?", default="evidence/grade5/results.json") args = parser.parse_args() source = Path(args.results) report = json.loads(source.read_text(encoding="utf-8")) destination = source.parent saturation_graph(report, destination / "01-saturation.svg") comparison_graph(report, "fixed", destination / "02-fixed-total.svg") comparison_graph(report, "growth", destination / "03-resource-growth.svg") bottleneck_graph(report, destination / "04-bottleneck.svg") improvement_graph(report, destination / "05-improvement.svg") write_csv(report, destination) markdown_summary(report, destination / "README.md") print(f"rendered grade-5 evidence in {destination}") if __name__ == "__main__": main()