annotations/_docs/02_document/tests/performance-tests.md

Performance Tests

Calibration note: no contracted SLAs exist anywhere in the codebase or acceptance_criteria.md. The thresholds below are inferred starting points anchored to the documented system properties. Step 15 (Performance Test) of the autodev existing-code flow will tune them against real targets. A test that fails the threshold is a signal, not a release-blocker, until the targets are contracted.

NFT-PERF-LATENCY-01: Annotation create — p95 latency, small image

Summary: Sequential POST /annotations with a small frame stays under a per-call threshold at p95. Traces to: implicit NFR; documented gap on AC-N-* (no contracted target) Metric: end-to-end response latency in ms (consumer wall-clock from request start to body close).

Preconditions:

• SUT freshly started; warmup loop of 10 sequential calls discarded.
• Clean state; clean outbox; RabbitMQ stream consumer not connected (writes fan out via channel + outbox only).
• Single in-process consumer (no concurrent load).

Steps:

Step	Consumer Action	Measurement
1	Warmup: 10× POST /annotations with image_small.jpg	discarded
2	Measure: 50× POST /annotations with image_small.jpg, sequential, single consumer	record latency per call
3	Compute p50, p95, p99	summary stats

Pass criteria: p95 ≤ 1500ms, p99 ≤ 3000ms (single-instance dev DB, no concurrent load). Duration: ~2 minutes.

---

NFT-PERF-LATENCY-02: Annotation create — large image

Summary: Same shape as -01 with a 7 MB image. Traces to: same as -01. Metric: end-to-end latency.

Preconditions: same as -01.

Steps:

Step	Consumer Action	Measurement
1	Warmup: 5× POST /annotations with image_large.JPG	discarded
2	Measure: 20× POST /annotations with image_large.JPG, sequential	record latency per call
3	p50, p95, p99	summary stats

Pass criteria: p95 ≤ 5000ms, p99 ≤ 8000ms. Duration: ~2 minutes.

---

NFT-PERF-THROUGHPUT-01: Annotation create — sustained writes

Summary: 5-minute sustained POST /annotations traffic at 5 RPS does not degrade response latency. Metric: response latency over time + total successful responses.

Preconditions: SUT warm; clean state; clean outbox; RabbitMQ broker reachable.

Steps:

Step	Consumer Action	Measurement
1	Warmup: 30s at 5 RPS with image_small.jpg	discarded
2	Measure: 5 minutes at 5 RPS, 1 consumer	record per-second latency p50/p95
3	Compare windows	p95 in last minute ≤ 1.5× p95 in first minute

Pass criteria: 0 HTTP 5xx; p95 latency in last minute ≤ 1.5× p95 in first minute. Duration: ~6 minutes.

---

NFT-PERF-OUTBOX-DRAIN-01: FailsafeProducer drain rate

Summary: Under sustained writes, the outbox queue depth stays bounded. Traces to: AC-N-03 Metric: SELECT COUNT(*) FROM annotations_queue_records sampled every 5s during the run.

Preconditions: NFT-PERF-THROUGHPUT-01 running; RabbitMQ broker reachable; no stream consumer back-pressure.

Steps:

Step	Consumer Action	Measurement
1	While -THROUGHPUT-01 is running, sample queue depth every 5s for the full duration	record samples
2	Compute max queue depth + average drain interval	summary stats

Pass criteria: max queue depth ≤ 100 rows; depth at end-of-run ≤ depth at start-of-run + 10. Duration: 5 minutes (overlaid on -THROUGHPUT-01).

---

NFT-PERF-SSE-FANOUT-01: SSE delivery latency under modest fan-out

Summary: 10 simultaneous SSE subscribers receive every event for their mission within the latency budget. Traces to: AC-F-10 Metric: per-subscriber event-arrival latency (consumer wall-clock from POST /annotations returning to SSE event arrival).

Preconditions: SUT warm; clean state.

Steps:

Step	Consumer Action	Measurement
1	Open 10 SSE connections to /annotations/events?missionId=<m>	all 10 alive
2	POST /annotations once for mission <m>	record post-return timestamp
3	Each subscriber records its event-arrival timestamp	per-subscriber latency
4	Compute max latency across the 10 subscribers	summary

Pass criteria: every subscriber receives the event; max latency ≤ 1000ms. Duration: 30s.

---

NFT-PERF-LIST-01: Annotation listing on populated DB

Summary: GET /annotations?limit=100 against a DB with 10,000 rows responds within budget. Metric: end-to-end response latency.

Preconditions: DB pre-seeded with 10,000 annotations + 50,000 detections (use dataseed to insert via direct SQL, bypassing the public API for population speed — the test still queries via the public API).

Steps:

Step	Consumer Action	Measurement
1	Warmup: 5× GET /annotations?limit=100&offset=0	discarded
2	Measure: 20× GET /annotations?limit=100&offset=<random 0..9000>	record per-call latency
3	p95	summary

Pass criteria: p95 ≤ 1000ms (read-only path; index ix_annotations_created_date should keep it fast). Duration: ~1 minute.

---

NFT-PERF-DATASET-01: Dataset class distribution at scale

Summary: GET /dataset/class-distribution against the populated DB. Metric: end-to-end latency.

Preconditions: same populated DB as NFT-PERF-LIST-01.

Steps:

Step	Consumer Action	Measurement
1	Warmup: 3 calls	discarded
2	Measure: 10 calls	record latency

Pass criteria: p95 ≤ 2000ms. Duration: ~30s.