Review Focus

Line count is high due to tests and metric declarations. Focus review on: (1) trader index-based cardinality management in exporter.py:200-217 to avoid high-cardinality address labels, (2) API error classification logic in _classify_api_error(), and (3) the (container_name, sample) tuple format change in MetricsStore callbacks.

Summary

Implements Phase 2 of COW-591 Prometheus exporter, adding API performance, container resource, per-trader, and baseline comparison metrics. This completes the full Prometheus metrics deliverable for the grant.

Changes

New Metrics Added

API Metrics

• cow_perf_api_requests_total - Counter for API requests by endpoint/method/status
• cow_perf_api_response_time_seconds - Histogram of API response times
• cow_perf_api_errors_total - Counter for API errors by type (client_error, server_error, timeout, connection_error)

Container Resource Metrics

• cow_perf_container_cpu_percent - Gauge for container CPU usage
• cow_perf_container_memory_bytes - Gauge for container memory usage
• cow_perf_container_network_rx_bytes - Gauge for network bytes received
• cow_perf_container_network_tx_bytes - Gauge for network bytes transmitted

Per-Trader Metrics

• cow_perf_trader_orders_submitted_total - Counter for orders submitted by trader index
• cow_perf_trader_orders_filled_total - Counter for orders filled by trader index
• cow_perf_traders_active - Gauge for count of currently active traders

Baseline Comparison Metrics

• cow_perf_baseline_comparison_percent - Gauge for percentage change from baseline
• cow_perf_regression_detected - Gauge for regression counts by severity
• cow_perf_regressions_total - Counter for total regressions detected

Code Changes

• MetricsRegistry: Added 4 new initialization methods for Phase 2 metric categories
• PrometheusExporter:
  • Added callback handlers for API (_update_api_metrics) and resource (_update_resource_metrics) types
  • Added trader tracking with index-based cardinality management
  • Added manual recording methods for all new metric types
• MetricsStore: Updated resource callback to pass (container_name, sample) tuple

How to Test

1. Run the test suite:

   poetry run pytest tests/unit/prometheus/ -v

2. Start exporter and verify metrics:

   from cow_performance.prometheus.exporter import PrometheusExporter
   
   exp = PrometheusExporter(port=9091, scenario='test')
   exp.start()
   exp.record_api_request('/api/v1/orders', 'POST', 200, 0.15)
   exp.update_container_resources('orderbook', 45.5, 536870912)
   # curl http://localhost:9091/metrics | grep cow_perf_

3. Run with CLI:

   cow-perf run --prometheus-port 9091 --duration 60

Checklist

• Tests pass (poetry run pytest tests/unit/prometheus/ - 56 passed)
• Linting passes (poetry run ruff check .)
• Type checking passes (poetry run mypy src/cow_performance/prometheus/)
• Implementation plan documented (thoughts/plans/2026-02-06-cow-591-phase-2-prometheus-exporter.md)

Breaking Changes

Minor: MetricsStore.add_resource_sample() now passes (container_name, sample) tuple to callbacks instead of just sample. This only affects code that registers callbacks for resource metrics.

Related Issues

• COW-591: Prometheus Exporters (Phase 2 completes this ticket)
• Enables COW-593: Grafana Dashboards (depends on these metrics)

🤖 Generated with Claude Code