smart_message 0.0.7 → 0.0.9

data/examples/11_global_configuration_example.rb

@@ -0,0 +1,219 @@
+#!/usr/bin/env ruby
+# examples/11_global_configuration_example.rb
+#
+# Global Configuration System Example
+#
+# This example demonstrates how to use SmartMessage's global configuration
+# system to set default logger, transport, and serializer for all message
+# classes in your application.
+
+require_relative '../lib/smart_message'
+
+puts "=== SmartMessage Global Configuration Example ==="
+puts
+
+# Example 1: Default behavior (no configuration) - NO LOGGING
+puts "1. Default Framework Behavior (NO LOGGING):"
+puts "   Default Logger: #{SmartMessage::Logger.default.class}"
+puts "   Default Transport: #{SmartMessage::Transport.default.class}" 
+puts "   Default Serializer: #{SmartMessage::Serializer.default.class}"
+puts "   Note: No logging unless explicitly configured!"
+puts
+
+# Example 2: Configure logging with string path
+puts "2. Configuring Logging with String Path:"
+SmartMessage.configure do |config|
+  config.logger = "log/my_application.log"  # String = Lumberjack logger with this path
+  config.transport = SmartMessage::Transport::StdoutTransport.new(loopback: true)
+  config.serializer = SmartMessage::Serializer::Json.new
+end
+
+puts "   Configured Logger: #{SmartMessage::Logger.default.class}"
+puts "   Log File: #{SmartMessage::Logger.default.log_file rescue 'N/A'}"
+puts "   Configured Transport: #{SmartMessage::Transport.default.class}"
+puts "   Configured Serializer: #{SmartMessage::Serializer.default.class}"
+puts
+
+# Reset for next example
+SmartMessage.reset_configuration!
+
+# Example 3: Configure with :default symbol (framework defaults)
+puts "3. Configuring with :default Symbol:"
+SmartMessage.configure do |config|
+  config.logger = :default  # Use Lumberjack with default settings
+  config.transport = SmartMessage::Transport::StdoutTransport.new(loopback: true)
+  config.serializer = SmartMessage::Serializer::Json.new
+end
+
+puts "   Configured Logger: #{SmartMessage::Logger.default.class}"
+puts "   Log File: #{SmartMessage::Logger.default.log_file rescue 'N/A'}"
+puts "   Configured Transport: #{SmartMessage::Transport.default.class}"
+puts "   Configured Serializer: #{SmartMessage::Serializer.default.class}"
+puts
+
+# Example 4: Message classes automatically use global configuration
+puts "4. Message Classes Using Global Configuration:"
+
+class NotificationMessage < SmartMessage::Base
+  property :recipient
+  property :message
+  property :priority, default: 'normal'
+  
+  # No config block needed - automatically uses global configuration!
+  
+  def self.process(wrapper)
+    message_header, message_payload = wrapper.split
+    data = JSON.parse(message_payload)
+    
+    priority_emoji = case data['priority']
+                     when 'high' then '🔴'
+                     when 'medium' then '🟡'
+                     else '🟢'
+                     end
+    
+    puts "#{priority_emoji} Notification: #{data['message']} (to: #{data['recipient']})"
+  end
+end
+
+class OrderStatusMessage < SmartMessage::Base
+  property :order_id
+  property :status
+  property :customer_id
+  
+  # Also uses global configuration automatically
+  
+  def self.process(wrapper)
+    message_header, message_payload = wrapper.split
+    data = JSON.parse(message_payload)
+    
+    status_emoji = case data['status']
+                   when 'confirmed' then '✅'
+                   when 'shipped' then '📦'
+                   when 'delivered' then '🎉'
+                   when 'cancelled' then '❌'
+                   else '⏳'
+                   end
+    
+    puts "#{status_emoji} Order #{data['order_id']}: #{data['status']}"
+  end
+end
+
+# Subscribe to messages to see them in action
+NotificationMessage.subscribe
+OrderStatusMessage.subscribe
+
+puts "   Message classes configured automatically!"
+puts
+
+# Example 4: Creating and publishing messages
+puts "4. Publishing Messages (using global configuration):"
+
+notification = NotificationMessage.new(
+  recipient: "admin@example.com",
+  message: "System maintenance scheduled for tonight",
+  priority: "high",
+  from: "SystemService"
+)
+
+order_status = OrderStatusMessage.new(
+  order_id: "ORD-12345",
+  status: "shipped",
+  customer_id: "CUST-001",
+  from: "OrderService"
+)
+
+puts "\n--- Publishing Messages ---"
+notification.publish
+order_status.publish
+
+# Give time for async processing
+sleep(0.5)
+
+puts
+
+# Example 5: Individual classes can still override global configuration
+puts "5. Overriding Global Configuration for Specific Classes:"
+
+class SpecialMessage < SmartMessage::Base
+  property :content
+  
+  # Override just the logger, keep global transport and serializer
+  config do
+    logger SmartMessage::Logger::Default.new(log_file: STDERR, level: Logger::WARN)
+    # transport and serializer still use global configuration
+  end
+  
+  def self.process(wrapper)
+    message_header, message_payload = wrapper.split
+    data = JSON.parse(message_payload)
+    puts "⭐ Special processing: #{data['content']}"
+  end
+end
+
+SpecialMessage.subscribe
+
+special = SpecialMessage.new(
+  content: "This uses custom logger but global transport/serializer",
+  from: "SpecialService"
+)
+
+puts "   SpecialMessage logger: #{SpecialMessage.logger.class}"
+puts "   (Should be SmartMessage::Logger::Default with STDERR output)"
+
+special.publish
+sleep(0.5)
+
+puts
+
+# Example 6: Resetting configuration
+puts "6. Resetting to Framework Defaults:"
+SmartMessage.reset_configuration!
+
+puts "   After reset:"
+puts "   Logger: #{SmartMessage::Logger.default.class}"
+puts "   Transport: #{SmartMessage::Transport.default.class}"
+puts "   Serializer: #{SmartMessage::Serializer.default.class}"
+
+puts "\n✨ Global Configuration Example Complete!"
+puts
+puts "Key Benefits:"
+puts "• Set defaults once for entire application"
+puts "• All message classes inherit global configuration automatically"
+puts "• Individual classes can still override when needed"
+puts "• Clean, centralized configuration management"
+puts "• No need for repetitive config blocks in every message class"
+puts "• Easy integration with Rails.logger or any other logger"
+puts
+puts "Configuration Options Summary:"
+puts "  # No configuration = NO LOGGING (new default behavior)"
+puts "  # No SmartMessage.configure block needed"
+puts
+puts "  # String path = Lumberjack logger with that file"
+puts "  SmartMessage.configure do |config|"
+puts "    config.logger = 'log/my_app.log'    # String path"
+puts "  end"
+puts
+puts "  # STDOUT/STDERR = Lumberjack logger to console"
+puts "  SmartMessage.configure do |config|"
+puts "    config.logger = STDOUT              # Log to STDOUT"
+puts "    config.logger = STDERR              # Log to STDERR"
+puts "  end"
+puts
+puts "  # :default symbol = Lumberjack with framework defaults" 
+puts "  SmartMessage.configure do |config|"
+puts "    config.logger = :default            # Framework default (file)"
+puts "  end"
+puts
+puts "  # Custom logger object = Use that logger"
+puts "  SmartMessage.configure do |config|"
+puts "    config.logger = Rails.logger        # Rails logger"
+puts "    config.logger = MyApp::Logger.new   # Custom logger"
+puts "  end"
+puts
+puts "  # Explicit nil = No logging (same as no configuration)"
+puts "  SmartMessage.configure do |config|"
+puts "    config.logger = nil                 # Explicit no logging"
+puts "  end"
+
+# Clean up test file
+File.delete('test_config.rb') if File.exist?('test_config.rb')

data/examples/README.md

@@ -16,6 +16,10 @@ ruby 05_proc_handlers.rb
 ruby 06_custom_logger_example.rb
 ruby 07_error_handling_scenarios.rb
 ruby 08_entity_addressing.rb
+ruby 09_regex_filtering_microservices.rb
+ruby 10_header_block_configuration.rb
+ruby 11_global_configuration_example.rb
+ruby show_logger.rb
 ```
 
 ## Examples Overview
@@ -266,6 +270,73 @@ payment.publish
 - **Runtime Configuration**: Dynamic addressing based on conditions
 - **Integration Patterns**: Gateway support for external systems
 
+---
+
+### 10. Header Block Configuration (Addressing DSL)
+**File:** `10_header_block_configuration.rb`
+
+**Scenario:** Comprehensive demonstration of SmartMessage's flexible header configuration options, showing three different methods for setting addressing fields.
+
+**Key Features:**
+- Direct class methods for addressing configuration
+- Header block DSL for clean, grouped configuration
+- Mixed approach combining both methods
+- Instance-level addressing overrides with method chaining
+- Setter syntax for addressing fields
+- Automatic header synchronization with instance values
+- Configuration checking and validation methods
+
+**Configuration Methods Demonstrated:**
+```ruby
+# Method 1: Direct class methods
+class DirectMethodMessage < SmartMessage::Base
+  from 'service-a'
+  to 'service-b'
+  reply_to 'service-a-callback'
+end
+
+# Method 2: Header block DSL
+class HeaderBlockMessage < SmartMessage::Base
+  header do
+    from 'service-x'
+    to 'service-y'
+    reply_to 'service-x-callback'
+  end
+end
+
+# Method 3: Mixed approach
+class MixedConfigMessage < SmartMessage::Base
+  header do
+    from 'mixed-service'
+    to 'target-service'
+  end
+  reply_to 'mixed-callback'  # Outside block
+end
+```
+
+**Instance-Level Features:**
+- **Method Chaining**: `msg.from('sender').to('recipient').reply_to('callback')`
+- **Setter Syntax**: `msg.from = 'sender'`, `msg.to = 'recipient'`
+- **Shortcut Accessors**: `msg.from`, `msg.to`, `msg.reply_to`
+- **Header Access**: `msg._sm_header.from`, `msg._sm_header.to`
+- **Configuration Checks**: `msg.from_configured?`, `msg.to_missing?`
+- **Reset Methods**: `msg.reset_from`, `msg.reset_to`, `msg.reset_reply_to`
+
+**What You'll Learn:**
+- How to choose the best configuration method for your use case
+- Benefits of header block DSL for grouped configuration
+- Dynamic addressing overrides at runtime
+- Three ways to access addressing values
+- How headers automatically sync with instance changes
+- Configuration validation and checking methods
+
+**Benefits:**
+- **Clean Syntax**: Header block groups related configuration
+- **Flexibility**: Multiple configuration approaches to suit different styles
+- **Runtime Control**: Instance-level overrides for dynamic routing
+- **Consistency**: Headers stay synchronized with instance values
+- **Validation**: Built-in methods to check configuration state
+
 ## Message Patterns Demonstrated
 
 ### Request-Response Pattern
@@ -471,6 +542,37 @@ class MyCustomTransport < SmartMessage::Transport::Base
 end
 ```
 
+---
+
+### Show Logger Demonstration
+**File:** `show_logger.rb`
+
+**Scenario:** Comprehensive demonstration of SmartMessage's enhanced logging capabilities, showing how applications can use the SmartMessage logger directly and configure various Lumberjack options.
+
+**Key Features:**
+- Colorized console output for different log levels
+- JSON and text log formatting
+- File-based logging with rolling (size and date-based)
+- Application logger patterns and direct logger usage
+- Multiple logger configurations
+- Integration with SmartMessage classes
+
+**What You'll Learn:**
+- How to configure SmartMessage's global logger settings
+- Different log output formats (text vs JSON)
+- Colorized logging for console output
+- File rolling strategies for production use
+- How to use the SmartMessage logger directly in applications
+- Best practices for structured logging
+- Integration patterns between application code and SmartMessage classes
+
+**Demonstrates:**
+- `SmartMessage.configure` block usage for logger configuration
+- `log_level`, `log_format`, `log_colorize`, and `log_options` settings
+- Direct access to `SmartMessage.configuration.default_logger`
+- Creating multiple logger instances with different configurations
+- Practical application patterns using the logger
+
 ## Production Considerations
 
 When adapting these examples for production:

data/examples/dead_letters.jsonl

@@ -0,0 +1,12 @@
+{"timestamp":"2025-08-19T16:03:52-05:00","header":{"uuid":"ecb4c4f9-e9a7-47fd-918a-8dc5087218d6","message_class":"OrderMessage","published_at":"2025-08-19T16:03:52.374-05:00","publisher_pid":16266,"version":1,"from":"OrderService","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"order_id\":\"ORD-1001\",\"customer_id\":\"CUST-001\",\"amount\":99.99,\"currency\":\"USD\",\"payment_method\":\"credit_card\",\"items\":[\"Widget A\",\"Widget B\"]}","payload_format":"json","error":"wrong number of arguments (given 1, expected 2)","retry_count":0,"transport":"circuit_breaker","stack_trace":null}
+{"timestamp":"2025-08-19T16:03:52-05:00","header":{"uuid":"40dce8a2-1723-48f5-ad01-fe49814991a2","message_class":"OrderMessage","published_at":"2025-08-19T16:03:52.889-05:00","publisher_pid":16266,"version":1,"from":"OrderService","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"order_id\":\"ORD-1002\",\"customer_id\":\"CUST-002\",\"amount\":1299.99,\"currency\":\"USD\",\"payment_method\":\"debit_card\",\"items\":[\"Premium Widget\",\"Extended Warranty\"]}","payload_format":"json","error":"wrong number of arguments (given 1, expected 2)","retry_count":0,"transport":"circuit_breaker","stack_trace":null}
+{"timestamp":"2025-08-19T16:03:53-05:00","header":{"uuid":"0e1a228b-4069-4c05-b1ed-18193174d773","message_class":"OrderMessage","published_at":"2025-08-19T16:03:53.397-05:00","publisher_pid":16266,"version":1,"from":"OrderService","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"order_id\":\"ORD-1003\",\"customer_id\":\"CUST-003\",\"amount\":45.5,\"currency\":\"USD\",\"payment_method\":\"paypal\",\"items\":[\"Small Widget\"]}","payload_format":"json","error":"wrong number of arguments (given 1, expected 2)","retry_count":0,"transport":"circuit_breaker","stack_trace":null}
+{"timestamp":"2025-08-19T16:04:01-05:00","header":{"uuid":"60ca2ca3-8185-4946-ae20-85269073ce3e","message_class":"UserEventMessage","published_at":"2025-08-19T16:04:01.582-05:00","publisher_pid":16396,"version":1,"from":"UserManager","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"event_id\":\"EVT-1001\",\"event_type\":\"user_registered\",\"user_id\":\"USER-101\",\"user_email\":\"alice@example.com\",\"user_name\":\"Alice Johnson\",\"timestamp\":\"2025-08-19T16:04:01-05:00\",\"metadata\":{\"source\":\"web_registration\"}}","payload_format":"json","error":"wrong number of arguments (given 1, expected 2)","retry_count":0,"transport":"circuit_breaker","stack_trace":null}
+{"timestamp":"2025-08-19T16:23:07-05:00","header":{"uuid":"ebd1f61b-e5d9-48f4-a787-e1f9f4e09578","message_class":"SystemNotificationMessage","published_at":"2025-08-19T16:23:07.222-05:00","publisher_pid":24163,"version":1,"from":"user-001","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"notification_id\":\"NOTIF-1755638587-564\",\"room_id\":\"general\",\"notification_type\":\"user_joined\",\"content\":\"Alice joined the room\",\"timestamp\":\"2025-08-19T16:23:07-05:00\",\"metadata\":{\"triggered_by\":\"user-001\"}}","payload_format":"json","error":"undefined method 'handle_system_notification_user-001' for class 'HumanChatAgent'","retry_count":0,"transport":"circuit_breaker","stack_trace":null}
+{"timestamp":"2025-08-19T16:25:50-05:00","header":{"uuid":"e722ef85-7168-42e2-94c2-cc55c1ca6784","message_class":"PaymentMessage","published_at":"2025-08-19T16:25:50.310-05:00","publisher_pid":25696,"version":1,"from":"payment-service","to":"dev-payment-processor","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"service_id\":\"payment-core\",\"message_type\":\"transaction_complete\",\"data\":{\"merchant\":\"Online Store\"},\"environment\":\"dev\",\"timestamp\":\"2025-08-19T16:25:50-05:00\",\"transaction_id\":\"TXN-001\",\"amount\":99.99,\"currency\":\"USD\"}","payload_format":"json","error":"undefined method 'process_dev' for class 'PaymentMessage'","retry_count":0,"transport":"circuit_breaker","stack_trace":null}
+{"timestamp":"2025-08-19T16:25:50-05:00","header":{"uuid":"d36c3c66-bccc-49af-b919-b62bc6c9e1b2","message_class":"PaymentMessage","published_at":"2025-08-19T16:25:50.831-05:00","publisher_pid":25696,"version":1,"from":"payment-service","to":"prod-payment-processor","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"service_id\":\"payment-core\",\"message_type\":\"transaction_complete\",\"data\":{\"merchant\":\"Enterprise Store\"},\"environment\":\"prod\",\"timestamp\":\"2025-08-19T16:25:50-05:00\",\"transaction_id\":\"TXN-002\",\"amount\":299.99,\"currency\":\"USD\"}","payload_format":"json","error":"undefined method 'process_prod' for class 'PaymentMessage'","retry_count":0,"transport":"circuit_breaker","stack_trace":null}
+{"timestamp":"2025-08-19T16:25:52-05:00","header":{"uuid":"d3371fb3-ed6e-403c-8f3b-3b130958a013","message_class":"AlertMessage","published_at":"2025-08-19T16:25:52.351-05:00","publisher_pid":25696,"version":1,"from":"admin","to":"security-dashboard","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"service_id\":\"security-scanner\",\"message_type\":\"security_alert\",\"data\":{\"attempts\":50,\"ip\":\"192.168.1.100\"},\"environment\":\"prod\",\"timestamp\":\"2025-08-19T16:25:52-05:00\",\"alert_level\":\"critical\",\"component\":\"authentication\",\"description\":\"Multiple failed login attempts detected\"}","payload_format":"json","error":"undefined method 'process_admin' for class 'AlertMessage'","retry_count":0,"transport":"circuit_breaker","stack_trace":null}
+{"timestamp":"2025-08-19T16:25:52-05:00","header":{"uuid":"46a5b557-540c-4d50-a1f9-030907ba6275","message_class":"AlertMessage","published_at":"2025-08-19T16:25:52.860-05:00","publisher_pid":25696,"version":1,"from":"system-metrics","to":"ops-dashboard","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"service_id\":\"system-monitor\",\"message_type\":\"resource_alert\",\"data\":{\"usage_percent\":85,\"threshold\":80},\"environment\":\"staging\",\"timestamp\":\"2025-08-19T16:25:52-05:00\",\"alert_level\":\"warning\",\"component\":\"memory\",\"description\":\"Memory usage above threshold\"}","payload_format":"json","error":"Circuit 'message_processor' is open","retry_count":0,"transport":"circuit_breaker","stack_trace":null}
+{"timestamp":"2025-08-19T16:25:52-05:00","header":{"uuid":"46a5b557-540c-4d50-a1f9-030907ba6275","message_class":"AlertMessage","published_at":"2025-08-19T16:25:52.860-05:00","publisher_pid":25696,"version":1,"from":"system-metrics","to":"ops-dashboard","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"service_id\":\"system-monitor\",\"message_type\":\"resource_alert\",\"data\":{\"usage_percent\":85,\"threshold\":80},\"environment\":\"staging\",\"timestamp\":\"2025-08-19T16:25:52-05:00\",\"alert_level\":\"warning\",\"component\":\"memory\",\"description\":\"Memory usage above threshold\"}","payload_format":"json","error":"Circuit 'message_processor' is open","retry_count":0,"transport":"circuit_breaker","stack_trace":null}
+{"timestamp":"2025-08-19T16:25:53-05:00","header":{"uuid":"8ebceac3-8c5d-4253-b2a2-ce754084c3c2","message_class":"OrderMessage","published_at":"2025-08-19T16:25:53.365-05:00","publisher_pid":25696,"version":1,"from":"admin-dashboard","to":"prod-fulfillment","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"service_id\":\"admin-portal\",\"message_type\":\"admin_order_override\",\"data\":{\"priority\":\"high\",\"reason\":\"VIP customer\"},\"environment\":\"prod\",\"timestamp\":\"2025-08-19T16:25:53-05:00\",\"order_id\":\"ORD-999\",\"customer_id\":\"ADMIN\",\"status\":\"expedited\"}","payload_format":"json","error":"Circuit 'message_processor' is open","retry_count":0,"transport":"circuit_breaker","stack_trace":null}
+{"timestamp":"2025-08-19T16:25:53-05:00","header":{"uuid":"8dfa4fed-f2df-4f66-81c2-963a97489a31","message_class":"PaymentMessage","published_at":"2025-08-19T16:25:53.873-05:00","publisher_pid":25696,"version":1,"from":"admin","serializer":"SmartMessage::Serializer::JSON"},"payload":"{\"service_id\":\"payment-system\",\"message_type\":\"system_maintenance\",\"data\":{\"message\":\"Scheduled maintenance in 30 minutes\",\"duration\":\"2 hours\",\"affected_services\":[\"payment\",\"billing\"]},\"environment\":\"prod\",\"timestamp\":\"2025-08-19T16:25:53-05:00\",\"transaction_id\":\"MAINT-001\",\"amount\":0,\"currency\":\"USD\"}","payload_format":"json","error":"Circuit 'message_processor' is open","retry_count":0,"transport":"circuit_breaker","stack_trace":null}

data/examples/performance_metrics/benchmark_results_ractor_20250818_205603.json

@@ -0,0 +1,135 @@
+{
+  "benchmark_info": {
+    "timestamp": "2025-08-18T20:56:03-05:00",
+    "implementation": "ractor",
+    "ruby_version": "3.4.5",
+    "platform": "arm64-darwin24",
+    "processor_count": 12
+  },
+  "overall_stats": {
+    "total_runtime": 4.173938,
+    "memory_used_mb": 21.046875
+  },
+  "scenario_results": {
+    "cpu_light": {
+      "name": "CPU Light",
+      "messages_generated": 1000,
+      "messages_published": 1000,
+      "messages_processed": 1000,
+      "errors": 0,
+      "times": {
+        "total": 0.360609,
+        "publish": 0.139781,
+        "processing": 0.103401
+      },
+      "throughput": {
+        "messages_per_second": 2773.0866395458793,
+        "publish_rate": 7154.048118127643
+      },
+      "dispatcher_stats": {
+        "pool_size": null,
+        "queue_length": 0,
+        "completed_task_count": 1000,
+        "scheduled_task_count": 1000,
+        "running": true,
+        "implementation": "ractor"
+      }
+    },
+    "cpu_heavy": {
+      "name": "CPU Heavy",
+      "messages_generated": 500,
+      "messages_published": 500,
+      "messages_processed": 500,
+      "errors": 0,
+      "times": {
+        "total": 1.701841,
+        "publish": 0.487508,
+        "processing": 1.1547
+      },
+      "throughput": {
+        "messages_per_second": 293.7994795048421,
+        "publish_rate": 1025.624194885007
+      },
+      "dispatcher_stats": {
+        "pool_size": null,
+        "queue_length": 0,
+        "completed_task_count": 1500,
+        "scheduled_task_count": 1500,
+        "running": true,
+        "implementation": "ractor"
+      }
+    },
+    "io_light": {
+      "name": "I/O Light",
+      "messages_generated": 800,
+      "messages_published": 800,
+      "messages_processed": 800,
+      "errors": 0,
+      "times": {
+        "total": 0.880671,
+        "publish": 0.068458,
+        "processing": 0.724868
+      },
+      "throughput": {
+        "messages_per_second": 908.3982554211505,
+        "publish_rate": 11685.997253790645
+      },
+      "dispatcher_stats": {
+        "pool_size": null,
+        "queue_length": 0,
+        "completed_task_count": 2300,
+        "scheduled_task_count": 2300,
+        "running": true,
+        "implementation": "ractor"
+      }
+    },
+    "io_heavy": {
+      "name": "I/O Heavy",
+      "messages_generated": 200,
+      "messages_published": 200,
+      "messages_processed": 200,
+      "errors": 0,
+      "times": {
+        "total": 0.249395,
+        "publish": 0.015782,
+        "processing": 0.205659
+      },
+      "throughput": {
+        "messages_per_second": 801.9406964854949,
+        "publish_rate": 12672.665061462425
+      },
+      "dispatcher_stats": {
+        "pool_size": null,
+        "queue_length": 0,
+        "completed_task_count": 2500,
+        "scheduled_task_count": 2500,
+        "running": true,
+        "implementation": "ractor"
+      }
+    },
+    "mixed": {
+      "name": "Mixed Load",
+      "messages_generated": 600,
+      "messages_published": 600,
+      "messages_processed": 600,
+      "errors": 0,
+      "times": {
+        "total": 0.969969,
+        "publish": 0.145701,
+        "processing": 0.747523
+      },
+      "throughput": {
+        "messages_per_second": 618.5764699696589,
+        "publish_rate": 4118.022525583215
+      },
+      "dispatcher_stats": {
+        "pool_size": null,
+        "queue_length": 0,
+        "completed_task_count": 3100,
+        "scheduled_task_count": 3100,
+        "running": true,
+        "implementation": "ractor"
+      }
+    }
+  }
+}

data/examples/performance_metrics/benchmark_results_ractor_20250818_205831.json

@@ -0,0 +1,135 @@
+{
+  "benchmark_info": {
+    "timestamp": "2025-08-18T20:58:31-05:00",
+    "implementation": "ractor",
+    "ruby_version": "3.4.5",
+    "platform": "arm64-darwin24",
+    "processor_count": 12
+  },
+  "overall_stats": {
+    "total_runtime": 4.174644,
+    "memory_used_mb": 23.53125
+  },
+  "scenario_results": {
+    "cpu_light": {
+      "name": "CPU Light",
+      "messages_generated": 1000,
+      "messages_published": 1000,
+      "messages_processed": 1000,
+      "errors": 0,
+      "times": {
+        "total": 0.353973,
+        "publish": 0.135409,
+        "processing": 0.106285
+      },
+      "throughput": {
+        "messages_per_second": 2825.0742288253628,
+        "publish_rate": 7385.033491126882
+      },
+      "dispatcher_stats": {
+        "pool_size": null,
+        "queue_length": 0,
+        "completed_task_count": 1000,
+        "scheduled_task_count": 1000,
+        "running": true,
+        "implementation": "ractor"
+      }
+    },
+    "cpu_heavy": {
+      "name": "CPU Heavy",
+      "messages_generated": 500,
+      "messages_published": 500,
+      "messages_processed": 500,
+      "errors": 0,
+      "times": {
+        "total": 1.76826,
+        "publish": 0.427835,
+        "processing": 1.265818
+      },
+      "throughput": {
+        "messages_per_second": 282.76384694558493,
+        "publish_rate": 1168.6748395993782
+      },
+      "dispatcher_stats": {
+        "pool_size": null,
+        "queue_length": 0,
+        "completed_task_count": 1500,
+        "scheduled_task_count": 1500,
+        "running": true,
+        "implementation": "ractor"
+      }
+    },
+    "io_light": {
+      "name": "I/O Light",
+      "messages_generated": 800,
+      "messages_published": 800,
+      "messages_processed": 800,
+      "errors": 0,
+      "times": {
+        "total": 0.893786,
+        "publish": 0.065332,
+        "processing": 0.731431
+      },
+      "throughput": {
+        "messages_per_second": 895.068841982309,
+        "publish_rate": 12245.14786016041
+      },
+      "dispatcher_stats": {
+        "pool_size": null,
+        "queue_length": 0,
+        "completed_task_count": 2300,
+        "scheduled_task_count": 2300,
+        "running": true,
+        "implementation": "ractor"
+      }
+    },
+    "io_heavy": {
+      "name": "I/O Heavy",
+      "messages_generated": 200,
+      "messages_published": 200,
+      "messages_processed": 200,
+      "errors": 0,
+      "times": {
+        "total": 0.274932,
+        "publish": 0.017833,
+        "processing": 0.210557
+      },
+      "throughput": {
+        "messages_per_second": 727.4526064626889,
+        "publish_rate": 11215.162900241125
+      },
+      "dispatcher_stats": {
+        "pool_size": null,
+        "queue_length": 0,
+        "completed_task_count": 2500,
+        "scheduled_task_count": 2500,
+        "running": true,
+        "implementation": "ractor"
+      }
+    },
+    "mixed": {
+      "name": "Mixed Load",
+      "messages_generated": 600,
+      "messages_published": 600,
+      "messages_processed": 600,
+      "errors": 0,
+      "times": {
+        "total": 0.870865,
+        "publish": 0.145127,
+        "processing": 0.625774
+      },
+      "throughput": {
+        "messages_per_second": 688.9701618505738,
+        "publish_rate": 4134.309949216893
+      },
+      "dispatcher_stats": {
+        "pool_size": null,
+        "queue_length": 0,
+        "completed_task_count": 3100,
+        "scheduled_task_count": 3100,
+        "running": true,
+        "implementation": "ractor"
+      }
+    }
+  }
+}