oxirs_tdb/
advanced_diagnostics_types.rs

1//! Data types for advanced TDB diagnostics.
2//!
3//! This module defines the report and analysis structures produced by the
4//! [`AdvancedDiagnosticEngine`], along with the engine's internal tracking
5//! structures:
6//! - Public report types ([`AdvancedDiagnosticReport`] and its component analyses)
7//! - Trend/forecast types ([`PredictiveHealthIndicators`], [`CapacityForecast`], etc.)
8//! - The [`AdvancedDiagnosticEngine`] struct and its internal trackers
9//!
10//! [`AdvancedDiagnosticEngine`]: crate::advanced_diagnostics_types::AdvancedDiagnosticEngine
11
12use crate::diagnostics::Severity;
13use crate::storage::BufferPoolStats;
14use serde::{Deserialize, Serialize};
15use std::collections::{HashMap, VecDeque};
16use std::time::{Duration, SystemTime};
17
18/// Advanced diagnostic report with trend analysis
19#[derive(Debug, Clone, Serialize, Deserialize)]
20pub struct AdvancedDiagnosticReport {
21    /// Timestamp
22    pub timestamp: SystemTime,
23    /// Query performance analysis
24    pub query_analysis: QueryPerformanceAnalysis,
25    /// Transaction pattern analysis
26    pub transaction_analysis: TransactionPatternAnalysis,
27    /// Fragmentation analysis
28    pub fragmentation_analysis: FragmentationAnalysis,
29    /// Index usage statistics
30    pub index_usage: IndexUsageStatistics,
31    /// Predictive health indicators
32    pub predictive_health: PredictiveHealthIndicators,
33    /// Auto-tuning recommendations
34    pub tuning_recommendations: Vec<TuningRecommendation>,
35    /// Anomaly detections
36    pub anomalies: Vec<AnomalyDetection>,
37    /// Capacity planning forecast
38    pub capacity_forecast: CapacityForecast,
39}
40
41/// Query performance analysis
42#[derive(Debug, Clone, Serialize, Deserialize)]
43pub struct QueryPerformanceAnalysis {
44    /// Total queries analyzed
45    pub total_queries: u64,
46    /// Average query execution time
47    pub avg_execution_time: Duration,
48    /// Median query execution time
49    pub median_execution_time: Duration,
50    /// P95 query execution time
51    pub p95_execution_time: Duration,
52    /// P99 query execution time
53    pub p99_execution_time: Duration,
54    /// Slow query count (above threshold)
55    pub slow_query_count: u64,
56    /// Query patterns detected
57    pub query_patterns: Vec<QueryPattern>,
58    /// Optimization opportunities
59    pub optimization_opportunities: Vec<String>,
60    /// Query cache hit rate
61    pub cache_hit_rate: f64,
62}
63
64/// Query pattern detected in workload
65#[derive(Debug, Clone, Serialize, Deserialize)]
66pub struct QueryPattern {
67    /// Pattern signature (simplified query structure)
68    pub signature: String,
69    /// Frequency of this pattern
70    pub frequency: u64,
71    /// Average execution time for this pattern
72    pub avg_time: Duration,
73    /// Index usage for this pattern
74    pub indexes_used: Vec<String>,
75    /// Optimization potential (0.0 = none, 1.0 = high)
76    pub optimization_potential: f64,
77}
78
79/// Transaction pattern analysis
80#[derive(Debug, Clone, Serialize, Deserialize)]
81pub struct TransactionPatternAnalysis {
82    /// Total transactions analyzed
83    pub total_transactions: u64,
84    /// Average transaction duration
85    pub avg_duration: Duration,
86    /// Median transaction duration
87    pub median_duration: Duration,
88    /// Transaction commit rate
89    pub commit_rate: f64,
90    /// Transaction abort rate
91    pub abort_rate: f64,
92    /// Conflict rate (conflicts per transaction)
93    pub conflict_rate: f64,
94    /// Deadlock rate (deadlocks per 1000 transactions)
95    pub deadlock_rate: f64,
96    /// Lock contention points
97    pub contention_points: Vec<ContentionPoint>,
98    /// Transaction size distribution
99    pub size_distribution: TransactionSizeDistribution,
100}
101
102/// Lock contention point
103#[derive(Debug, Clone, Serialize, Deserialize)]
104pub struct ContentionPoint {
105    /// Resource identifier (e.g., "SPO_INDEX", "DICTIONARY")
106    pub resource: String,
107    /// Number of contentions detected
108    pub contention_count: u64,
109    /// Average wait time
110    pub avg_wait_time: Duration,
111    /// Severity (0.0 = low, 1.0 = high)
112    pub severity: f64,
113}
114
115/// Transaction size distribution
116#[derive(Debug, Clone, Serialize, Deserialize)]
117pub struct TransactionSizeDistribution {
118    /// Small transactions (< 10 operations)
119    pub small_pct: f64,
120    /// Medium transactions (10-100 operations)
121    pub medium_pct: f64,
122    /// Large transactions (> 100 operations)
123    pub large_pct: f64,
124}
125
126/// Storage fragmentation analysis
127#[derive(Debug, Clone, Serialize, Deserialize)]
128pub struct FragmentationAnalysis {
129    /// Overall fragmentation percentage
130    pub overall_fragmentation_pct: f64,
131    /// Dictionary fragmentation
132    pub dictionary_fragmentation_pct: f64,
133    /// Index fragmentation by type
134    pub index_fragmentation: HashMap<String, f64>,
135    /// Free space distribution
136    pub free_space_distribution: Vec<FreeSpaceRegion>,
137    /// Compaction benefit estimate (space recoverable)
138    pub compaction_benefit_bytes: u64,
139    /// Recommended compaction priority (0.0 = low, 1.0 = critical)
140    pub compaction_priority: f64,
141}
142
143/// Free space region in storage
144#[derive(Debug, Clone, Serialize, Deserialize)]
145pub struct FreeSpaceRegion {
146    /// Starting offset
147    pub offset: u64,
148    /// Size in bytes
149    pub size: u64,
150}
151
152/// Index usage statistics
153#[derive(Debug, Clone, Serialize, Deserialize)]
154pub struct IndexUsageStatistics {
155    /// Total index scans performed
156    pub total_scans: u64,
157    /// Usage by index type
158    pub usage_by_index: HashMap<String, IndexUsageStats>,
159    /// Unused indexes
160    pub unused_indexes: Vec<String>,
161    /// Overused indexes (potential bottleneck)
162    pub overused_indexes: Vec<String>,
163    /// Missing index opportunities
164    pub missing_index_opportunities: Vec<MissingIndexOpportunity>,
165}
166
167/// Statistics for a specific index
168#[derive(Debug, Clone, Serialize, Deserialize)]
169pub struct IndexUsageStats {
170    /// Number of scans
171    pub scan_count: u64,
172    /// Average selectivity (rows returned / rows scanned)
173    pub avg_selectivity: f64,
174    /// Average scan time
175    pub avg_scan_time: Duration,
176    /// Index efficiency score (0.0 = inefficient, 1.0 = highly efficient)
177    pub efficiency_score: f64,
178}
179
180/// Opportunity to create a missing index
181#[derive(Debug, Clone, Serialize, Deserialize)]
182pub struct MissingIndexOpportunity {
183    /// Suggested index name
184    pub suggested_index: String,
185    /// Query patterns that would benefit
186    pub benefiting_patterns: Vec<String>,
187    /// Estimated performance improvement (percentage)
188    pub estimated_improvement_pct: f64,
189}
190
191/// Predictive health indicators
192#[derive(Debug, Clone, Serialize, Deserialize)]
193pub struct PredictiveHealthIndicators {
194    /// Time series of historical metrics
195    pub historical_metrics: HistoricalMetrics,
196    /// Predicted issues in next 24 hours
197    pub predicted_issues_24h: Vec<PredictedIssue>,
198    /// Predicted issues in next 7 days
199    pub predicted_issues_7d: Vec<PredictedIssue>,
200    /// Health trend (improving, stable, degrading)
201    pub health_trend: HealthTrend,
202    /// Resource exhaustion predictions
203    pub resource_predictions: ResourcePredictions,
204}
205
206/// Historical metrics for trend analysis
207#[derive(Debug, Clone, Serialize, Deserialize)]
208pub struct HistoricalMetrics {
209    /// Number of data points
210    pub data_points: usize,
211    /// Time range covered
212    pub time_range: Duration,
213    /// Query latency trend (per hour)
214    pub query_latency_trend: Vec<f64>,
215    /// Transaction throughput trend (per hour)
216    pub txn_throughput_trend: Vec<f64>,
217    /// Storage growth trend (bytes per hour)
218    pub storage_growth_trend: Vec<f64>,
219    /// Error rate trend (errors per hour)
220    pub error_rate_trend: Vec<f64>,
221}
222
223/// Predicted issue
224#[derive(Debug, Clone, Serialize, Deserialize)]
225pub struct PredictedIssue {
226    /// Issue category
227    pub category: String,
228    /// Issue description
229    pub description: String,
230    /// Confidence level (0.0 = low, 1.0 = certain)
231    pub confidence: f64,
232    /// Estimated time until issue occurs
233    pub eta: Duration,
234    /// Severity if issue occurs
235    pub severity: Severity,
236    /// Preventive action
237    pub preventive_action: String,
238}
239
240/// Health trend direction
241#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
242pub enum HealthTrend {
243    /// System health is improving
244    Improving,
245    /// System health is stable
246    Stable,
247    /// System health is degrading slowly
248    DegradingSlowly,
249    /// System health is degrading rapidly
250    DegradingRapidly,
251}
252
253/// Resource exhaustion predictions
254#[derive(Debug, Clone, Serialize, Deserialize)]
255pub struct ResourcePredictions {
256    /// Predicted storage full date
257    pub storage_full_eta: Option<SystemTime>,
258    /// Predicted memory exhaustion
259    pub memory_exhaustion_eta: Option<SystemTime>,
260    /// Predicted connection pool saturation
261    pub connection_saturation_eta: Option<SystemTime>,
262}
263
264/// Auto-tuning recommendation
265#[derive(Debug, Clone, Serialize, Deserialize)]
266pub struct TuningRecommendation {
267    /// Configuration parameter
268    pub parameter: String,
269    /// Current value
270    pub current_value: String,
271    /// Recommended value
272    pub recommended_value: String,
273    /// Rationale
274    pub rationale: String,
275    /// Expected impact
276    pub expected_impact: String,
277    /// Priority (0.0 = low, 1.0 = critical)
278    pub priority: f64,
279}
280
281/// Anomaly detection
282#[derive(Debug, Clone, Serialize, Deserialize)]
283pub struct AnomalyDetection {
284    /// Metric name
285    pub metric: String,
286    /// Anomaly description
287    pub description: String,
288    /// Detected value
289    pub detected_value: f64,
290    /// Expected value range
291    pub expected_range: (f64, f64),
292    /// Deviation from normal (standard deviations)
293    pub deviation: f64,
294    /// Detection timestamp
295    pub detected_at: SystemTime,
296    /// Severity
297    pub severity: Severity,
298}
299
300/// Capacity planning forecast
301#[derive(Debug, Clone, Serialize, Deserialize)]
302pub struct CapacityForecast {
303    /// Current storage usage (bytes)
304    pub current_storage_bytes: u64,
305    /// Predicted storage in 30 days
306    pub predicted_30d_bytes: u64,
307    /// Predicted storage in 90 days
308    pub predicted_90d_bytes: u64,
309    /// Growth rate (bytes per day)
310    pub growth_rate_per_day: f64,
311    /// Days until 80% capacity
312    pub days_until_80pct: Option<u32>,
313    /// Days until 90% capacity
314    pub days_until_90pct: Option<u32>,
315    /// Recommended actions
316    pub recommended_actions: Vec<String>,
317}
318
319/// Advanced diagnostic engine
320pub struct AdvancedDiagnosticEngine {
321    /// Historical metrics buffer (circular buffer)
322    pub(crate) historical_buffer: VecDeque<MetricSnapshot>,
323    /// Maximum history size (24 hours of hourly snapshots)
324    pub(crate) max_history_size: usize,
325    /// Query performance tracker
326    pub(crate) query_tracker: QueryPerformanceTracker,
327    /// Transaction pattern tracker
328    pub(crate) transaction_tracker: TransactionPatternTracker,
329    /// Anomaly detector
330    pub(crate) anomaly_detector: AnomalyDetector,
331}
332
333/// Snapshot of metrics at a point in time
334#[derive(Debug, Clone)]
335pub(crate) struct MetricSnapshot {
336    pub(crate) timestamp: SystemTime,
337    pub(crate) query_latency: f64,
338    pub(crate) txn_throughput: f64,
339    pub(crate) storage_bytes: u64,
340    pub(crate) error_count: u64,
341    #[allow(dead_code)]
342    pub(crate) buffer_pool_stats: BufferPoolStats,
343}
344
345/// Query performance tracker
346pub(crate) struct QueryPerformanceTracker {
347    /// Query execution times (most recent 1000)
348    pub(crate) recent_queries: VecDeque<Duration>,
349    /// Query patterns
350    pub(crate) patterns: HashMap<String, QueryPatternStats>,
351    /// Cache hits vs misses
352    pub(crate) cache_hits: u64,
353    pub(crate) cache_misses: u64,
354}
355
356#[derive(Debug, Clone)]
357pub(crate) struct QueryPatternStats {
358    pub(crate) frequency: u64,
359    pub(crate) total_time: Duration,
360    pub(crate) indexes_used: Vec<String>,
361}
362
363/// Transaction pattern tracker
364pub(crate) struct TransactionPatternTracker {
365    /// Recent transaction durations
366    pub(crate) recent_durations: VecDeque<Duration>,
367    /// Commit/abort counts
368    pub(crate) commits: u64,
369    pub(crate) aborts: u64,
370    /// Conflict tracking
371    pub(crate) conflicts: u64,
372    pub(crate) deadlocks: u64,
373    /// Contention points
374    pub(crate) contention_map: HashMap<String, ContentionStats>,
375}
376
377#[derive(Debug, Clone)]
378pub(crate) struct ContentionStats {
379    pub(crate) count: u64,
380    pub(crate) total_wait_time: Duration,
381}
382
383/// Anomaly detector using statistical methods
384pub(crate) struct AnomalyDetector {
385    /// Detection threshold (standard deviations)
386    pub(crate) threshold: f64,
387}
oxirs_tdb/advanced_diagnostics_types.rs

oxirs_tdb/
advanced_diagnostics_types.rs
