tidaldb/.sdlc/features/pg1-instrumented-metrics/qa-plan.md

pg1-instrumented-metrics: QA Plan

Unit Tests

histogram.rs (T1)

• percentile_empty_returns_none -- percentile on empty histogram returns None
• percentile_single_observation -- single obs returns correct percentile
• percentile_known_distribution -- 3 observations, verify p50/p99 match expected
• percentile_beyond_all_bounds -- observation above max bound still tracked
• total_count_tracks_observations -- total_count increments correctly
• render_percentile_gauges_empty -- empty histogram produces empty string
• render_percentile_gauges_format -- gauges contain correct metric names and values

metrics/mod.rs (T2, T3, T6)

• user_signal_timestamp_map_record_get -- record and retrieve a timestamp
• user_signal_timestamp_map_eviction -- map evicts when over capacity
• user_signal_timestamp_map_cap_respected -- map never exceeds cap
• render_diagnostics_valid_json -- render_diagnostics returns parseable JSON
• signal_writes_by_type_increment -- per-type counter increments correctly

Integration Tests

pg1_instrumented_metrics.rs (T7)

• prometheus_contains_percentile_gauges -- /metrics output includes p50/p95/p99 gauge lines for signal write, retrieve, and search latencies
• prometheus_contains_per_type_counters -- /metrics output includes tidaldb_signal_writes_by_type{signal_type="view"} after writing view signals
• prometheus_contains_staleness_histogram -- /metrics output includes tidaldb_personalization_staleness_us after user query
• diagnostics_endpoint_returns_json -- /diagnostics returns HTTP 200 with valid JSON containing expected keys

Non-Functional Verification

• All new code is behind #[cfg(feature = "metrics")] -- verify cargo check passes without the feature flag
• No new dependencies added to Cargo.toml
• Existing test suite (1345 lib tests) still passes after changes

Exit Criteria

1. All unit tests pass: cargo test --manifest-path tidal/Cargo.toml --lib --features metrics
2. Integration test passes: cargo test --manifest-path tidal/Cargo.toml --test pg1_instrumented_metrics --features metrics,test-utils
3. No regressions: full lib test suite passes
4. Clippy clean: cargo clippy --manifest-path tidal/Cargo.toml -- -D warnings
5. Format clean: cargo fmt --manifest-path tidal/Cargo.toml --check