rusty_feeder/provider/ext/
metrics.rs

1//! Metrics collection and reporting for the HFT provider system
2//!
3//! This module contains comprehensive metrics structures for monitoring
4//! trading performance, latency, order flow, and execution quality.
5
6use anyhow::Result;
7use async_trait::async_trait;
8use rustc_hash::FxHashMap;
9use rusty_model::instruments::InstrumentId;
10
11use crate::feeder::FeedStats;
12use crate::provider::connection::ConnectionStats;
13
14/// Comprehensive metrics for a specific trading instrument
15///
16/// Contains all monitoring data for a single instrument including connection health,
17/// data feed statistics, order flow analysis, and performance metrics. All timestamps
18/// are in nanoseconds for HFT precision.
19#[derive(Debug, Clone)]
20pub struct InstrumentMetrics {
21    /// The instrument identifier these metrics apply to
22    pub instrument_id: InstrumentId,
23    /// Data feed statistics (messages per second, drop rate, etc.)
24    pub feed_stats: FeedStats,
25    /// Connection health and performance statistics
26    pub connection_stats: ConnectionStats,
27    /// Order flow analysis metrics
28    pub order_flow_metrics: OrderFlowMetrics,
29    /// Detailed latency breakdown
30    pub latency_metrics: LatencyMetrics,
31    /// Anomaly detection score (0.0 = normal, 1.0 = highly anomalous)
32    pub anomaly_score: f64,
33    /// Overall health score (0.0 = critical, 1.0 = perfect health)
34    pub health_score: f64,
35    /// Timestamp of last update in nanoseconds
36    pub last_updated: u64,
37}
38
39/// Aggregated metrics across all actively monitored instruments
40///
41/// Provides system-wide performance metrics for monitoring overall health
42/// and identifying systemic issues that affect multiple instruments.
43#[derive(Debug, Clone)]
44pub struct AggregatedMetrics {
45    /// Number of instruments being monitored
46    pub total_instruments: usize,
47    /// Total messages processed across all instruments
48    pub total_messages_processed: u64,
49    /// Total messages dropped due to processing issues
50    pub total_dropped_messages: u64,
51    /// Average latency across all instruments in nanoseconds
52    pub avg_latency_ns: u64,
53    /// Maximum observed latency in nanoseconds
54    pub max_latency_ns: u64,
55    /// 99th percentile latency in nanoseconds
56    pub p99_latency_ns: u64,
57    /// Total memory usage by the monitoring system in bytes
58    pub total_memory_usage_bytes: usize,
59    /// Total error count across all components
60    pub total_errors: u32,
61    /// System-wide health score (0.0 = critical, 1.0 = perfect)
62    pub overall_health_score: f64,
63    /// Number of currently active alerts
64    pub active_alerts: u32,
65    /// Timestamp of metric collection in nanoseconds
66    pub timestamp: u64,
67}
68
69/// Order flow specific metrics for HFT trading analysis
70///
71/// Captures market microstructure dynamics including volume imbalances,
72/// spread analysis, and market impact estimation crucial for HFT strategies.
73#[derive(Debug, Clone)]
74pub struct OrderFlowMetrics {
75    /// Buy/sell volume imbalance ratio (-1.0 to 1.0, positive = buy pressure)
76    pub volume_imbalance: f64,
77    /// Order book pressure ratio (bid volume / ask volume)
78    pub book_pressure: f64,
79    /// Trade intensity measured in trades per second
80    pub trade_intensity: f64,
81    /// Average trade size in base currency
82    pub avg_trade_size: rust_decimal::Decimal,
83    /// Price volatility as rolling standard deviation
84    pub price_volatility: f64,
85    /// Average spread in basis points
86    pub avg_spread_bps: f64,
87    /// Maximum observed spread in basis points
88    pub max_spread_bps: f64,
89    /// Estimated market impact in basis points
90    pub market_impact_bps: f64,
91}
92
93/// Detailed latency breakdown for performance optimization
94///
95/// Breaks down end-to-end latency into components to identify bottlenecks
96/// in the data processing pipeline. All values in nanoseconds for precision.
97#[derive(Debug, Clone)]
98pub struct LatencyMetrics {
99    /// Network latency from exchange timestamp to first byte received
100    pub network_latency_ns: u64,
101    /// Time spent parsing raw message into structured data
102    pub parsing_latency_ns: u64,
103    /// Time spent processing structured data in application logic
104    pub processing_latency_ns: u64,
105    /// Total end-to-end latency from exchange to strategy
106    pub total_latency_ns: u64,
107    /// Latency variance measured as standard deviation
108    pub latency_jitter_ns: u64,
109}
110
111/// Latency distribution statistics for detailed performance analysis
112///
113/// Provides percentile breakdown and histogram data for understanding
114/// latency patterns and identifying outliers.
115#[derive(Debug, Clone)]
116pub struct LatencyDistribution {
117    /// 50th percentile (median) latency in nanoseconds
118    pub p50_ns: u64,
119    /// 90th percentile latency in nanoseconds
120    pub p90_ns: u64,
121    /// 95th percentile latency in nanoseconds
122    pub p95_ns: u64,
123    /// 99th percentile latency in nanoseconds
124    pub p99_ns: u64,
125    /// 99.9th percentile latency in nanoseconds
126    pub p99_9_ns: u64,
127    /// Maximum observed latency in nanoseconds
128    pub max_ns: u64,
129    /// Histogram buckets for distribution visualization
130    pub histogram: Vec<LatencyBucket>,
131}
132
133/// Individual histogram bucket for latency distribution
134#[derive(Debug, Clone)]
135pub struct LatencyBucket {
136    /// Lower bound of this bucket in nanoseconds (inclusive)
137    pub min_ns: u64,
138    /// Upper bound of this bucket in nanoseconds (exclusive)
139    pub max_ns: u64,
140    /// Number of samples in this bucket
141    pub count: u64,
142}
143
144/// Trading-specific performance metrics for strategy analysis
145///
146/// Advanced metrics for evaluating trading performance including
147/// price benchmarks and microstructure signal analysis.
148#[derive(Debug, Clone)]
149pub struct TradingMetrics {
150    /// Order flow imbalance indicator (-1.0 to 1.0)
151    pub order_flow_imbalance: f64,
152    /// Volume-weighted average price over measurement period
153    pub vwap: rust_decimal::Decimal,
154    /// Time-weighted average price over measurement period
155    pub twap: rust_decimal::Decimal,
156    /// Collection of microstructure trading signals
157    pub microstructure_signals: MicrostructureSignals,
158    /// Execution quality measurements
159    pub execution_quality: ExecutionQualityMetrics,
160}
161
162/// Microstructure signals for algorithmic trading strategies
163///
164/// Real-time signals derived from order book and trade data that
165/// indicate short-term price movements and trading opportunities.
166#[derive(Debug, Clone)]
167pub struct MicrostructureSignals {
168    /// Order book imbalance signal (-1.0 to 1.0, positive = bid heavy)
169    pub book_imbalance: f64,
170    /// Accuracy of trade direction predictions (0.0 to 1.0)
171    pub trade_sign_accuracy: f64,
172    /// Short-term alpha generation signal strength
173    pub alpha_signal: f64,
174    /// Price momentum indicator (-1.0 to 1.0)
175    pub momentum: f64,
176    /// Mean reversion opportunity signal (0.0 to 1.0)
177    pub mean_reversion: f64,
178}
179
180/// Execution quality metrics for post-trade analysis
181///
182/// Measures the quality of trade execution including slippage,
183/// market impact, and fill rates essential for strategy optimization.
184#[derive(Debug, Clone)]
185pub struct ExecutionQualityMetrics {
186    /// Average slippage in basis points (negative = favorable)
187    pub slippage_bps: f64,
188    /// Estimated market impact in basis points
189    pub market_impact_bps: f64,
190    /// Percentage of orders successfully filled (0.0 to 1.0)
191    pub fill_rate: f64,
192    /// Average time from order submission to fill in nanoseconds
193    pub avg_fill_time_ns: u64,
194    /// Implementation shortfall in basis points
195    pub implementation_shortfall_bps: f64,
196}
197
198/// Trait for implementing custom metrics collectors
199///
200/// Allows extending the monitoring system with domain-specific metrics
201/// that are collected periodically and included in reports.
202///
203/// # Example Implementation
204///
205/// ```rust,no_run
206/// use async_trait::async_trait;
207/// use anyhow::Result;
208/// use rusty_feeder::provider::metrics::{MetricsCollector, CustomMetric};
209/// use rustc_hash::FxHashMap;
210///
211/// struct LatencyPercentileCollector {
212///     percentiles: Vec<f64>,
213/// }
214///
215/// #[async_trait]
216/// impl MetricsCollector for LatencyPercentileCollector {
217///     async fn collect(&self) -> Result<Vec<CustomMetric>> {
218///         let mut metrics = Vec::new();
219///         let mut tags = FxHashMap::default();
220///
221///         for percentile in &self.percentiles {
222///             tags.insert("percentile".to_string(), percentile.to_string());
223///             metrics.push(CustomMetric {
224///                 name: "custom_latency_percentile".to_string(),
225///                 value: 1000.0, // Example value
226///                 tags: tags.clone(),
227///                 timestamp: quanta::Instant::now().as_nanos() as u64,
228///             });
229///         }
230///
231///         Ok(metrics)
232///     }
233///
234///     fn name(&self) -> &str {
235///         "latency_percentile_collector"
236///     }
237/// }
238/// ```
239#[async_trait]
240pub trait MetricsCollector: Send + Sync {
241    /// Collects custom metrics when invoked by the monitoring system
242    ///
243    /// This method is called periodically to gather custom metrics.
244    /// Implementations should be efficient as this runs in the monitoring loop.
245    async fn collect(&self) -> Result<Vec<CustomMetric>>;
246
247    /// Returns the unique name of this collector
248    ///
249    /// Used for identification and preventing duplicate registrations.
250    fn name(&self) -> &str;
251}
252
253/// Definition of a custom metric with tags
254///
255/// Represents a single metric value with associated metadata tags
256/// for dimensional analysis in monitoring systems.
257#[derive(Debug, Clone)]
258pub struct CustomMetric {
259    /// Metric name following Prometheus naming conventions
260    pub name: String,
261    /// Numeric value of the metric
262    pub value: f64,
263    /// Key-value tags for metric dimensions
264    pub tags: FxHashMap<String, String>,
265    /// Collection timestamp in nanoseconds
266    pub timestamp: u64,
267}
rusty_feeder/provider/ext/metrics.rs

rusty_feeder/provider/ext/
metrics.rs
