fixtureqa 0.4.18__tar.gz → 0.4.20__tar.gz

{fixtureqa-0.4.18/fixtureqa.egg-info → fixtureqa-0.4.20}/PKG-INFO

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

{fixtureqa-0.4.18 → fixtureqa-0.4.20}/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.18 → fixtureqa-0.4.20}/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,14 +200,14 @@ 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")
@@ -215,7 +215,7 @@ 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."""
+    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"):
         raise HTTPException(status_code=422,
                             detail="metric must be one_way|round_trip|both; agg must be scatter|percentile|both")
@@ -224,16 +224,23 @@ async def run_chart(run_id: str, reg: REG, _admin: Admin,
     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"
     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}")
+                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))

fixtureqa-0.4.18/fixture/core/exec_csv_writer.py → fixtureqa-0.4.20/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,26 +26,26 @@ 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
                      #   venue→client: ack / fill / pending-replace / replace /
                      #                 pending-cancel / canceled / cancel-reject / amend-reject
-    "direction",     # c2v (client→hub→venue) | v2c (venue→hub→client) | rt
-                     #   (rt = round-trip-only fallback, client/venue-only modes)
+    "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",    # recv_ns − send_ns: this message's transit through the hub, one
-                     #   monotonic clock (empty in client/venue-only modes — no far leg)
-    "round_trip_us",  # v2c only: recv_ns − the originating request's send_ns; empty for c2v
+    "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)
 )
 
 
-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.18 → fixtureqa-0.4.20}/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.
 
@@ -115,7 +115,7 @@ def _draw(ax, by_kind, agg: str, bucket_s: float, logy: bool, ylabel: str, 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) -> str:
+                         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
@@ -146,7 +146,7 @@ def render_latency_chart(csv_gz_path: str, out_path: str, *, metric: str = "one_
     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 = _METRIC[m][2]
+        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()

{fixtureqa-0.4.18 → fixtureqa-0.4.20}/fixture/core/perf_engine.py

@@ -26,11 +26,12 @@ import random
 import time
 import uuid
 from collections import deque
+from datetime import datetime, timezone
 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,
@@ -48,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",
@@ -96,17 +97,40 @@ def _to_float(v) -> Optional[float]:
         return None
 
 
+# Wire send-time tags for the tag-60 latency path (client/venue-only modes):
+# TransactTime(60), falling back to the session SendingTime(52) which every
+# message carries (e.g. 35=9 has no TransactTime).
+_LAT_TS_TAGS = (60, 52)
+
+
+def _parse_fix_ts(fields: dict) -> Optional[float]:
+    """The counterparty's wall-clock send time (epoch seconds, UTC) from
+    TransactTime(60) → SendingTime(52). Returns None if absent/unparseable.
+    Used only when FIXture sees one leg, so the send timestamp must come off the
+    wire — accuracy then depends on the two hosts' clocks being NTP/PTP-synced."""
+    for tag in _LAT_TS_TAGS:
+        val = fields.get(tag)
+        if not val:
+            continue
+        for fmt in ("%Y%m%d-%H:%M:%S.%f", "%Y%m%d-%H:%M:%S"):
+            try:
+                return datetime.strptime(val, fmt).replace(tzinfo=timezone.utc).timestamp()
+            except ValueError:
+                continue
+    return None
+
+
 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
@@ -181,16 +205,23 @@ class PerfRun:
         self.status = "running"
         self.started_at = time.time()
         self._start_ns = time.perf_counter_ns()
-        if self.config.test.record_execs:
-            # Per-exec capture happens in the client-leg correlator; venue-only
-            # runs have nothing to record.
-            if not self._has_client:
-                self.warnings.append("record_execs has no effect in venue mode (no client leg)")
-            elif not self._execs_dir:
-                self.warnings.append("record_execs unavailable (no exec CSV directory configured)")
+        # Wall-clock anchored to the same instant as _start_ns, so an inbound
+        # 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_latency:
+            if not (self._has_client or self._has_venue):
+                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 "
+                        "send time (TransactTime 60 / SendingTime 52) — accurate only "
+                        "if this host and the counterparty share a synced clock")
         if self.config.amend.enabled and not self._has_client:
             self.warnings.append(
                 "amend injection has no effect in venue mode (no client leg); "
@@ -267,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()
@@ -791,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,
@@ -805,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:
@@ -817,38 +848,58 @@ class PerfRun:
         sends[eid] = {"kind": kind, "send_ns": send_ns, "send_wall": time.time(),
                       "corr": corr, "clordid": clordid}
 
+    def _recv_wall(self, recv_ns: int) -> float:
+        """Wall-clock (epoch secs) of an inbound message, anchored to the same
+        instant as its monotonic recv_perf_ns — for the tag-60 latency path."""
+        return self._start_wall + (recv_ns - self._start_ns) / 1e9
+
     def _record_c2v(self, of: dict, corr: str, recv_ns: int, kind: str) -> None:
         """Record a client→venue crossing (order/amend/cancel) at the venue
-        inbound side: one-way latency = venue recv − the client's send (looked up
-        in _pending). Only when we drive both legs on one clock (manager/loopback)."""
-        if self._exec_csv is None or not self._one_way:
+        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._latency_csv is None:
             return
-        entry = self._pending.get(corr)
-        if entry is None:
-            return
-        ns_key = {"order": "sent_ns", "amend": "amend_sent_ns",
-                  "cancel": "cancel_sent_ns"}[kind]
-        send_ns = entry.get(ns_key)
-        if not send_ns:
-            return
-        send_at = entry.get(ns_key[:-2] + "at")   # *_sent_ns → *_sent_at
+        if self._one_way:
+            entry = self._pending.get(corr)
+            if entry is None:
+                return
+            ns_key = {"order": "sent_ns", "amend": "amend_sent_ns",
+                      "cancel": "cancel_sent_ns"}[kind]
+            send_ns = entry.get(ns_key)
+            if not send_ns:
+                return
+            send_at = entry.get(ns_key[:-2] + "at")   # *_sent_ns → *_sent_at
+            one_way_us = (recv_ns - send_ns) / 1000.0
+        else:
+            ts = _parse_fix_ts(of)
+            if ts is None:
+                return
+            send_at = ts
+            one_way_us = (self._recv_wall(recv_ns) - ts) * 1e6
         self._emit_crossing(
             corr=corr, clordid=of.get(T_CLORDID), exec_id=None, kind=kind,
             direction="c2v", send_at=send_at, recv_at=time.time(),
-            req_send_at=send_at, one_way_us=(recv_ns - send_ns) / 1000.0,
-            round_trip_us=None)
+            req_send_at=send_at, one_way_us=one_way_us, round_trip_us=None)
 
     def _record_v2c(self, f: dict, corr, exec_id, now_ns: int, kind: str,
                     entry: Optional[dict]) -> None:
-        """Record a venue→client crossing at the client inbound side: one-way
-        latency from the venue send registry (manager/loopback), and round-trip
-        from the originating request's send time in _pending. Client-only mode
-        has no registry hit → round-trip only, direction 'rt'."""
-        if self._exec_csv is None:
+        """Record a venue→client crossing at the client inbound side. one-way:
+        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._latency_csv is None:
             return
         vs = self._venue_sends.pop(exec_id, None) if exec_id else None
-        one_way_us = ((now_ns - vs["send_ns"]) / 1000.0) if vs else None
-        send_at = vs["send_wall"] if vs else None
+        if vs:
+            one_way_us = (now_ns - vs["send_ns"]) / 1000.0
+            send_at = vs["send_wall"]
+        elif not self._one_way:
+            ts = _parse_fix_ts(f)
+            one_way_us = ((self._recv_wall(now_ns) - ts) * 1e6) if ts is not None else None
+            send_at = ts
+        else:
+            one_way_us = send_at = None
         rt_us = req_send_at = None
         ns_key = _KIND_REQ_NS.get(kind)
         if entry is not None and ns_key:
@@ -858,8 +909,7 @@ class PerfRun:
                 req_send_at = entry.get(ns_key[:-2] + "at")   # *_sent_ns → *_sent_at
         clordid = (entry.get("clordid") if entry else None) or (vs["clordid"] if vs else None)
         self._emit_crossing(
-            corr=corr, clordid=clordid, exec_id=exec_id, kind=kind,
-            direction="v2c" if self._one_way else "rt",
+            corr=corr, clordid=clordid, exec_id=exec_id, kind=kind, direction="v2c",
             send_at=send_at, recv_at=time.time(), req_send_at=req_send_at,
             one_way_us=one_way_us, round_trip_us=rt_us,
             exec_type=f.get(T_EXECTYPE, ""), ord_status=f.get(T_ORDSTATUS, ""),
@@ -1257,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]] = {}
 
@@ -1267,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.18 → fixtureqa-0.4.20}/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):