2.10 LatencyProfiler

1. Bot Identity

Operational profile

2. Purpose

LatencyProfiler continuously measures round-trip order submission latency by route and surfaces regressions. It probes each configured route at probe_interval_s and emits ObservationReports when p95 or p99 thresholds are breached.

3. Why This Bot Matters

• Latency regression undetected

  Strategy signals age past their TTL in transit, causing stale-signal discards and missed opportunities without a clear root cause.

• Route not profiled per endpoint

  A degraded CLOB endpoint continues to receive orders because the routing layer lacks per-route latency data.

• WebSocket lag not tracked

  ws_user fill events arrive late, causing order lifecycle state to be updated with significant delay.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "warn_p95_ms": 150 }

if p95 > params.warn_p95_ms: emit(LATENCY_WARN)

{ "fail_p99_ms": 500 }

if p99 > params.fail_p99_ms: flagRoute(route, 'degraded')

{ "probe_interval_s": 30 }

assert params.probe_interval_s <= params.hard

{ "routes_to_probe": ["clob_auth", "ws_user"] }

if 'ws_user' not in params.routes_to_probe: emit(WARN)

8. Default Configuration

{
  "bot_id": "exec.latencyprofiler",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "warn_p95_ms": 150,
    "fail_p99_ms": 500,
    "probe_interval_s": 30,
    "routes_to_probe": [
      "clob_auth",
      "ws_user"
    ]
  },
  "locked": {
    "warn_p95_ms": {
      "max": 500
    },
    "fail_p99_ms": {
      "max": 1000
    },
    "probe_interval_s": {
      "max": 120
    }
  }
}

9. Implementation Flow

1. Every probe_interval_s, for each route in routes_to_probe: send a probe request and record send_ms.
2. For clob_auth: issue a lightweight GET /time or authenticated OPTIONS; record ack_ms.
3. For ws_user: compare heartbeat ts_ms to local now_ms; record feed_lag_ms.
4. Maintain a rolling window of the last 100 probe round-trip times per route.
5. Compute p50, p95, p99 from the rolling window.
6. If p95 > warn_p95_ms: emit ObservationReport(LATENCY_WARN) for the route.
7. If p99 > fail_p99_ms: emit ObservationReport(LATENCY_HARD_BREACH); flag route as degraded in internal state store.
8. Publish per-route latency histogram metrics every probe cycle.

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

FUNCTION probeRoute(route):
  sendMs = now_ms()
  IF route == 'clob_auth':
    result = clob_auth.GET('/time')  // lightweight probe
    ackMs = now_ms()
    rtt = ackMs - sendMs
    IF result IS NULL OR result.error:
      rtt = 1000  // count as max latency
  ELIF route == 'ws_user':
    hb = ws_user.lastHeartbeat()
    rtt = now_ms() - hb.ts_ms

  // Update rolling window
  windows[route].append(rtt)
  IF len(windows[route]) > 100:
    windows[route].pop(0)

  // Compute percentiles
  sorted_w = sorted(windows[route])
  p50 = sorted_w[int(0.50 * len(sorted_w))]
  p95 = sorted_w[int(0.95 * len(sorted_w))]
  p99 = sorted_w[int(0.99 * len(sorted_w))]

  // Threshold checks
  IF p99 > params.fail_p99_ms:
    routeState[route] = 'degraded'
    EMIT ObservationReport(route, p50, p95, p99, LATENCY_HARD_BREACH)
  ELIF p95 > params.warn_p95_ms:
    EMIT ObservationReport(route, p50, p95, p99, LATENCY_WARN)

SCHEDULE probeRoute FOR EACH route IN params.routes_to_probe
         EVERY params.probe_interval_s

SDK calls used

• clob_auth.GET('/time')
• ws_user.lastHeartbeat()

Complexity: O(W log W) where W = rolling window size (100)

11. Wire Examples

Input — what arrives on the wire

Probe trigger (internal scheduler) — internal

{
  "route": "clob_auth",
  "trigger_ts_ms": 1746770300000
}

Output — what the bot emits

ObservationReport — LATENCY_WARN

{
  "report_id": "rep_5e6f7a8b9c0d1e2f",
  "bot_id": "exec.latencyprofiler",
  "route": "clob_auth",
  "p50_ms": 45,
  "p95_ms": 160,
  "p99_ms": 280,
  "verdict": "LATENCY_WARN",
  "measured_at_ms": 1746770300000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ObservationReport object. See ObservationReport schema.

{
  "report_id": "rep_5e6f7a8b9c0d1e2f",
  "trace_id": "trc_4d5e6f7a8b9c0d1e",
  "bot_id": "exec.latencyprofiler",
  "route": "clob_auth",
  "p50_ms": 45,
  "p95_ms": 160,
  "p99_ms": 280,
  "verdict": "LATENCY_WARN",
  "window_size": 100,
  "measured_at_ms": 1746770300000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "route": "clob_auth",
  "p50_ms": 45,
  "p95_ms": 160,
  "p99_ms": 280,
  "warn_p95_ms": 150,
  "fail_p99_ms": 500,
  "samples": 100,
  "route_degraded": false
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Window cleared on restart; first probe cycle rebuilds estimates from scratch.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Flooding probe scheduler to exhaust rate-limit budget with unnecessary latency checks
• Injecting fake degraded-route state to suppress order submission on healthy routes

Mitigations

• Probe rate capped at 1/probe_interval_s per route; scheduler enforces minimum interval
• Route degraded state writable only by LatencyProfiler process; read by other exec bots via internal read-only API

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

LatencyProfiler incidents are always route degradations. Check CLOB status page and ws_user heartbeat freshness first.

On-call actions

Manual overrides

• polytraders bot unflag-route exec.latencyprofiler --route clob_auth — Route was incorrectly flagged degraded due to a probe anomaly; confirm route is healthy first.

Healthcheck

GET /internal/health/latencyprofiler -> 200 if All probed routes healthy, degraded_routes=0, p99 < fail_p99_ms on all routes. Red: degraded_routes > 0, probe_errors_total spiking, scheduler not firing.

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%