fixtureqa 0.4.17__tar.gz → 0.4.19__tar.gz

{fixtureqa-0.4.17/fixtureqa.egg-info → fixtureqa-0.4.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fixtureqa
-Version: 0.4.17
+Version: 0.4.19
 Summary: FIXture — FIX Protocol Testing Tool
 Requires-Python: >=3.10
 License-File: LICENSE
@@ -10,6 +10,7 @@ Requires-Dist: uvicorn[standard]>=0.29.0
 Requires-Dist: websockets>=12.0
 Requires-Dist: python-jose[cryptography]>=3.3.0
 Requires-Dist: passlib[bcrypt]>=1.7.4
+Requires-Dist: matplotlib>=3.7
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

{fixtureqa-0.4.17 → fixtureqa-0.4.19}/fixture/api/routers/perf.py

@@ -5,9 +5,11 @@ Stage 1a: run lifecycle (start/list/get/stop) + live snapshot WS. The WS uses a
 short-TTL single-use ticket (JWT never in the URL); the rest of the contract
 (messages/scenarios/export/configs) lands in later stages.
 """
+import asyncio
 import csv
 import io
 import logging
+import os
 import zipfile
 from typing import Annotated, Optional
 
@@ -16,6 +18,7 @@ from fastapi.responses import FileResponse, Response, StreamingResponse
 
 from ...core.models import SessionStatus
 from ...core.perf_models import RunConfig, RunStatus
+from ...core.perf_charts import render_latency_chart
 from ...core.perf_engine import RunRegistry
 from ...core.perf_payload import PerfConfigError
 from ...core.perf_store import PerfStore
@@ -207,6 +210,44 @@ def run_export(run_id: str, reg: REG, pw: PW, _admin: Admin,
     raise HTTPException(status_code=422, detail="kind must be messages|scenarios|execs|both")
 
 
+@router.get("/runs/{run_id}/chart")
+async def run_chart(run_id: str, reg: REG, _admin: Admin,
+                    metric: str = Query("one_way"), agg: str = Query("both")):
+    """Per-message latency chart (PNG) from the run's recorded csv.gz. Rendered
+    off-loop on first request and cached per (metric, agg) — the CSV is immutable
+    once the run finishes. Needs record_execs; 404 otherwise, 409 while live."""
+    if metric not in ("one_way", "round_trip", "both") or agg not in ("scatter", "percentile", "both"):
+        raise HTTPException(status_code=422,
+                            detail="metric must be one_way|round_trip|both; agg must be scatter|percentile|both")
+    if not reg.exists(run_id):
+        raise HTTPException(status_code=404, detail="Run not found")
+    if _run_is_live(reg, run_id):
+        raise HTTPException(status_code=409,
+                            detail="Run still active — the latency chart is rendered when the run finishes")
+    csv_path = reg.exec_csv_path(run_id)
+    if csv_path is None or not os.path.exists(csv_path):
+        raise HTTPException(status_code=404,
+                            detail="No per-message recording for this run (enable record_execs before starting)")
+    # Single-leg runs (client/venue) derive one-way from the wire send time;
+    # label it so the chart can't be misread as the single-clock measurement.
+    st = reg.get_status(run_id)
+    one_way_label = None
+    if st is not None and st.mode not in ("loopback", "manager"):
+        one_way_label = "one-way (tag-60 wire send → recv; needs synced clocks)"
+    out_path = f"{csv_path[:-len('.csv.gz')]}_{metric}_{agg}.png"
+    if not os.path.exists(out_path):
+        try:
+            await asyncio.to_thread(
+                render_latency_chart, csv_path, out_path,
+                metric=metric, agg=agg, title=f"Per-message latency — {run_id}",
+                one_way_label=one_way_label)
+        except ValueError as e:
+            # No chartable points (e.g. recording produced only un-latencied rows).
+            raise HTTPException(status_code=404, detail=str(e))
+    return FileResponse(out_path, media_type="image/png",
+                        filename=f"{run_id}_latency.png")
+
+
 # --- saved configs --------------------------------------------------------
 
 @router.get("/configs")

{fixtureqa-0.4.17 → fixtureqa-0.4.19}/fixture/core/exec_csv_writer.py

@@ -1,6 +1,7 @@
 """
-Per-run gzipped CSV recorder for individual ExecutionReports (opt-in via
-test.record_execs).
+Per-run gzipped CSV recorder for individual inbound correlated messages —
+every ExecutionReport (ack, fill, amend/cancel reply) plus OrderCancelReject
+(35=9), opt-in via test.record_execs.
 
 CSV-direct: there is no database staging — rows stream straight to
 data/perf_execs/<run_id>.csv.gz and export serves the finished file as-is.
@@ -10,6 +11,7 @@ gzip/disk work happens on one daemon writer thread, so recording cannot add
 latency to the measured inbound path.
 
 One instance per recording run; it owns its file exclusively for its lifetime.
+Drives scripts/perf_latency_chart.py (per-`kind` latency plots).
 """
 from __future__ import annotations
 
@@ -26,14 +28,20 @@ DEFAULT_MAX_QUEUE = 200_000
 
 EXEC_COLS = (
     "run_id", "corr_id", "clordid", "exec_id",
-    "exec_type", "ord_status",                      # tags 150 / 39
-    "last_qty", "last_px", "cum_qty", "leaves_qty",  # tags 32 / 31 / 14 / 151
-    "exec_seq",      # 1-based report index within the order
-    "sent_at",       # wall clock of the order send (same for all the order's rows)
-    "recv_at",       # wall clock of this report's receive
-    "latency_us",    # client receive − order send (one monotonic clock — authoritative;
-                     # recv_at − sent_at is wall clock, for cross-referencing only)
-    "gap_us",        # since the previous report for this order; empty on the first
+    "kind",          # message kind / chart series key (engine-assigned):
+                     #   client→venue: order / amend / cancel
+                     #   venue→client: ack / fill / pending-replace / replace /
+                     #                 pending-cancel / canceled / cancel-reject / amend-reject
+    "direction",     # c2v (client→hub→venue) | v2c (venue→hub→client)
+    "send_at",       # wall clock of THIS message's send on the near leg (one-way x-axis)
+    "recv_at",       # wall clock of THIS message's receive on the far leg
+    "req_send_at",   # wall clock of the originating request's send (order/amend/cancel
+                     #   send; == send_at for c2v rows) — the round-trip x-axis
+    "one_way_us",    # this message's one-way transit. manager/loopback: recv − send on
+                     #   one monotonic clock. client/venue-only: recv − the wire send time
+                     #   (TransactTime 60 / SendingTime 52), needs a synced clock.
+    "round_trip_us",  # v2c only: recv − the originating request's send (our clock); empty for c2v
+    "exec_type", "ord_status", "cum_qty", "leaves_qty",  # tags 150 / 39 / 14 / 151 (forensics)
 )
 
 

fixtureqa-0.4.19/fixture/core/perf_charts.py

@@ -0,0 +1,170 @@
+"""
+Post-run per-message latency charts from a recorded run's csv.gz
+(test.record_execs). One plot line/series per message `kind` (ack / fill /
+replace / canceled / cancel-reject / …): x = order send time (run progression),
+y = per-message latency.
+
+Single implementation, two callers: scripts/perf_latency_chart.py (offline CLI)
+and the FastAPI /perf/runs/{id}/chart endpoint (rendered off-loop and cached).
+
+matplotlib is imported lazily inside render_latency_chart so importing this
+module (and starting the server) never pays the matplotlib import cost; the
+render uses the Agg backend via the object-oriented Figure API, which is
+safe to run on a worker thread (no pyplot global state, no GUI backend).
+"""
+from __future__ import annotations
+
+import csv
+import gzip
+from collections import defaultdict
+from typing import Optional
+
+# Stable colour per kind so charts are comparable across runs (mirrors the live
+# dashboard hues). Unknown kinds fall back to the mpl cycle.
+_KIND_COLOR = {
+    "order": "#38bdf8",            # client→venue
+    "ack": "#00b4c8",
+    "fill": "#a78bfa",
+    "amend": "#f59e0b",            # client→venue
+    "pending-replace": "#c084fc",
+    "replace": "#7c3aed",
+    "cancel": "#fb7185",           # client→venue
+    "pending-cancel": "#fb923c",
+    "canceled": "#2dd4bf",
+    "cancel-reject": "#f43f5e",
+    "amend-reject": "#ef4444",
+}
+# Drawing order: order lifecycle, then amend, then cancel (request before reply).
+_KIND_ORDER = ["order", "ack", "fill", "amend", "pending-replace", "replace",
+               "cancel", "pending-cancel", "canceled", "cancel-reject", "amend-reject"]
+
+# Per metric: (latency column, x-axis column, axis label).
+_METRIC = {
+    "one_way":   ("one_way_us",   "send_at",     "one-way hub transit"),
+    "round_trip": ("round_trip_us", "req_send_at", "round-trip"),
+}
+
+
+def _pctl(sorted_vals: list[float], q: float) -> float:
+    """Nearest-rank percentile of an already-sorted list (q in 0..1)."""
+    if not sorted_vals:
+        return 0.0
+    i = min(len(sorted_vals) - 1, max(0, int(round(q * (len(sorted_vals) - 1)))))
+    return sorted_vals[i]
+
+
+def _read_points(csv_gz_path: str, metric: str):
+    """Group (x_seconds_since_start, y_ms) points by kind from the gz CSV for one
+    metric ('one_way' or 'round_trip'): y = that latency column, x = its send
+    column rebased to seconds since the first send."""
+    y_col, x_col, _ = _METRIC[metric]
+    by_kind: dict[str, list[tuple[float, float]]] = defaultdict(list)
+    t0: Optional[float] = None
+    with gzip.open(csv_gz_path, "rt", newline="") as fh:
+        for r in csv.DictReader(fh):
+            yraw = r.get(y_col) or ""
+            xraw = r.get(x_col) or ""
+            if yraw == "" or xraw == "":
+                continue
+            try:
+                x = float(xraw)
+                y_ms = float(yraw) / 1000.0
+            except ValueError:
+                continue
+            t0 = x if t0 is None else min(t0, x)
+            by_kind[r.get("kind") or "unknown"].append((x, y_ms))
+    if t0 is not None:
+        for pts in by_kind.values():
+            pts[:] = [(x - t0, y) for (x, y) in pts]
+    return by_kind
+
+
+def _ordered_kinds(by_kind) -> list[str]:
+    known = [k for k in _KIND_ORDER if k in by_kind]
+    extra = sorted(k for k in by_kind if k not in _KIND_COLOR)
+    return known + extra
+
+
+def _draw(ax, by_kind, agg: str, bucket_s: float, logy: bool, ylabel: str, title: str):
+    for kind in _ordered_kinds(by_kind):
+        pts = sorted(by_kind[kind])
+        if not pts:
+            continue
+        color = _KIND_COLOR.get(kind)
+        xs = [p[0] for p in pts]
+        ys = [p[1] for p in pts]
+        if agg in ("scatter", "both"):
+            ax.scatter(xs, ys, s=6, alpha=0.25 if agg == "both" else 0.5,
+                       color=color, label=None if agg == "both" else kind,
+                       edgecolors="none")
+        if agg in ("percentile", "both"):
+            bx, p50, p99 = _bucketed(pts, bucket_s)
+            if bx:
+                ax.plot(bx, p50, color=color, lw=1.6, label=f"{kind} p50")
+                ax.plot(bx, p99, color=color, lw=1.0, ls="--", alpha=0.7,
+                        label=f"{kind} p99")
+    ax.set_xlabel("run time (s, from first send)")
+    ax.set_ylabel(ylabel + ("  [log]" if logy else ""))
+    if logy:
+        ax.set_yscale("log")
+    ax.grid(True, which="both", ls=":", alpha=0.4)
+    ax.legend(loc="upper left", fontsize=8, ncol=2, framealpha=0.85)
+    ax.set_title(title)
+
+
+def render_latency_chart(csv_gz_path: str, out_path: str, *, metric: str = "one_way",
+                         agg: str = "both", bucket_s: float = 2.0,
+                         logy: bool = True, kinds: Optional[list[str]] = None,
+                         title: Optional[str] = None, one_way_label: Optional[str] = None) -> str:
+    """Render a per-kind latency chart from a recorded run CSV to out_path (PNG).
+
+    metric: 'one_way' (recv − send, this message's hub transit; x = its own send
+    time) | 'round_trip' (recv − the originating request's send; x = request send)
+    | 'both' (two stacked panels, one-way above round-trip).
+    agg: 'scatter' = one point per message; 'percentile' = per-kind p50 & p99 over
+    `bucket_s`-second buckets (exposes backlog); 'both' overlays them.
+
+    Blocking + CPU-bound (matplotlib) — call off the event loop. Returns out_path.
+    Raises ValueError if the CSV has no usable points for the metric.
+    """
+    import matplotlib
+    matplotlib.use("Agg")
+    from matplotlib.figure import Figure
+
+    metrics = ["one_way", "round_trip"] if metric == "both" else [metric]
+    panels = []
+    for m in metrics:
+        by_kind = _read_points(csv_gz_path, m)
+        if kinds:
+            by_kind = {k: v for k, v in by_kind.items() if k in set(kinds)}
+        if any(by_kind.values()):
+            panels.append((m, by_kind))
+    if not panels:
+        raise ValueError(f"no chartable {metric!r} latency points in {csv_gz_path}")
+
+    fig = Figure(figsize=(12, 6.5 * len(panels)), dpi=120)
+    axes = fig.subplots(len(panels), 1, squeeze=False)[:, 0]
+    base = title or "Per-message latency"
+    for ax, (m, by_kind) in zip(axes, panels):
+        label = one_way_label if (m == "one_way" and one_way_label) else _METRIC[m][2]
+        _draw(ax, by_kind, agg, bucket_s, logy, f"latency (ms) — {label}",
+              base if len(panels) == 1 else f"{base} — {label}")
+    fig.tight_layout()
+    fig.savefig(out_path)
+    return out_path
+
+
+def _bucketed(sorted_pts: list[tuple[float, float]], bucket_s: float):
+    """Per-bucket (center_x, p50, p99) over fixed-width time buckets."""
+    if bucket_s <= 0:
+        bucket_s = 1.0
+    buckets: dict[int, list[float]] = defaultdict(list)
+    for x, y in sorted_pts:
+        buckets[int(x // bucket_s)].append(y)
+    bx, p50, p99 = [], [], []
+    for b in sorted(buckets):
+        ys = sorted(buckets[b])
+        bx.append((b + 0.5) * bucket_s)
+        p50.append(_pctl(ys, 0.50))
+        p99.append(_pctl(ys, 0.99))
+    return bx, p50, p99