tidaldb/.sdlc/features/pg1-instrumented-metrics/tasks.md

pg1-instrumented-metrics: Tasks

T1: Percentile Methods on LatencyHistogram

Files: tidal/src/db/metrics/histogram.rs

Add total_count(), percentile(p), and render_percentile_gauges(name) methods to LatencyHistogram. Add 7 unit tests covering: empty histogram, single observation, known distribution, beyond all bounds, total_count tracking, empty gauges render, format validation.

Tests: cargo test --manifest-path tidal/Cargo.toml --lib histogram --features metrics

T2: Per-Signal-Type Write Counters

Files: tidal/src/db/metrics/mod.rs, tidal/src/db/signals.rs

Add signal_writes_by_type: DashMap<String, AtomicU64> field to MetricsState. In signal(), after existing metrics block, increment the per-type counter (bounded at 256 entries). Update render_prometheus() to emit per-type counter lines.

Tests: cargo test --manifest-path tidal/Cargo.toml --lib --features metrics

T3: UserSignalTimestampMap

Files: tidal/src/db/metrics/mod.rs, tidal/src/db/signals.rs

Add UserSignalTimestampMap struct with new(), record(), get(), evict_oldest(). Add user_last_signal field to MetricsState. In signal_with_context(), record user timestamp before dispatch.

Tests: Unit tests for record/get/eviction in metrics module.

T4: Personalization Staleness Histogram

Files: tidal/src/db/metrics/mod.rs, tidal/src/db/query_ops.rs

Add personalization_staleness: LatencyHistogram field to MetricsState with staleness-appropriate bounds. At the top of retrieve() and search(), compute and record staleness. Update render_prometheus() with staleness histogram + percentiles.

Tests: cargo test --manifest-path tidal/Cargo.toml --lib --features metrics

T5: Feedback-Loop Latency Histogram

Files: tidal/src/db/metrics/mod.rs, tidal/src/db/query_ops.rs

Add feedback_loop_latency: LatencyHistogram field to MetricsState. After result assembly in retrieve() and search(), check if user's signaled entity is in results (within 60s) and record loop latency. Update render_prometheus().

Tests: cargo test --manifest-path tidal/Cargo.toml --lib --features metrics

T6: /diagnostics JSON Endpoint

Files: tidal/src/db/metrics/mod.rs, tidal/src/db/http.rs

Add render_diagnostics() method to MetricsState returning JSON with per-type counts, latency percentiles, staleness percentiles, feedback-loop percentiles. Add /diagnostics route to HTTP server (feature-gated).

Tests: cargo test --manifest-path tidal/Cargo.toml --lib --features metrics

T7: Integration Test

Files: tidal/tests/pg1_instrumented_metrics.rs

End-to-end test: open db with metrics feature, write signals with user context, run retrieve/search queries, verify Prometheus output contains new metric names and /diagnostics returns parseable JSON.

Tests: cargo test --manifest-path tidal/Cargo.toml --test pg1_instrumented_metrics --features metrics,test-utils