fixtureqa 0.4.19__tar.gz → 0.4.21__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fixtureqa
-Version: 0.4.19
+Version: 0.4.21
 Summary: FIXture — FIX Protocol Testing Tool
 Requires-Python: >=3.10
 License-File: LICENSE

{fixtureqa-0.4.19 → fixtureqa-0.4.21}/fixture/api/app.py

@@ -91,7 +91,7 @@ def create_app(
     perf_writer = PerfWriter(os.path.join(data_dir, "perf.db"))
     app.state.perf_writer = perf_writer
     app.state.perf_registry = RunRegistry(
-        perf_writer, execs_dir=os.path.join(data_dir, "perf_execs"))
+        perf_writer, latency_dir=os.path.join(data_dir, "perf_latency"))
     # Runs left non-terminal in perf.db were interrupted by a prior restart —
     # mark them errored so History doesn't show zombie 'running' rows.
     app.state.perf_registry.reconcile_interrupted()

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

@@ -180,19 +180,19 @@ def run_export(run_id: str, reg: REG, pw: PW, _admin: Admin,
             _csv_stream(pw, "perf_scenarios", pw.scenario_columns(), run_id),
             media_type="text/csv",
             headers={"Content-Disposition": f'attachment; filename="{run_id}_scenarios.csv"'})
-    if kind == "execs":
-        # CSV-direct: the run streams per-exec rows straight into this csv.gz; the
-        # gzip footer is only written when the run finishes, so a live file would
-        # download truncated.
+    if kind in ("latency", "execs"):   # "execs" kept for back-compat
+        # CSV-direct: the run streams per-message rows straight into this csv.gz;
+        # the gzip footer is only written when the run finishes, so a live file
+        # would download truncated.
         if _run_is_live(reg, run_id):
             raise HTTPException(status_code=409,
-                                detail="Run still active — the exec CSV is finalized when the run finishes")
-        path = reg.exec_csv_path(run_id)
+                                detail="Run still active — the latency CSV is finalized when the run finishes")
+        path = reg.latency_csv_path(run_id)
         if path is None:
             raise HTTPException(status_code=404,
-                                detail="No exec recording for this run (enable record_execs before starting)")
+                                detail="No per-message recording for this run (enable record_latency before starting)")
         return FileResponse(path, media_type="application/gzip",
-                            filename=f"{run_id}_execs.csv.gz")
+                            filename=f"{run_id}_latency.csv.gz")
     if kind == "both":
         buf = io.BytesIO()
         with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
@@ -200,47 +200,52 @@ def run_export(run_id: str, reg: REG, pw: PW, _admin: Admin,
                        _csv_text(pw, "perf_messages", pw.message_columns(), run_id))
             z.writestr(f"{run_id}_scenarios.csv",
                        _csv_text(pw, "perf_scenarios", pw.scenario_columns(), run_id))
-            execs_path = reg.exec_csv_path(run_id)
-            if execs_path is not None and not _run_is_live(reg, run_id):
+            latency_path = reg.latency_csv_path(run_id)
+            if latency_path is not None and not _run_is_live(reg, run_id):
                 # Already gzipped — store as-is rather than re-deflating.
-                z.write(execs_path, arcname=f"{run_id}_execs.csv.gz",
+                z.write(latency_path, arcname=f"{run_id}_latency.csv.gz",
                         compress_type=zipfile.ZIP_STORED)
         return Response(buf.getvalue(), media_type="application/zip",
                         headers={"Content-Disposition": f'attachment; filename="{run_id}.zip"'})
-    raise HTTPException(status_code=422, detail="kind must be messages|scenarios|execs|both")
+    raise HTTPException(status_code=422, detail="kind must be messages|scenarios|latency|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")):
+                    metric: str = Query("one_way"), agg: str = Query("both"),
+                    scale: str = Query("log")):
     """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"):
+    off-loop on first request and cached per (metric, agg, scale) — the CSV is
+    immutable once the run finishes. Needs record_latency; 404 otherwise, 409
+    while live."""
+    if (metric not in ("one_way", "round_trip", "both")
+            or agg not in ("scatter", "percentile", "both")
+            or scale not in ("log", "linear")):
         raise HTTPException(status_code=422,
-                            detail="metric must be one_way|round_trip|both; agg must be scatter|percentile|both")
+                            detail="metric must be one_way|round_trip|both; "
+                                   "agg must be scatter|percentile|both; scale must be log|linear")
     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)
+    csv_path = reg.latency_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)")
+                            detail="No per-message recording for this run (enable record_latency 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"
+    out_path = f"{csv_path[:-len('.csv.gz')]}_{metric}_{agg}_{scale}.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)
+                metric=metric, agg=agg, logy=(scale == "log"),
+                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))

fixtureqa-0.4.19/fixture/core/exec_csv_writer.py → fixtureqa-0.4.21/fixture/core/latency_csv_writer.py

@@ -1,10 +1,10 @@
 """
 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.
+(35=9), opt-in via test.record_latency.
 
 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.
+data/perf_latency/<run_id>.csv.gz and export serves the finished file as-is.
 Same non-blocking producer contract as PerfWriter: the event loop only does a
 put_nowait (drop+count when the bounded queue is full); all formatting and
 gzip/disk work happens on one daemon writer thread, so recording cannot add
@@ -26,7 +26,7 @@ logger = logging.getLogger(__name__)
 
 DEFAULT_MAX_QUEUE = 200_000
 
-EXEC_COLS = (
+LATENCY_COLS = (
     "run_id", "corr_id", "clordid", "exec_id",
     "kind",          # message kind / chart series key (engine-assigned):
                      #   client→venue: order / amend / cancel
@@ -45,7 +45,7 @@ EXEC_COLS = (
 )
 
 
-class ExecCsvWriter:
+class LatencyCsvWriter:
     def __init__(self, path: str, max_queue: int = DEFAULT_MAX_QUEUE):
         self.path = path
         os.makedirs(os.path.dirname(path), exist_ok=True)
@@ -79,7 +79,7 @@ class ExecCsvWriter:
         try:
             with gzip.open(self.path, "wt", newline="") as fh:
                 w = csv.writer(fh)
-                w.writerow(EXEC_COLS)
+                w.writerow(LATENCY_COLS)
                 while True:
                     item = self._queue.get()
                     if item is None:

{fixtureqa-0.4.19 → fixtureqa-0.4.21}/fixture/core/perf_charts.py

@@ -1,6 +1,6 @@
 """
 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 /
+(test.record_latency). One plot line/series per message `kind` (ack / fill /
 replace / canceled / cancel-reject / …): x = order send time (run progression),
 y = per-message latency.
 
@@ -53,10 +53,25 @@ def _pctl(sorted_vals: list[float], q: float) -> float:
     return sorted_vals[i]
 
 
+def _humanize_us(v, _pos=None) -> str:
+    """Format a microsecond value as a self-describing tick label, picking the
+    unit per tick so a log axis spanning µs→s reads '500µs / 1ms / 10ms / 1s'
+    instead of 10^1 / 10^2. Handles negatives (tag-60 clock skew)."""
+    if v == 0:
+        return "0"
+    sign, a = ("-" if v < 0 else ""), abs(v)
+    if a < 1_000:
+        return f"{sign}{a:g}µs"
+    if a < 1_000_000:
+        return f"{sign}{a / 1_000:g}ms"
+    return f"{sign}{a / 1_000_000:g}s"
+
+
 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."""
+    """Group (x_seconds_since_start, y_microseconds) points by kind from the gz
+    CSV for one metric ('one_way' or 'round_trip'): y = that latency column (raw
+    µs — the axis humanizes per tick), 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
@@ -68,11 +83,11 @@ def _read_points(csv_gz_path: str, metric: str):
                 continue
             try:
                 x = float(xraw)
-                y_ms = float(yraw) / 1000.0
+                y_us = float(yraw)
             except ValueError:
                 continue
             t0 = x if t0 is None else min(t0, x)
-            by_kind[r.get("kind") or "unknown"].append((x, y_ms))
+            by_kind[r.get("kind") or "unknown"].append((x, y_us))
     if t0 is not None:
         for pts in by_kind.values():
             pts[:] = [(x - t0, y) for (x, y) in pts]
@@ -98,15 +113,25 @@ def _draw(ax, by_kind, agg: str, bucket_s: float, logy: bool, ylabel: str, title
                        color=color, label=None if agg == "both" else kind,
                        edgecolors="none")
         if agg in ("percentile", "both"):
-            bx, p50, p99 = _bucketed(pts, bucket_s)
+            bx, p50, p99, pmax = _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")
+                # p100 / worst-case per bucket — the outlier envelope (faint dots)
+                ax.plot(bx, pmax, color=color, lw=0.8, ls=":", alpha=0.55,
+                        label=f"{kind} max")
+    from matplotlib.ticker import FuncFormatter, LogLocator, NullFormatter
     ax.set_xlabel("run time (s, from first send)")
     ax.set_ylabel(ylabel + ("  [log]" if logy else ""))
     if logy:
         ax.set_yscale("log")
+        # 1-2-5 per decade as labelled ticks (so narrow ranges still get several
+        # labels); finer minors as unlabelled gridlines.
+        ax.yaxis.set_major_locator(LogLocator(base=10, subs=(1.0, 2.0, 5.0)))
+        ax.yaxis.set_minor_locator(LogLocator(base=10, subs=tuple(x / 10 for x in range(10, 100))))
+        ax.yaxis.set_minor_formatter(NullFormatter())
+    ax.yaxis.set_major_formatter(FuncFormatter(_humanize_us))
     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)
@@ -147,7 +172,7 @@ def render_latency_chart(csv_gz_path: str, out_path: str, *, metric: str = "one_
     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}",
+        _draw(ax, by_kind, agg, bucket_s, logy, f"latency — {label}",
               base if len(panels) == 1 else f"{base} — {label}")
     fig.tight_layout()
     fig.savefig(out_path)
@@ -155,16 +180,18 @@ def render_latency_chart(csv_gz_path: str, out_path: str, *, metric: str = "one_
 
 
 def _bucketed(sorted_pts: list[tuple[float, float]], bucket_s: float):
-    """Per-bucket (center_x, p50, p99) over fixed-width time buckets."""
+    """Per-bucket (center_x, p50, p99, max) over fixed-width time buckets
+    (max = p100, the worst-case latency in the bucket)."""
     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 = [], [], []
+    bx, p50, p99, pmax = [], [], [], []
     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
+        pmax.append(ys[-1])
+    return bx, p50, p99, pmax

{fixtureqa-0.4.19 → fixtureqa-0.4.21}/fixture/core/perf_engine.py

@@ -31,7 +31,7 @@ from typing import Optional
 
 from fixcore.message.message import Message
 
-from .exec_csv_writer import ExecCsvWriter
+from .latency_csv_writer import LatencyCsvWriter
 from .fix_time import utc_timestamp
 from .perf_models import (
     RunConfig, RunStatus, LiveSnapshot, ClientLeg, VenueLeg, SnapshotErrors, LatencyStats,
@@ -49,7 +49,7 @@ T_ORDERQTY, T_ORDTYPE, T_PRICE, T_TIF, T_TRANSACTTIME = 38, 40, 44, 59, 60
 T_ORDERID, T_EXECID, T_EXECTRANSTYPE, T_EXECTYPE, T_ORDSTATUS = 37, 17, 20, 150, 39
 T_LASTQTY, T_LASTPX, T_CUMQTY, T_LEAVESQTY, T_AVGPX = 32, 31, 14, 151, 6
 
-# ExecType(150) → per-message latency-chart series label (see ExecCsvWriter).
+# ExecType(150) → per-message latency-chart series label (see LatencyCsvWriter).
 _EXEC_KIND = {
     "0": "ack", "1": "fill", "2": "fill", "F": "fill",
     "E": "pending-replace", "5": "replace",
@@ -124,13 +124,13 @@ class PerfRun:
     def __init__(self, run_id: str, config: RunConfig, sm: SessionManager, writer: PerfWriter,
                  template_store=None, owner_uid: str = "",
                  sender_comp_id: str = "", target_comp_id: str = "",
-                 execs_dir: Optional[str] = None):
+                 latency_dir: Optional[str] = None):
         self.run_id = run_id
         self.config = config
         self._sm = sm
         self._writer = writer
-        self._execs_dir = execs_dir
-        self._exec_csv: Optional[ExecCsvWriter] = None
+        self._latency_dir = latency_dir
+        self._latency_csv: Optional[LatencyCsvWriter] = None
 
         self.status: str = "pending"
         self.started_at: Optional[float] = None
@@ -209,14 +209,14 @@ class PerfRun:
         # message's monotonic recv_perf_ns can be expressed as a UTC wall time
         # (for the tag-60 latency path) without a second clock read per message.
         self._start_wall = time.time()
-        if self.config.test.record_execs:
+        if self.config.test.record_latency:
             if not (self._has_client or self._has_venue):
-                self.warnings.append("record_execs has no effect with no client or venue leg")
-            elif not self._execs_dir:
-                self.warnings.append("record_execs unavailable (no exec CSV directory configured)")
+                self.warnings.append("record_latency has no effect with no client or venue leg")
+            elif not self._latency_dir:
+                self.warnings.append("record_latency unavailable (no latency CSV directory configured)")
             else:
-                self._exec_csv = ExecCsvWriter(
-                    os.path.join(self._execs_dir, f"{self.run_id}.csv.gz"))
+                self._latency_csv = LatencyCsvWriter(
+                    os.path.join(self._latency_dir, f"{self.run_id}.csv.gz"))
                 if not self._one_way:
                     self.warnings.append(
                         "single-leg run: per-message one-way latency uses the wire "
@@ -298,10 +298,10 @@ class PerfRun:
             self._client_sub.close()
         if self._venue_sub:
             self._venue_sub.close()
-        if self._exec_csv is not None:
+        if self._latency_csv is not None:
             # Correlator is cancelled (no more enqueues); drain + gzip-finalize
             # off-loop — close() joins the writer thread.
-            await asyncio.to_thread(self._exec_csv.close)
+            await asyncio.to_thread(self._latency_csv.close)
         self.status = "stopped" if self._stopped_by_user else "completed"
         self._build_snapshot()
         self._publish()
@@ -822,10 +822,10 @@ class PerfRun:
                        send_at, recv_at, req_send_at, one_way_us, round_trip_us,
                        exec_type="", ord_status="", cum_qty=None, leaves_qty=None) -> None:
         """Append one message-crossing row to the per-message latency CSV
-        (opt-in via record_execs). Column order must match EXEC_COLS."""
-        if self._exec_csv is None:
+        (opt-in via record_latency). Column order must match LATENCY_COLS."""
+        if self._latency_csv is None:
             return
-        self._exec_csv.enqueue((
+        self._latency_csv.enqueue((
             self.run_id, corr, clordid, exec_id, kind, direction,
             send_at, recv_at, req_send_at, one_way_us, round_trip_us,
             exec_type, ord_status, cum_qty, leaves_qty,
@@ -836,7 +836,7 @@ class PerfRun:
         """Stamp a venue→client message's send time keyed by its ExecID, so the
         client correlator can compute one-way hub latency on receipt. No-op when
         not recording. Bounded: drop-oldest past the cap (age-swept too)."""
-        if self._exec_csv is None:
+        if self._latency_csv is None:
             return
         eid = msg.get_field_or(self.config.exec_id_tag, "") or msg.get_field_or(T_EXECID, "")
         if not eid:
@@ -858,7 +858,7 @@ class PerfRun:
         inbound side. Manager/loopback: one-way = venue recv − the client's send
         (from _pending, one clock). Venue-only: one-way = our recv − the
         counterparty's wire send time (tag-60), needing a synced clock."""
-        if self._exec_csv is None:
+        if self._latency_csv is None:
             return
         if self._one_way:
             entry = self._pending.get(corr)
@@ -888,7 +888,7 @@ class PerfRun:
         from the venue send registry (manager/loopback) or the counterparty's
         wire send time (tag-60, client-only — synced clock needed). round-trip:
         from the originating request's send in _pending (always our own clock)."""
-        if self._exec_csv is None:
+        if self._latency_csv is None:
             return
         vs = self._venue_sends.pop(exec_id, None) if exec_id else None
         if vs:
@@ -1307,9 +1307,9 @@ class RunRegistry:
     TICKET_TTL_S = 30.0
     _TERMINAL_STATES = ("completed", "stopped", "error")
 
-    def __init__(self, writer: PerfWriter, execs_dir: Optional[str] = None):
+    def __init__(self, writer: PerfWriter, latency_dir: Optional[str] = None):
         self._writer = writer
-        self._execs_dir = execs_dir
+        self._latency_dir = latency_dir
         self._runs: dict[str, PerfRun] = {}
         self._tickets: dict[str, tuple[str, float]] = {}
 
@@ -1317,17 +1317,17 @@ class RunRegistry:
                owner_uid: str = "", sender_comp_id: str = "", target_comp_id: str = "") -> PerfRun:
         run_id = str(uuid.uuid4())
         run = PerfRun(run_id, config, sm, self._writer, template_store, owner_uid,
-                      sender_comp_id, target_comp_id, execs_dir=self._execs_dir)
+                      sender_comp_id, target_comp_id, latency_dir=self._latency_dir)
         self._runs[run_id] = run
         run.start()
         return run
 
-    def exec_csv_path(self, run_id: str) -> Optional[str]:
+    def latency_csv_path(self, run_id: str) -> Optional[str]:
         """Path to the run's per-exec csv.gz, or None if it never recorded.
         The file is complete (gzip footer written) only once the run is terminal."""
-        if not self._execs_dir:
+        if not self._latency_dir:
             return None
-        path = os.path.join(self._execs_dir, f"{run_id}.csv.gz")
+        path = os.path.join(self._latency_dir, f"{run_id}.csv.gz")
         return path if os.path.exists(path) else None
 
     def get(self, run_id: str) -> Optional[PerfRun]:

{fixtureqa-0.4.19 → fixtureqa-0.4.21}/fixture/core/perf_models.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 
 from typing import Literal, Optional
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import AliasChoices, BaseModel, Field, model_validator
 
 RunMode = Literal["loopback", "manager", "client", "venue"]
 SaturationPolicy = Literal["pause", "drop_oldest"]
@@ -51,10 +51,14 @@ class TestConfig(BaseModel):
     max_pending: int = Field(default=100_000, gt=0)
     on_saturation: SaturationPolicy = "pause"
     output: str = "results"
-    # Record every inbound ExecutionReport (ack + each fill) to a per-run
-    # csv.gz for detailed latency analysis. Off by default: ~(1+fills_per_order)×
-    # the per-order row volume on disk.
-    record_execs: bool = False
+    # Record every message crossing (orders, amends, cancels + acks, fills,
+    # replies) to a per-run csv.gz — the source for the per-message latency
+    # charts. On by default; ~(2+fills_per_order)× the per-order row volume on
+    # disk. Turn off for pure throughput runs that don't need the latency CSV.
+    # Accepts the legacy key `record_execs` so saved configs / run history from
+    # before the rename still load.
+    record_latency: bool = Field(
+        default=True, validation_alias=AliasChoices("record_latency", "record_execs"))
 
 
 class AmendConfig(BaseModel):