# 🦀 Rust Rule Engine - GRL Edition
A powerful, high-performance rule engine for Rust supporting **GRL (Grule Rule Language)** syntax with advanced features like method calls, custom functions, object interactions, and both file-based and inline rule management.
[](https://crates.io/crates/rust-rule-engine)
[](https://docs.rs/rust-rule-engine)
[](https://opensource.org/licenses/MIT)
## 🌟 Key Features
- **🔥 GRL-Only Support**: Pure Grule Rule Language syntax (no JSON)
- **📄 Rule Files**: External `.grl` files for organized rule management
- **📝 Inline Rules**: Define rules as strings directly in your code
- **📞 Custom Functions**: Register and call user-defined functions from rules
- **🎯 Method Calls**: Support for `Object.metho## 📋 Changelog
### v0.3.1 (October 2025) - REST API with Monitoring
- **🌐 Production REST API**: Complete web API with advanced analytics integration
- Comprehensive endpoints for rule execution and monitoring
- Real-time analytics dashboard with performance insights
- Health monitoring and system status endpoints
- CORS support and proper error handling
- Sample requests and complete API documentation
- Production-ready demo script for testing
### v0.3.0 (October 2025) - AST-Based Dependency Analysis & Advanced Analyticsrgs)` and property access
- **🧠 Knowledge Base**: Centralized rule management with salience-based execution
- **💾 Working Memory**: Facts system for complex object interactions
- **⚡ High Performance**: Optimized execution engine with cycle detection
- **🛡️ Type Safety**: Rust's type system ensures runtime safety
- **🏗️ Builder Pattern**: Clean API with `RuleEngineBuilder`
- **📈 Execution Statistics**: Detailed performance metrics and debugging
- **🔍 Smart Dependency Analysis**: AST-based field dependency detection and conflict resolution
- **🚀 Parallel Processing**: Multi-threaded rule execution with automatic dependency management
- **📊 Rule Templates**: Parameterized rule templates for scalable rule generation
- **🌊 Stream Processing**: Real-time event processing with time windows (optional)
- **📊 Analytics**: Built-in aggregations and trend analysis
- **🚨 Action Handlers**: Custom action execution for rule consequences
- **📈 Advanced Analytics**: Production-ready performance monitoring and optimization insights
## 🚀 Quick Start
Add to your `Cargo.toml`:
```toml
[dependencies]
rust-rule-engine = "0.3.1"
# For streaming features
rust-rule-engine = { version = "0.3.1", features = ["streaming"] }
```
### 📄 File-Based Rules
Create a rule file `rules/example.grl`:
```grl
rule "AgeCheck" salience 10 {
when
User.Age >= 18 && User.Country == "US"
then
User.setIsAdult(true);
User.setCategory("Adult");
log("User qualified as adult");
}
rule "VIPUpgrade" salience 20 {
when
User.IsAdult == true && User.SpendingTotal > 1000.0
then
User.setIsVIP(true);
log("User upgraded to VIP status");
}
```
```rust
use rust_rule_engine::{RuleEngineBuilder, Value, Facts};
use std::collections::HashMap;
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create engine with rule file
let mut engine = RuleEngineBuilder::new()
.with_rule_file("rules/example.grl")?
.build();
// Register custom functions
engine.register_function("User.setIsAdult", |args, _| {
println!("Setting adult status: {}", args[0]);
Ok(Value::Boolean(true))
});
engine.register_function("User.setCategory", |args, _| {
println!("Setting category: {}", args[0]);
Ok(Value::String(args[0].to_string()))
});
// Create facts
let facts = Facts::new();
let mut user = HashMap::new();
user.insert("Age".to_string(), Value::Integer(25));
user.insert("Country".to_string(), Value::String("US".to_string()));
user.insert("SpendingTotal".to_string(), Value::Number(1500.0));
facts.add_value("User", Value::Object(user))?;
// Execute rules
let result = engine.execute(&facts)?;
println!("Rules fired: {}", result.rules_fired);
Ok(())
}
```
### 📝 Inline String Rules
Define rules directly in your code:
```rust
use rust_rule_engine::{RuleEngineBuilder, Value, Facts};
use std::collections::HashMap;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let grl_rules = r#"
rule "HighValueCustomer" salience 20 {
when
Customer.TotalSpent > 1000.0
then
sendWelcomeEmail(Customer.Email, "GOLD");
log("Customer upgraded to GOLD tier");
}
rule "LoyaltyBonus" salience 15 {
when
Customer.OrderCount >= 10
then
applyLoyaltyBonus(Customer.Id, 50.0);
log("Loyalty bonus applied");
}
"#;
// Create engine with inline rules
let mut engine = RuleEngineBuilder::new()
.with_inline_grl(grl_rules)?
.build();
// Register custom functions
engine.register_function("sendWelcomeEmail", |args, _| {
println!("📧 Welcome email sent to {} for {} tier", args[0], args[1]);
Ok(Value::Boolean(true))
});
engine.register_function("applyLoyaltyBonus", |args, _| {
println!("💰 Loyalty bonus of {} applied to customer {}", args[1], args[0]);
Ok(Value::Number(args[1].as_number().unwrap_or(0.0)))
});
// Create facts
let facts = Facts::new();
let mut customer = HashMap::new();
customer.insert("TotalSpent".to_string(), Value::Number(1250.0));
customer.insert("OrderCount".to_string(), Value::Integer(12));
customer.insert("Email".to_string(), Value::String("john@example.com".to_string()));
customer.insert("Id".to_string(), Value::String("CUST001".to_string()));
facts.add_value("Customer", Value::Object(customer))?;
// Execute rules
let result = engine.execute(&facts)?;
println!("Rules fired: {}", result.rules_fired);
Ok(())
}
```
### 🔍 Dependency Analysis Example
```rust
use rust_rule_engine::dependency::DependencyAnalyzer;
fn analyze_rule_dependencies() -> Result<(), Box<dyn std::error::Error>> {
let grl_content = r#"
rule "VIPUpgrade" {
when Customer.TotalSpent > 1000.0 && Customer.IsVIP == false
then
Customer.setIsVIP(true);
Customer.setTier("GOLD");
}
rule "VIPBenefits" {
when Customer.IsVIP == true
then
Order.setDiscountRate(0.15);
log("VIP discount applied");
}
"#;
let analyzer = DependencyAnalyzer::new();
let analysis = analyzer.analyze_grl_rules(grl_content)?;
// Show detected dependencies
for rule in &analysis.rules {
println!("📋 Rule '{}' reads: {:?}", rule.name, rule.reads);
println!("✏️ Rule '{}' writes: {:?}", rule.name, rule.writes);
}
// Check for conflicts
let conflicts = analysis.find_conflicts();
if conflicts.is_empty() {
println!("✅ No conflicts detected - rules can execute safely in parallel");
} else {
println!("⚠️ {} conflicts detected", conflicts.len());
}
Ok(())
}
```
## 🎯 GRL Rule Language Features
### Supported Syntax
```grl
rule "RuleName" salience 10 {
when
Object.Property > 100 &&
Object.Status == "ACTIVE"
then
Object.setCategory("HIGH_VALUE");
processTransaction(Object.Id, Object.Amount);
log("Rule executed successfully");
}
```
### Operators
- **Comparison**: `>`, `>=`, `<`, `<=`, `==`, `!=`
- **Logical**: `&&`, `||`
- **Value Types**: Numbers, Strings (quoted), Booleans (`true`/`false`)
### Actions
- **Method Calls**: `Object.method(args)`
- **Function Calls**: `functionName(args)`
- **Logging**: `log("message")`
## 📚 Examples
### 🛒 E-commerce Rules
```grl
rule "VIPCustomer" salience 20 {
when
Customer.TotalSpent > 5000.0 && Customer.YearsActive >= 2
then
Customer.setTier("VIP");
sendWelcomePackage(Customer.Email, "VIP");
applyDiscount(Customer.Id, 15.0);
log("Customer upgraded to VIP");
}
rule "LoyaltyReward" salience 15 {
when
Customer.OrderCount >= 50
then
addLoyaltyPoints(Customer.Id, 500);
log("Loyalty reward applied");
}
```
### 🚗 Vehicle Monitoring
```grl
rule "SpeedLimit" salience 25 {
when
Vehicle.Speed > Vehicle.SpeedLimit
then
triggerAlert(Vehicle.Id, "SPEED_VIOLATION");
logViolation(Vehicle.Driver, Vehicle.Speed);
Vehicle.setStatus("FLAGGED");
}
rule "MaintenanceDue" salience 10 {
when
Vehicle.Mileage > Vehicle.NextMaintenance
then
scheduleService(Vehicle.Id, Vehicle.Mileage);
notifyDriver(Vehicle.Driver, "Maintenance due");
}
```
## 🌐 REST API with Monitoring
The engine provides a production-ready REST API with comprehensive analytics monitoring.
### Quick Start
```bash
# Run the REST API server with full analytics monitoring
cargo run --example rest_api_monitoring
# Or use the demo script for testing
./demo_rest_api.sh
```
### Available Endpoints
**Rule Execution:**
- `POST /api/v1/rules/execute` - Execute rules with provided facts
- `POST /api/v1/rules/batch` - Execute rules in batch mode
**Analytics & Monitoring:**
- `GET /api/v1/analytics/dashboard` - Comprehensive analytics dashboard
- `GET /api/v1/analytics/stats` - Overall performance statistics
- `GET /api/v1/analytics/recent` - Recent execution activity
- `GET /api/v1/analytics/recommendations` - Performance optimization recommendations
- `GET /api/v1/analytics/rules/{rule_name}` - Rule-specific analytics
**System:**
- `GET /` - API documentation
- `GET /api/v1/health` - Health check
- `GET /api/v1/status` - System status
### Example Requests
**Execute Rules:**
```bash
curl -X POST "http://localhost:3000/api/v1/rules/execute" \
-H "Content-Type: application/json" \
-d '{
"facts": {
"Customer": {
"Age": 35,
"IsNew": false,
"OrderCount": 75,
"TotalSpent": 15000.0,
"YearsActive": 3,
"Email": "customer@example.com"
},
"Order": {
"Amount": 750.0,
"CustomerEmail": "customer@example.com"
}
}
}'
```
**Analytics Dashboard:**
```bash
curl "http://localhost:3000/api/v1/analytics/dashboard"
```
**Sample Response:**
```json
{
"overall_stats": {
"total_executions": 1250,
"avg_execution_time_ms": 2.3,
"success_rate": 99.8,
"rules_per_second": 435.2,
"uptime_hours": 24.5
},
"top_performing_rules": [
{
"name": "VIPCustomerRule",
"execution_count": 340,
"avg_duration_ms": 1.8,
"success_rate": 100.0
}
],
"recommendations": [
"Consider caching customer data to improve performance",
"Rule 'ComplexValidation' shows high execution time"
]
}
```
### Production Configuration
The REST API includes:
- **Real-time Analytics**: Live performance monitoring
- **Health Checks**: Comprehensive system health monitoring
- **CORS Support**: Cross-origin resource sharing
- **Error Handling**: Proper HTTP status codes and error messages
- **Sampling**: Configurable analytics sampling for high-volume scenarios
- **Memory Management**: Automatic cleanup and retention policies
## ⚡ Performance & Architecture
### Benchmarks
Performance benchmarks on a typical development machine:
```text
Simple Rule Execution:
• Single condition rule: ~4.5 µs per execution
• With custom function call: ~4.8 µs per execution
Complex Rule Execution:
• Multi-condition rules: ~2.7 µs per execution
• 3 rules with conditions: ~2.8 µs per execution
Rule Parsing:
• Simple GRL rule: ~1.1 µs per parse
• Medium complexity rule: ~1.4 µs per parse
• Complex multi-line rule: ~2.0 µs per parse
Facts Operations:
• Create complex facts: ~1.8 µs
• Get nested fact: ~79 ns
• Set nested fact: ~81 ns
Memory Usage:
• Base engine overhead: ~10KB
• Per rule storage: ~1-2KB
• Per fact storage: ~100-500 bytes
```
*Run benchmarks: `cargo bench`*
**Key Performance Insights:**
- **Ultra-fast execution**: Rules execute in microseconds
- **Efficient parsing**: GRL rules parse in under 2µs
- **Optimized facts**: Nanosecond-level fact operations
- **Low memory footprint**: Minimal overhead per rule
- **Scales linearly**: Performance consistent across rule counts
### 🏆 **Performance Comparison**
Benchmark comparison with other rule engines:
```text
Language/Engine Rule Execution Memory Usage Startup Time
─────────────────────────────────────────────────────────────────────
Rust (this engine) 2-5µs 1-2KB/rule ~1ms
.NET Rules Engine 15-50µs 3-8KB/rule ~50-100ms
Go Rules Framework 10-30µs 2-5KB/rule ~10-20ms
Java Drools 50-200µs 5-15KB/rule ~200-500ms
Python rule-engine 500-2000µs 8-20KB/rule ~100-300ms
```
**Rust Advantages:**
- **10x faster** than .NET rule engines
- **5x faster** than Go-based rule frameworks
- **50x faster** than Java Drools
- **400x faster** than Python implementations
- **Zero GC pauses** (unlike .NET/Java/Go)
- **Minimal memory footprint**
- **Instant startup** time
**Why Rust Wins:**
- No garbage collection overhead
- Zero-cost abstractions
- Direct memory management
- LLVM optimizations
- No runtime reflection costs
### Key Design Decisions
- **GRL-Only**: Removed JSON support for cleaner, focused API
- **Dual Sources**: Support both file-based and inline rule definitions
- **Custom Functions**: Extensible function registry for business logic
- **Builder Pattern**: Fluent API for easy engine configuration
- **Type Safety**: Leverages Rust's type system for runtime safety
- **Zero-Copy**: Efficient string and memory management
## � Advanced Dependency Analysis (v0.3.0+)
The rule engine features sophisticated **AST-based dependency analysis** that automatically detects field dependencies and potential conflicts between rules.
### Smart Field Detection
```rust
use rust_rule_engine::{RuleEngineBuilder, dependency::DependencyAnalyzer};
// Automatic field dependency detection
let rules = r#"
rule "DiscountRule" {
when Customer.VIP == true && Order.Amount > 100.0
then
Order.setDiscount(0.2);
Customer.setPoints(Customer.Points + 50);
}
rule "ShippingRule" {
when Order.Amount > 50.0
then
Order.setFreeShipping(true);
log("Free shipping applied");
}
"#;
let analyzer = DependencyAnalyzer::new();
let analysis = analyzer.analyze_grl_rules(rules)?;
// Automatically detected dependencies:
// DiscountRule reads: [Customer.VIP, Order.Amount, Customer.Points]
// DiscountRule writes: [Order.Discount, Customer.Points]
// ShippingRule reads: [Order.Amount]
// ShippingRule writes: [Order.FreeShipping]
```
### Conflict Detection
```rust
// Detect read-write conflicts between rules
let conflicts = analysis.find_conflicts();
for conflict in conflicts {
println!("⚠️ Conflict: {} reads {} while {} writes {}",
conflict.reader_rule, conflict.field,
conflict.writer_rule, conflict.field
);
}
// Smart execution ordering based on dependencies
let execution_order = analysis.suggest_execution_order();
```
### Advanced Features
- **🎯 AST-Based Analysis**: Proper parsing instead of regex pattern matching
- **🔄 Recursive Conditions**: Handles nested condition groups (AND/OR/NOT)
- **🧠 Function Side-Effects**: Infers field modifications from function calls
- **⚡ Zero False Positives**: Accurate dependency detection
- **📊 Conflict Resolution**: Automatic rule ordering suggestions
- **🚀 Parallel Safety**: Enables safe concurrent rule execution
## �📋 API Reference
### Core Types
```rust
// Main engine builder
RuleEngineBuilder::new()
.with_rule_file("path/to/rules.grl")?
.with_inline_grl("rule content")?
.with_config(config)
.build()
// Value types
Value::Integer(42)
Value::Number(3.14)
Value::String("text".to_string())
Value::Boolean(true)
Value::Object(HashMap<String, Value>)
// Facts management
let facts = Facts::new();
facts.add_value("Object", value)?;
facts.get("Object")?;
// Execution results
result.rules_fired // Number of rules that executed
result.cycle_count // Number of execution cycles
result.execution_time // Duration of execution
```
### Function Registration
```rust
engine.register_function("functionName", |args, facts| {
// args: Vec<Value> - function arguments
// facts: &Facts - current facts state
// Return: Result<Value, RuleEngineError>
let param1 = &args[0];
let param2 = args[1].as_number().unwrap_or(0.0);
// Your custom business logic here
println!("Function called with: {:?}", args);
Ok(Value::String("Success".to_string()))
});
```
## ⚡ Parallel Rule Execution
The engine supports parallel execution for improved performance with large rule sets:
```rust
use rust_rule_engine::engine::parallel::{ParallelEngine, ParallelConfig};
// Create parallel engine with custom configuration
let config = ParallelConfig {
enabled: true,
max_threads: 4,
};
let mut engine = ParallelEngine::new(config);
// Add rules and facts
engine.add_rule(rule);
engine.insert_fact("User", user_data);
// Execute rules in parallel
let result = engine.execute_parallel(10).await;
println!("Rules fired: {}", result.total_rules_fired);
println!("Execution time: {:?}", result.execution_time);
println!("Parallel speedup: {:.2}x", result.parallel_speedup);
```
### Parallel Execution Examples
```bash
# Simple parallel demo
cargo run --example simple_parallel_demo
# Performance comparison
cargo run --example financial_stress_test
```
## 🌊 Streaming Rule Engine (v0.2.0+)
For real-time event processing, enable the `streaming` feature:
```
## 🌊 Streaming Rule Engine (v0.2.0+)
For real-time rule processing with streaming data:
```rust
use rust_rule_engine::streaming::*;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut engine = StreamRuleEngine::new();
// Add streaming rules
engine.add_rule(r#"
rule "HighVolumeAlert" {
when
WindowEventCount > 100 && volumeSum > 1000000
then
AlertService.trigger("High volume detected");
}
"#).await?;
// Register action handlers
engine.register_action_handler("AlertService", |action| {
println!("🚨 Alert: {:?}", action.parameters);
}).await;
// Start processing
engine.start().await?;
// Send events
let event = StreamEvent::new("TradeEvent", data, "exchange");
engine.send_event(event).await?;
Ok(())
}
```
**Streaming Features:**
- **⏰ Time Windows**: Sliding/tumbling window aggregations
- **📊 Real-time Analytics**: Count, sum, average, min/max over windows
- **🎯 Pattern Matching**: Event correlation and filtering
- **⚡ High Throughput**: Async processing with backpressure handling
- **🚨 Action Handlers**: Custom callbacks for rule consequences
### Real-World Integration Examples
#### 🔌 **Kafka Consumer**
```rust
use rdkafka::consumer::{Consumer, StreamConsumer};
async fn consume_from_kafka(engine: Arc<StreamRuleEngine>) {
let consumer: StreamConsumer = ClientConfig::new()
.set("group.id", "trading-group")
.set("bootstrap.servers", "localhost:9092")
.create().unwrap();
consumer.subscribe(&["trading-events"]).unwrap();
loop {
match consumer.recv().await {
Ok(message) => {
let event = parse_kafka_message(message);
engine.send_event(event).await?;
}
Err(e) => eprintln!("Kafka error: {}", e),
}
}
}
```
#### 🌐 **WebSocket Stream**
```rust
use tokio_tungstenite::{connect_async, tungstenite::Message};
async fn consume_from_websocket(engine: Arc<StreamRuleEngine>) {
let (ws_stream, _) = connect_async("wss://api.exchange.com/stream").await?;
let (_, mut read) = ws_stream.split();
while let Some(msg) = read.next().await {
match msg? {
Message::Text(text) => {
let trade_data: TradeData = serde_json::from_str(&text)?;
let event = convert_to_stream_event(trade_data);
engine.send_event(event).await?;
}
_ => {}
}
}
}
```
#### 🔄 **HTTP API Polling**
```rust
async fn poll_trading_api(engine: Arc<StreamRuleEngine>) {
let client = reqwest::Client::new();
let mut interval = interval(Duration::from_secs(1));
loop {
interval.tick().await;
match client.get("https://api.exchange.com/trades").send().await {
Ok(response) => {
let trades: Vec<Trade> = response.json().await?;
for trade in trades {
let event = StreamEvent::new(
"TradeEvent",
trade.to_hashmap(),
"exchange_api"
);
engine.send_event(event).await?;
}
}
Err(e) => eprintln!("API error: {}", e),
}
}
}
```
#### 🗄️ **Database Change Streams**
```rust
async fn watch_database_changes(engine: Arc<StreamRuleEngine>) {
let mut change_stream = db.collection("trades")
.watch(None, None).await?;
while let Some(change) = change_stream.next().await {
let change_doc = change?;
if let Some(full_document) = change_doc.full_document {
let event = StreamEvent::new(
"DatabaseChange",
document_to_hashmap(full_document),
"mongodb"
);
engine.send_event(event).await?;
}
}
}
```
#### 📂 **File Watching**
```rust
use notify::{Watcher, RecursiveMode, watcher};
async fn watch_log_files(engine: Arc<StreamRuleEngine>) {
let (tx, mut rx) = tokio::sync::mpsc::channel(100);
let mut watcher = watcher(move |res| {
// Parse log lines into StreamEvents
}, Duration::from_secs(1))?;
watcher.watch("/var/log/trading", RecursiveMode::Recursive)?;
while let Some(file_event) = rx.recv().await {
let stream_event = parse_log_event(file_event);
engine.send_event(stream_event).await?;
}
}
```
### Use Case Examples
#### 📈 **Financial Trading**
```rust
rule "CircuitBreaker" {
when
priceMax > 200.0 || priceMin < 50.0
then
MarketService.halt("extreme_movement");
}
```
#### 🌡️ **IoT Monitoring**
```rust
rule "OverheatingAlert" {
when
temperatureAverage > 80.0 && WindowEventCount > 20
then
CoolingSystem.activate();
AlertService.notify("overheating_detected");
}
```
#### 🛡️ **Fraud Detection**
```rust
rule "SuspiciousActivity" {
when
transactionCountSum > 10 && amountAverage > 1000.0
then
SecurityService.flag("potential_fraud");
AccountService.freeze();
}
```
#### 📊 **E-commerce Analytics**
```rust
rule "FlashSaleOpportunity" {
when
viewCountSum > 1000 && conversionRateAverage < 0.02
then
PromotionService.trigger("flash_sale");
InventoryService.prepare();
}
```
See [docs/STREAMING.md](docs/STREAMING.md) for complete documentation and examples.
## 📊 Advanced Analytics & Performance Monitoring (v0.3.0+)
Get deep insights into your rule engine performance with built-in analytics and monitoring:
### 🔧 Quick Analytics Setup
```rust
use rust_rule_engine::{RustRuleEngine, AnalyticsConfig, RuleAnalytics};
// Configure analytics for production use
let analytics_config = AnalyticsConfig {
track_execution_time: true,
track_memory_usage: true,
track_success_rate: true,
sampling_rate: 0.8, // 80% sampling for high-volume production
retention_period: Duration::from_secs(30 * 24 * 60 * 60), // 30 days
max_recent_samples: 100,
};
// Enable analytics
let analytics = RuleAnalytics::new(analytics_config);
engine.enable_analytics(analytics);
// Execute rules - analytics automatically collected
let result = engine.execute(&facts)?;
// Access comprehensive insights
if let Some(analytics) = engine.analytics() {
let stats = analytics.overall_stats();
println!("Total executions: {}", stats.total_evaluations);
println!("Average execution time: {:.2}ms",
stats.avg_execution_time.as_secs_f64() * 1000.0);
println!("Success rate: {:.1}%", stats.success_rate);
// Get optimization recommendations
let recommendations = analytics.generate_recommendations();
for rec in recommendations {
println!("💡 {}", rec);
}
}
```
### 📈 Analytics Features
- **⏱️ Execution Timing**: Microsecond-precision rule performance tracking
- **📊 Success Rate Monitoring**: Track fired vs evaluated rule ratios
- **💾 Memory Usage Estimation**: Optional memory footprint analysis
- **🎯 Performance Rankings**: Identify fastest and slowest rules
- **🔮 Smart Recommendations**: AI-powered optimization suggestions
- **📅 Timeline Analysis**: Recent execution history and trends
- **⚙️ Production Sampling**: Configurable sampling rates for high-volume environments
- **🗂️ Automatic Cleanup**: Configurable data retention policies
### 🎛️ Production Configuration
```rust
// Production configuration with optimized settings
let production_config = AnalyticsConfig::production(); // Built-in production preset
// Or custom configuration
let custom_config = AnalyticsConfig {
track_execution_time: true,
track_memory_usage: false, // Disable for performance
track_success_rate: true,
sampling_rate: 0.1, // 10% sampling for high traffic
retention_period: Duration::from_secs(7 * 24 * 60 * 60), // 1 week
max_recent_samples: 50, // Limit memory usage
};
```
### 📊 Rich Analytics Dashboard
```rust
// Get comprehensive performance report
let analytics = engine.analytics().unwrap();
// Overall statistics
let stats = analytics.overall_stats();
println!("📊 Performance Summary:");
println!(" Rules: {}", stats.total_rules);
println!(" Executions: {}", stats.total_evaluations);
println!(" Success Rate: {:.1}%", stats.success_rate);
println!(" Avg Time: {:.2}ms", stats.avg_execution_time.as_secs_f64() * 1000.0);
// Top performing rules
for rule_metrics in analytics.slowest_rules(3) {
println!("⚠️ Slow Rule: {} ({:.2}ms avg)",
rule_metrics.rule_name,
rule_metrics.avg_execution_time().as_secs_f64() * 1000.0
);
}
// Recent activity timeline
for event in analytics.get_recent_events(5) {
let status = if event.success { "✅" } else { "❌" };
println!("{} {} - {:.2}ms", status, event.rule_name,
event.duration.as_secs_f64() * 1000.0);
}
```
### 🔍 Performance Insights
The analytics system provides actionable insights:
- **Slow Rule Detection**: "Consider optimizing 'ComplexValidation' - average execution time is 15.3ms"
- **Low Success Rate Alerts**: "Rule 'RareCondition' has low success rate (12.5%) - review conditions"
- **Dead Rule Detection**: "Rule 'ObsoleteCheck' never fires despite 156 evaluations - review logic"
- **Memory Usage Warnings**: "Rule 'DataProcessor' uses significant memory - consider optimization"
### 📚 Analytics Examples
Check out the comprehensive analytics demo:
```bash
# Run the analytics demonstration
cargo run --example analytics_demo
# Output includes:
# - Configuration summary
# - Performance rankings
# - Success rate analysis
# - Optimization recommendations
# - Recent execution timeline
```
**Key Benefits:**
- 🚀 **Performance Optimization**: Identify bottlenecks automatically
- 📈 **Production Monitoring**: Real-time insights in live environments
- 🔧 **Development Debugging**: Detailed execution analysis during development
- 📊 **Trend Analysis**: Historical performance tracking and regression detection
- ⚡ **Zero-Overhead Option**: Configurable sampling with minimal performance impact
## � Changelog
### v0.3.0 (October 2025) - AST-Based Dependency Analysis & Advanced Analytics
- **🔍 Revolutionary Dependency Analysis**: Complete rewrite from hard-coded pattern matching to proper AST parsing
- **🎯 Smart Field Detection**: Recursive condition tree traversal for accurate field dependency extraction
- **🧠 Function Side-Effect Analysis**: Intelligent inference of field modifications from function calls
- **⚡ Zero False Positives**: Elimination of brittle string-based detection methods
- **🚀 Parallel Processing Foundation**: AST-based analysis enables safe concurrent rule execution
- **📊 Advanced Conflict Detection**: Real data flow analysis for read-write conflict identification
- **🏗️ Production-Ready Safety**: Robust dependency analysis for enterprise-grade rule management
- **📈 Advanced Analytics System**: Comprehensive performance monitoring and optimization insights
- Real-time execution metrics with microsecond precision
- Success rate tracking and trend analysis
- Memory usage estimation and optimization recommendations
- Production-ready sampling and data retention policies
- Automated performance optimization suggestions
- Rich analytics dashboard with timeline analysis
- **🌐 REST API with Monitoring**: Production-ready web API with full analytics integration
- Comprehensive REST endpoints for rule execution
- Real-time analytics dashboard with performance insights
- Health monitoring and system status endpoints
- CORS support and proper error handling
- Sample requests and complete API documentation
### v0.2.x - Core Features & Streaming
- **🌊 Stream Processing**: Real-time event processing with time windows
- **📊 Rule Templates**: Parameterized rule generation system
- **🔧 Method Calls**: Enhanced object method call support
- **📄 File-Based Rules**: External `.grl` file support
- **⚡ Performance Optimizations**: Microsecond-level rule execution
## �📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 📞 Support
- 📚 **Documentation**: [docs.rs/rust-rule-engine](https://docs.rs/rust-rule-engine)
- 🐛 **Issues**: [GitHub Issues](https://github.com/KSD-CO/rust-rule-engine/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/KSD-CO/rust-rule-engine/discussions)
---
**Built with ❤️ in Rust** 🦀