loaderup 0.1.2__tar.gz → 0.1.4__tar.gz

{loaderup-0.1.2 → loaderup-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loaderup
-Version: 0.1.2
+Version: 0.1.4
 Summary: Lightweight load-testing API and CLI built around FastAPI, k6, and decorator-based target registration.
 Author: Mahdi Haroun
 License: MIT
@@ -33,7 +33,7 @@ Lightweight load-testing API and CLI built around FastAPI, k6, and decorator-bas
 
 - Python `>=3.12`
 - `uv` (recommended package manager)
-- `k6` (optional but recommended for real load runs)
+- `k6` 
 
 ## Install
 
@@ -47,7 +47,7 @@ uv pip install -e .
 python -m loader.main
 ```
 
-Server starts on `http://127.0.0.1:8000` by default.
+Server starts on `http://127.0.0.1:5050` by default.
 
 ## Run via CLI
 
@@ -55,7 +55,7 @@ Server starts on `http://127.0.0.1:8000` by default.
 python -m loaderup.cli up --app loader.main:app --targets loader.demo_registry_target --reload
 ```
 
-This command opens the dashboard automatically at `http://127.0.0.1:8000/`.
+This command opens the dashboard automatically at `http://127.0.0.1:5050/`.
 Use `--no-open-browser` if you want to disable auto-open.
 
 You can also use fallback-friendly forms like:
@@ -64,10 +64,75 @@ You can also use fallback-friendly forms like:
 python -m loaderup.cli up --app main:app --targets demo_registry_targets --reload
 ```
 
+## Using the decorator with FastAPI
+
+Create your FastAPI app as usual:
+
+```python
+# main.py
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def home():
+    return {"message": "ok"}
+
+
+@app.post("/users")
+def create_user(payload: dict):
+    return {"id": 1, **payload}
+```
+
+Then create a module with the load targets you want LoaderUp to test. The decorated functions do not need to call your route handlers; importing this module registers the target metadata.
+
+```python
+# targets.py
+from loaderup import load_target
+
+
+@load_target(
+    name="home page",
+    method="GET",
+    path="/",
+    expected_status=200,
+    tags=["public"],
+)
+def home_page():
+    pass
+
+
+@load_target(
+    name="create user",
+    method="POST",
+    path="/users",
+    payload_example={"name": "Ada"},
+    expected_status=200,
+    tags=["users"],
+)
+def create_user():
+    pass
+```
+
+Start LoaderUp and tell it to import the target module:
+
+```bash
+python -m loaderup.cli up --app main:app --targets targets --reload
+```
+
+Run all decorator-registered targets against your FastAPI app:
+
+```bash
+curl -X POST http://127.0.0.1:5050/run/registry \
+  -H 'Content-Type: application/json' \
+  -d '{"base_url":"http://127.0.0.1:5050","vus":10,"duration_seconds":30}'
+```
+
 ## Health check
 
 ```bash
-curl http://127.0.0.1:8000/health
+curl http://127.0.0.1:5050/health
 ```
 
 ## Dashboard
@@ -75,7 +140,7 @@ curl http://127.0.0.1:8000/health
 Open:
 
 ```bash
-http://127.0.0.1:8000/
+http://127.0.0.1:5050/
 ```
 
 Dashboard includes:

loaderup-0.1.4/README.md

@@ -0,0 +1,130 @@
+# LoaderUp
+
+Lightweight load-testing API and CLI built around FastAPI, k6, and decorator-based target registration.
+
+## Requirements
+
+- Python `>=3.12`
+- `uv` (recommended package manager)
+- `k6` 
+
+## Install
+
+```bash
+uv pip install -e .
+```
+
+## Run API directly
+
+```bash
+python -m loader.main
+```
+
+Server starts on `http://127.0.0.1:5050` by default.
+
+## Run via CLI
+
+```bash
+python -m loaderup.cli up --app loader.main:app --targets loader.demo_registry_target --reload
+```
+
+This command opens the dashboard automatically at `http://127.0.0.1:5050/`.
+Use `--no-open-browser` if you want to disable auto-open.
+
+You can also use fallback-friendly forms like:
+
+```bash
+python -m loaderup.cli up --app main:app --targets demo_registry_targets --reload
+```
+
+## Using the decorator with FastAPI
+
+Create your FastAPI app as usual:
+
+```python
+# main.py
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def home():
+    return {"message": "ok"}
+
+
+@app.post("/users")
+def create_user(payload: dict):
+    return {"id": 1, **payload}
+```
+
+Then create a module with the load targets you want LoaderUp to test. The decorated functions do not need to call your route handlers; importing this module registers the target metadata.
+
+```python
+# targets.py
+from loaderup import load_target
+
+
+@load_target(
+    name="home page",
+    method="GET",
+    path="/",
+    expected_status=200,
+    tags=["public"],
+)
+def home_page():
+    pass
+
+
+@load_target(
+    name="create user",
+    method="POST",
+    path="/users",
+    payload_example={"name": "Ada"},
+    expected_status=200,
+    tags=["users"],
+)
+def create_user():
+    pass
+```
+
+Start LoaderUp and tell it to import the target module:
+
+```bash
+python -m loaderup.cli up --app main:app --targets targets --reload
+```
+
+Run all decorator-registered targets against your FastAPI app:
+
+```bash
+curl -X POST http://127.0.0.1:5050/run/registry \
+  -H 'Content-Type: application/json' \
+  -d '{"base_url":"http://127.0.0.1:5050","vus":10,"duration_seconds":30}'
+```
+
+## Health check
+
+```bash
+curl http://127.0.0.1:5050/health
+```
+
+## Dashboard
+
+Open:
+
+```bash
+http://127.0.0.1:5050/
+```
+
+Dashboard includes:
+
+- live status + progress stream
+- metrics cards + quick chart bars
+- saved run history (persisted in `artifacts/history/runs.jsonl`)
+- React-based multi-tab control center (`Run Now`, `Live`, `Registered Targets`, `History`)
+
+## Notes
+
+- Registry targets are loaded when the module is imported.
+- Use `/run/targets` to submit explicit targets.
+- Use `/run/registry` to run all decorator-registered targets.

loaderup-0.1.4/agents/analyzer.py

@@ -0,0 +1,202 @@
+import json
+from datetime import datetime
+from typing import Any, Dict, Tuple
+from loader.models import SummaryMetrics
+
+
+def _metric_value(metrics: Dict[str, Any], metric_name: str, field: str):
+    metric = metrics.get(metric_name, {})
+    if not isinstance(metric, dict):
+        return None
+    return metric.get(field)
+
+
+def _checks_pass_rate(metrics: Dict[str, Any]) -> float | None:
+    checks = metrics.get("checks", {})
+    if not isinstance(checks, dict):
+        return None
+
+    # Some k6 outputs provide "value"
+    if "value" in checks:
+        return checks.get("value")
+
+    passes = checks.get("passes")
+    fails = checks.get("fails")
+
+    if isinstance(passes, (int, float)) and isinstance(fails, (int, float)):
+        total = passes + fails
+        if total > 0:
+            return passes / total
+
+    return None
+
+
+def _http_req_failed_rate(metrics: Dict[str, Any]) -> float | None:
+    failed = metrics.get("http_req_failed", {})
+    if not isinstance(failed, dict):
+        return None
+
+    # Best source in k6 summary output
+    value = failed.get("value")
+    if isinstance(value, (int, float)):
+        return float(value)
+
+    # Some formats may expose "rate"
+    rate = failed.get("rate")
+    if isinstance(rate, (int, float)):
+        return float(rate)
+
+    # Fallback: in k6 this metric is a Rate metric, and "passes"
+    # usually means failed requests, while "fails" means non-failed requests.
+    passes = failed.get("passes")
+    fails = failed.get("fails")
+
+    if isinstance(passes, (int, float)) and isinstance(fails, (int, float)):
+        total = passes + fails
+        if total > 0:
+            return float(passes) / float(total)
+
+    return None
+
+
+def parse_k6_summary(summary_path: str) -> Tuple[SummaryMetrics, Dict[str, Any]]:
+    with open(summary_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    metrics = data.get("metrics", {})
+
+    parsed = SummaryMetrics(
+        total_requests=_metric_value(metrics, "http_reqs", "count"),
+        avg_http_req_duration_ms=_metric_value(metrics, "http_req_duration", "avg"),
+        med_http_req_duration_ms=_metric_value(metrics, "http_req_duration", "med"),
+        p90_http_req_duration_ms=_metric_value(metrics, "http_req_duration", "p(90)"),
+        p95_http_req_duration_ms=_metric_value(metrics, "http_req_duration", "p(95)"),
+        max_http_req_duration_ms=_metric_value(metrics, "http_req_duration", "max"),
+        http_req_failed_rate=_http_req_failed_rate(metrics),
+        checks_pass_rate=_checks_pass_rate(metrics),
+    )
+
+    return parsed, data
+
+
+def _decode_diag_json(raw_json: str) -> dict[str, Any] | None:
+    candidates = [
+        raw_json,
+        raw_json.replace('\\"', '"'),
+        raw_json.encode("utf-8", errors="ignore").decode("unicode_escape", errors="ignore"),
+    ]
+
+    for candidate in candidates:
+        try:
+            data = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(data, dict):
+            return data
+    return None
+
+
+def parse_k6_diagnostics(stdout_text: str, stderr_text: str = "") -> list[dict[str, Any]]:
+    diagnostics: list[dict[str, Any]] = []
+    merged = "\n".join([stdout_text or "", stderr_text or ""])
+    if not merged.strip():
+        return diagnostics
+
+    marker = "LOADERUP_DIAG "
+
+    for line in merged.splitlines():
+        if marker not in line:
+            continue
+
+        payload_part = line.split(marker, 1)[1]
+        start = payload_part.find("{")
+        end = payload_part.rfind("}")
+        if start == -1 or end == -1 or end <= start:
+            continue
+
+        raw_json = payload_part[start : end + 1]
+        data = _decode_diag_json(raw_json)
+        if not data:
+            continue
+
+        diagnostics.append(data)
+
+    return diagnostics
+
+
+def _to_dt(value: str) -> datetime | None:
+    text = str(value or "").strip()
+    if not text:
+        return None
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    try:
+        return datetime.fromisoformat(text)
+    except ValueError:
+        return None
+
+
+def _p95(values: list[float]) -> float | None:
+    if not values:
+        return None
+    ordered = sorted(values)
+    idx = max(0, min(len(ordered) - 1, int(0.95 * (len(ordered) - 1))))
+    return float(ordered[idx])
+
+
+def parse_k6_latency_timeseries(stream_path: str) -> list[dict[str, Any]]:
+    buckets: dict[int, list[float]] = {}
+    start_time: datetime | None = None
+
+    with open(stream_path, "r", encoding="utf-8") as handle:
+        for line in handle:
+            line = line.strip()
+            if not line:
+                continue
+
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            if entry.get("type") != "Point" or entry.get("metric") != "http_req_duration":
+                continue
+
+            data = entry.get("data")
+            if not isinstance(data, dict):
+                continue
+
+            value = data.get("value")
+            if not isinstance(value, (int, float)):
+                continue
+
+            t = _to_dt(data.get("time", ""))
+            if not t:
+                continue
+
+            if start_time is None:
+                start_time = t
+
+            second = int((t - start_time).total_seconds()) + 1
+            if second < 1:
+                second = 1
+
+            buckets.setdefault(second, []).append(float(value))
+
+    if not buckets:
+        return []
+
+    points: list[dict[str, Any]] = []
+    for second in sorted(buckets):
+        values = buckets[second]
+        avg = sum(values) / len(values)
+        points.append(
+            {
+                "second": second,
+                "avg_ms": float(avg),
+                "p95_ms": _p95(values),
+                "count": len(values),
+            }
+        )
+
+    return points

{loaderup-0.1.2 → loaderup-0.1.4}/agents/generator.py

@@ -33,6 +33,7 @@ def build_k6_script(
 
     script = f"""import http from 'k6/http';
 import {{ check, sleep }} from 'k6';
+import {{ Counter }} from 'k6/metrics';
 
 export const options = {{
   vus: {vus},
@@ -41,6 +42,24 @@ export const options = {{
 
 const BASE_URL = {_js_string(base_url.rstrip("/"))};
 const TARGETS = {targets_json};
+const STATUS_CODE_COUNT = new Counter('status_code_count');
+const STATUS_429_SERVER_COUNT = new Counter('status_429_server_count');
+const MAX_DIAG_PER_RUN = 6;
+let diagCount = 0;
+
+function normalizeHeaders(headers) {{
+  const normalized = {{}};
+  for (const [key, value] of Object.entries(headers || {{}})) {{
+    if (Array.isArray(value)) {{
+      normalized[key] = value.join(', ');
+    }} else if (value === null || value === undefined) {{
+      normalized[key] = '';
+    }} else {{
+      normalized[key] = String(value);
+    }}
+  }}
+  return normalized;
+}}
 
 function weightedPick(targets) {{
   const expanded = [];
@@ -93,8 +112,44 @@ export default function () {{
   check(res, {{
     [`status is expected`]: (r) => r.status === target.expected_status,
     [`status is < 500`]: (r) => r.status < 500,
+    [`status code ${{res.status}}`]: () => true,
   }});
 
+  STATUS_CODE_COUNT.add(1, {{
+    status_code: String(res.status),
+    target_name: target.name,
+    method,
+    path: target.path,
+  }});
+
+  if (res.status === 429) {{
+    const headers = normalizeHeaders(res.headers);
+    const serverSignature = headers.Server || headers.server || 'unknown';
+    STATUS_429_SERVER_COUNT.add(1, {{
+      server_signature: String(serverSignature || 'unknown'),
+      target_name: target.name,
+      method,
+      path: target.path,
+    }});
+    check(res, {{
+      [`429 server ${{String(serverSignature || 'unknown')}}`]: () => true,
+    }});
+  }}
+
+  if (res.status === 429 && diagCount < MAX_DIAG_PER_RUN) {{
+    diagCount += 1;
+    const diagnostic = {{
+      status: res.status,
+      target_name: target.name,
+      method,
+      path: target.path,
+      url,
+      headers: normalizeHeaders(res.headers),
+      body_preview: String(res.body || '').slice(0, 2000),
+    }};
+    console.log(`LOADERUP_DIAG ${{JSON.stringify(diagnostic)}}`);
+  }}
+
   sleep(1);
 }}
 """

{loaderup-0.1.2 → loaderup-0.1.4}/agents/runner.py

@@ -7,12 +7,15 @@ async def run_k6(script_path: str, job_id: str) -> dict:
     out_dir.mkdir(parents=True, exist_ok=True)
 
     summary_path = out_dir / "summary.json"
+    metrics_stream_path = out_dir / "metrics.jsonl"
 
     process = await asyncio.create_subprocess_exec(
         "k6",
         "run",
         "--summary-export",
         str(summary_path),
+        "--out",
+        f"json={metrics_stream_path}",
         script_path,
         stdout=asyncio.subprocess.PIPE,
         stderr=asyncio.subprocess.PIPE,
@@ -35,6 +38,7 @@ async def run_k6(script_path: str, job_id: str) -> dict:
 
     return {
         "summary_path": str(summary_path),
+        "metrics_stream_path": str(metrics_stream_path),
         "stdout": stdout_text,
         "stderr": stderr_text,
-    }
+    }

{loaderup-0.1.2 → loaderup-0.1.4}/loader/demo_registry_target.py

@@ -1,8 +1,7 @@
 # demo_registry_targets.py
 
 from loaderup import load_target
-
-"""
+'''
 @load_target(
     name="home",
     method="GET",
@@ -12,7 +11,7 @@ from loaderup import load_target
 )
 def home():
     pass
-
+'''
 @load_target(
     name="home",
     method="POST",
@@ -22,4 +21,4 @@ def home():
 )
 def gg():
     pass
-"""
+

{loaderup-0.1.2 → loaderup-0.1.4}/loader/main.py

@@ -147,4 +147,4 @@ async def get_run_history(limit: int = 20):
 if __name__ == "__main__":
     import uvicorn
 
-    uvicorn.run(app, host="0.0.0.0", port=8000)
+    uvicorn.run(app, host="0.0.0.0", port=5050)

{loaderup-0.1.2 → loaderup-0.1.4}/loader/models.py

@@ -74,6 +74,13 @@ class TargetMetric(BaseModel):
     note: Optional[str] = None
 
 
+class LatencySeriesPoint(BaseModel):
+    second: int
+    avg_ms: Optional[float] = None
+    p95_ms: Optional[float] = None
+    count: int = 0
+
+
 class JobResult(BaseModel):
     config: Optional[RunConfig] = None
     k6_script_path: Optional[str] = None
@@ -83,6 +90,8 @@ class JobResult(BaseModel):
     metrics: Optional[SummaryMetrics] = None
     target_metrics: List[TargetMetric] = Field(default_factory=list)
     raw_summary: Optional[Dict[str, Any]] = None
+    status_diagnostics: List[Dict[str, Any]] = Field(default_factory=list)
+    latency_timeseries: List[LatencySeriesPoint] = Field(default_factory=list)
 
 
 class Job(BaseModel):

{loaderup-0.1.2 → loaderup-0.1.4}/loader/pipeline.py

@@ -3,7 +3,11 @@ from loader.history import persist_job
 from loader.store import get_job, update_job, push_event, close_queue
 from agents.generator import build_k6_script, save_k6_script
 from agents.runner import run_k6
-from agents.analyzer import parse_k6_summary
+from agents.analyzer import (
+    parse_k6_summary,
+    parse_k6_diagnostics,
+    parse_k6_latency_timeseries,
+)
 
 
 async def set_status(job, status: JobStatus, message: str):
@@ -66,6 +70,9 @@ async def run_targets_pipeline(job_id: str, config: RunConfig):
             job.result.k6_stdout = run_output["stdout"]
         if hasattr(job.result, "k6_stderr"):
             job.result.k6_stderr = run_output["stderr"]
+        job.result.status_diagnostics = parse_k6_diagnostics(
+            run_output["stdout"], run_output.get("stderr", "")
+        )
 
         update_job(job)
 
@@ -82,6 +89,9 @@ async def run_targets_pipeline(job_id: str, config: RunConfig):
         metrics, raw_summary = parse_k6_summary(run_output["summary_path"])
         job.result.metrics = metrics
         job.result.raw_summary = raw_summary
+        stream_path = run_output.get("metrics_stream_path")
+        if stream_path:
+            job.result.latency_timeseries = parse_k6_latency_timeseries(stream_path)
         update_job(job)
 
         await push_event(