smart_message 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a7c214ec62b411d8f3bbf0925d6547fa135233684ac22483e028ffc76cc6cbe
-  data.tar.gz: f80ce67e2ea59172a36a8c7b675864c93573bf1f2b94e294124bdf2bbb28ae73
+  metadata.gz: de5fce8e9cb793850301df5fdb9ad8a6954cf3a481cadc2deb625c373706723a
+  data.tar.gz: 0cc8067011377f0d574bc7f9bf1168ac2176fad7c7981cbd43f708e622a98fa0
 SHA512:
-  metadata.gz: da70af3b299ef64e94d8cefd87b3bb25b0a50dd3b835d4765a6f26231c65d0fa69b2ccf3d204d8de666aca2e241dcb37e396dcd064aaeae895881885e8c1ea21
-  data.tar.gz: fd2da658b323102bcb93e73f9b5d0ae843bd6afc7a8f031be7ebc206d89231f3304092d83de79524d7fd337f09a0bafad7b7bfc782e9f7a9820d32568c65e252
+  metadata.gz: bf7d1fc90d41bdbd3a8661f1f3e294915d29f267a68c13869926a4f829a00338f3878b03e14f26a7ccc9b248dc55b566e9988cb67aca7f6de596b94a51b5e885
+  data.tar.gz: 51c784d4183fe12862ff9250389a57233718604442e50303cdb941265971978e291fe7c3c1fec92509e6fa32bcc67b6b2fe8813b3cc1d06fa9d1f16645b181f3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smart_message (0.0.3)
+    smart_message (0.0.4)
       activesupport
       concurrent-ruby
       hashie

data/docs/README.md

@@ -18,6 +18,7 @@ Welcome to the comprehensive documentation for SmartMessage, a Ruby gem that abs
 - [Property System](properties.md)
 - [Transport Layer](transports.md)
 - [Serializers](serializers.md)
+- [Logging System](logging.md)
 - [Dispatcher & Routing](dispatcher.md)
 - [Message Headers](headers.md)
 

data/docs/logging.md

@@ -0,0 +1,452 @@
+# Logging in SmartMessage
+
+SmartMessage provides flexible logging capabilities through its plugin architecture. This document covers the built-in default logger as well as how to create custom loggers.
+
+## Table of Contents
+
+- [Default Logger](#default-logger)
+- [Configuration Options](#configuration-options)
+- [Output Destinations](#output-destinations)
+- [Log Levels](#log-levels)
+- [Message Lifecycle Logging](#message-lifecycle-logging)
+- [Rails Integration](#rails-integration)
+- [Custom Loggers](#custom-loggers)
+- [Examples](#examples)
+
+## Default Logger
+
+SmartMessage includes a built-in `SmartMessage::Logger::Default` class that automatically detects your environment and chooses the best logging approach:
+
+- **Rails Applications**: Uses `Rails.logger` with tagged logging
+- **Standalone Ruby**: Uses Ruby's standard `Logger` class with file output
+
+### Quick Start
+
+```ruby
+class MyMessage < SmartMessage::Base
+  property :content
+  
+  config do
+    transport SmartMessage::Transport::StdoutTransport.new
+    serializer SmartMessage::Serializer::JSON.new
+    logger SmartMessage::Logger::Default.new  # Zero configuration!
+  end
+end
+```
+
+## Configuration Options
+
+The default logger accepts several configuration options:
+
+### Basic Configuration
+
+```ruby
+# Use defaults (Rails.logger or log/smart_message.log)
+logger SmartMessage::Logger::Default.new
+
+# Custom log file path
+logger SmartMessage::Logger::Default.new(
+  log_file: '/var/log/my_app/messages.log'
+)
+
+# Custom log level
+logger SmartMessage::Logger::Default.new(
+  level: Logger::DEBUG
+)
+
+# Both custom file and level
+logger SmartMessage::Logger::Default.new(
+  log_file: 'logs/custom.log',
+  level: Logger::WARN
+)
+```
+
+## Output Destinations
+
+The default logger supports multiple output destinations:
+
+### File Logging (Default)
+
+```ruby
+# Default file location (Rails convention)
+logger SmartMessage::Logger::Default.new
+# → log/smart_message.log
+
+# Custom file path
+logger SmartMessage::Logger::Default.new(
+  log_file: '/var/log/application/messages.log'
+)
+```
+
+**Features:**
+- Automatic log rotation (10 files, 10MB each)
+- Directory creation if needed
+- Timestamped entries with clean formatting
+
+### STDOUT Logging
+
+Perfect for containerized applications (Docker, Kubernetes):
+
+```ruby
+logger SmartMessage::Logger::Default.new(
+  log_file: STDOUT,
+  level: Logger::INFO
+)
+```
+
+### STDERR Logging
+
+For error-focused logging:
+
+```ruby
+logger SmartMessage::Logger::Default.new(
+  log_file: STDERR,
+  level: Logger::WARN
+)
+```
+
+### In-Memory Logging (Testing)
+
+```ruby
+require 'stringio'
+
+logger SmartMessage::Logger::Default.new(
+  log_file: StringIO.new,
+  level: Logger::DEBUG
+)
+```
+
+## Log Levels
+
+The default logger supports all standard Ruby log levels:
+
+| Level | Numeric Value | Description |
+|-------|--------------|-------------|
+| `Logger::DEBUG` | 0 | Detailed debugging information |
+| `Logger::INFO` | 1 | General information messages |
+| `Logger::WARN` | 2 | Warning messages |
+| `Logger::ERROR` | 3 | Error messages |
+| `Logger::FATAL` | 4 | Fatal error messages |
+
+### Environment-Based Defaults
+
+The default logger automatically sets appropriate log levels based on your environment:
+
+- **Rails Production**: `Logger::INFO`
+- **Rails Test**: `Logger::ERROR`
+- **Rails Development**: `Logger::DEBUG`
+- **Non-Rails**: `Logger::INFO`
+
+## Message Lifecycle Logging
+
+The default logger automatically logs key events in the message lifecycle:
+
+### Message Creation
+
+```ruby
+# Logged at DEBUG level
+message = MyMessage.new(content: "Hello")
+# → [DEBUG] [SmartMessage] Created: MyMessage - {content: "Hello"}
+```
+
+### Message Publishing
+
+```ruby
+# Logged at INFO level
+message.publish
+# → [INFO] [SmartMessage] Published: MyMessage via StdoutTransport
+```
+
+### Message Reception
+
+```ruby
+# Logged at INFO level when message is received
+# → [INFO] [SmartMessage] Received: MyMessage (45 bytes)
+```
+
+### Message Processing
+
+```ruby
+# Logged at INFO level after processing
+# → [INFO] [SmartMessage] Processed: MyMessage - Success
+```
+
+### Subscription Management
+
+```ruby
+# Logged at INFO level
+MyMessage.subscribe
+# → [INFO] [SmartMessage] Subscribed: MyMessage
+
+MyMessage.unsubscribe
+# → [INFO] [SmartMessage] Unsubscribed: MyMessage
+```
+
+### Error Logging
+
+```ruby
+# Logged at ERROR level with full stack trace (DEBUG level)
+# → [ERROR] [SmartMessage] Error in message processing: RuntimeError - Something went wrong
+# → [DEBUG] [SmartMessage] Backtrace: ...
+```
+
+## Rails Integration
+
+When running in a Rails application, the default logger provides enhanced integration:
+
+### Automatic Detection
+
+```ruby
+# Automatically uses Rails.logger when available
+logger SmartMessage::Logger::Default.new
+```
+
+### Tagged Logging
+
+```ruby
+# In Rails, all SmartMessage logs are tagged
+Rails.logger.tagged('SmartMessage') do
+  # All SmartMessage logging happens here
+end
+```
+
+### Rails Log File Location
+
+```ruby
+# Uses Rails.root/log/smart_message.log when Rails is detected
+logger SmartMessage::Logger::Default.new
+# → Rails.root.join('log', 'smart_message.log')
+```
+
+### Rails Environment Handling
+
+The logger respects Rails environment settings:
+
+- **Production**: INFO level, structured logging
+- **Development**: DEBUG level, verbose output  
+- **Test**: ERROR level, minimal output
+
+## Custom Loggers
+
+You can create custom loggers by inheriting from `SmartMessage::Logger::Base`:
+
+### Basic Custom Logger
+
+```ruby
+class SmartMessage::Logger::MyCustomLogger < SmartMessage::Logger::Base
+  def initialize(external_logger)
+    @logger = external_logger
+  end
+  
+  def log_message_created(message)
+    @logger.debug "Created message: #{message.class.name}"
+  end
+  
+  def log_message_published(message, transport)
+    @logger.info "Published #{message.class.name} via #{transport.class.name}"
+  end
+  
+  # Implement other lifecycle methods as needed...
+end
+```
+
+### Wrapper for Third-Party Loggers
+
+```ruby
+# Semantic Logger example
+class SmartMessage::Logger::SemanticLogger < SmartMessage::Logger::Base
+  def initialize(semantic_logger = nil)
+    @logger = semantic_logger || SemanticLogger['SmartMessage']
+  end
+  
+  def log_message_created(message)
+    @logger.debug "Message created", message_class: message.class.name
+  end
+  
+  def log_error(context, error)
+    @logger.error "Error in #{context}", exception: error
+  end
+end
+```
+
+### Multi-Logger (Broadcast)
+
+```ruby
+class SmartMessage::Logger::MultiLogger < SmartMessage::Logger::Base
+  def initialize(*loggers)
+    @loggers = loggers
+  end
+  
+  def log_message_created(message)
+    @loggers.each { |logger| logger.log_message_created(message) }
+  end
+  
+  # Other methods follow same pattern...
+end
+
+# Usage
+logger SmartMessage::Logger::MultiLogger.new(
+  SmartMessage::Logger::Default.new(log_file: 'app.log'),
+  SmartMessage::Logger::Default.new(log_file: STDOUT),
+  SmartMessage::Logger::MyCustomLogger.new(external_system)
+)
+```
+
+## Examples
+
+### Development Setup
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  property :order_id, String, required: true
+  property :customer_id, String, required: true
+  property :amount, Float, required: true
+  
+  config do
+    transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Verbose logging for development
+    logger SmartMessage::Logger::Default.new(
+      log_file: STDOUT,
+      level: Logger::DEBUG
+    )
+  end
+  
+  def self.process(message_header, message_payload)
+    data = JSON.parse(message_payload)
+    
+    # Logger is available in process method
+    logger.info "Processing order #{data['order_id']}"
+    
+    # Business logic here
+    result = process_order(data)
+    
+    logger.info "Order #{data['order_id']} completed: #{result}"
+    result
+  end
+end
+```
+
+### Production Setup
+
+```ruby
+class NotificationMessage < SmartMessage::Base
+  property :recipient, String, required: true
+  property :subject, String, required: true
+  property :body, String, required: true
+  
+  config do
+    transport SmartMessage::Transport::RedisTransport.new
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Production logging with file rotation
+    logger SmartMessage::Logger::Default.new(
+      log_file: '/var/log/app/notifications.log',
+      level: Logger::INFO
+    )
+  end
+end
+```
+
+### Docker/Kubernetes Setup
+
+```ruby
+class EventMessage < SmartMessage::Base
+  property :event_type, String, required: true
+  property :data, Hash, required: true
+  
+  config do
+    transport SmartMessage::Transport::RedisTransport.new(
+      redis_url: ENV['REDIS_URL']
+    )
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Container-friendly STDOUT logging
+    logger SmartMessage::Logger::Default.new(
+      log_file: STDOUT,
+      level: ENV['LOG_LEVEL']&.upcase&.to_sym || Logger::INFO
+    )
+  end
+end
+```
+
+### Testing Setup
+
+```ruby
+# In test_helper.rb or similar
+class TestMessage < SmartMessage::Base
+  property :test_data, Hash
+  
+  config do
+    transport SmartMessage::Transport::MemoryTransport.new
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Minimal logging for tests
+    logger SmartMessage::Logger::Default.new(
+      log_file: StringIO.new,
+      level: Logger::FATAL  # Only fatal errors in tests
+    )
+  end
+end
+```
+
+### Instance-Level Logger Override
+
+```ruby
+# Different logger for specific instances
+class PriorityMessage < SmartMessage::Base
+  property :priority, String
+  property :data, Hash
+  
+  config do
+    transport SmartMessage::Transport::RedisTransport.new
+    serializer SmartMessage::Serializer::JSON.new
+    logger SmartMessage::Logger::Default.new  # Default logger
+  end
+end
+
+# Override logger for high-priority messages
+priority_logger = SmartMessage::Logger::Default.new(
+  log_file: '/var/log/priority.log',
+  level: Logger::DEBUG
+)
+
+urgent_message = PriorityMessage.new(priority: 'urgent', data: {...})
+urgent_message.logger(priority_logger)  # Override for this instance
+urgent_message.publish
+```
+
+## Best Practices
+
+1. **Use the default logger** unless you have specific requirements
+2. **Log to STDOUT** in containerized environments
+3. **Use appropriate log levels** - avoid DEBUG in production
+4. **Tag your logs** for better searchability
+5. **Consider structured logging** for production systems
+6. **Test your logging** - ensure logs are helpful for debugging
+7. **Monitor log volume** - excessive logging can impact performance
+8. **Rotate log files** to prevent disk space issues (default logger handles this)
+
+## Troubleshooting
+
+### No logs appearing
+- Check log level settings
+- Verify file permissions
+- Ensure logger is configured
+
+### Too much logging
+- Increase log level (DEBUG → INFO → WARN → ERROR)
+- Consider filtering in production
+
+### Performance issues
+- Lower log level in production
+- Use asynchronous logging for high-volume systems
+- Consider structured logging formats
+
+### Rails integration not working
+- Ensure Rails is loaded before SmartMessage
+- Check that `Rails.logger` is available
+- Verify Rails environment is set correctly
+
+For more troubleshooting tips, see the [Troubleshooting Guide](troubleshooting.md).

data/examples/.gitignore

@@ -0,0 +1,2 @@
+/log/
+*.log

data/examples/06_custom_logger_example.rb

@@ -0,0 +1,620 @@
+#!/usr/bin/env ruby
+# examples/06_custom_logger_example.rb
+#
+# Custom Logger Example: Comprehensive Message Logging
+#
+# This example demonstrates how to implement and use custom loggers in the SmartMessage
+# framework. It shows different logging strategies including file logging, structured 
+# logging, and audit trails for message processing workflows.
+#
+# IMPORTANT: Using the Default Logger or Custom Loggers
+# ====================================================================
+# SmartMessage now includes a DEFAULT LOGGER that automatically detects your environment:
+# - Uses Rails.logger if running in a Rails application
+# - Uses Ruby's standard Logger otherwise (logs to log/smart_message.log)
+#
+# To use the default logger (EASIEST OPTION):
+#   config do
+#     logger SmartMessage::Logger::Default.new
+#   end
+#
+# To use the default logger with custom settings:
+#   config do
+#     logger SmartMessage::Logger::Default.new(
+#       log_file: 'custom/path.log',
+#       level: Logger::DEBUG
+#     )
+#   end
+#
+# To log to STDOUT (useful for Docker/Kubernetes):
+#   config do
+#     logger SmartMessage::Logger::Default.new(
+#       log_file: STDOUT,
+#       level: Logger::INFO
+#     )
+#   end
+#
+# To create your own custom logger:
+#   1. Create a wrapper class that inherits from SmartMessage::Logger::Base
+#   2. Store the Ruby logger instance in your wrapper
+#   3. Implement the SmartMessage logging methods using your Ruby logger
+#
+# To use Rails.logger directly (without the default logger):
+#   1. Create a wrapper that delegates to Rails.logger
+#   2. Configure it at the class level: logger SmartMessage::Logger::RailsLogger.new
+#   3. All messages will be logged to your Rails application logs
+
+require_relative '../lib/smart_message'
+require 'logger'
+require 'json'
+require 'fileutils'
+
+puts "=== SmartMessage Example: Custom Logger Implementation ==="
+puts
+
+# Custom File Logger Implementation
+# This wrapper shows how to integrate Ruby's standard Logger class with SmartMessage.
+# The same pattern works for Rails.logger, Semantic Logger, or any Ruby logger.
+class SmartMessage::Logger::FileLogger < SmartMessage::Logger::Base
+  attr_reader :log_file_path, :logger
+  
+  def initialize(log_file_path, level: Logger::INFO)
+    @log_file_path = log_file_path
+    
+    # Ensure log directory exists
+    FileUtils.mkdir_p(File.dirname(@log_file_path))
+    
+    # This is Ruby's standard Logger class from the 'logger' library
+    # You could replace this with Rails.logger or any other logger:
+    #   @logger = Rails.logger  # For Rails applications
+    #   @logger = SemanticLogger['SmartMessage']  # For Semantic Logger
+    #   @logger = $stdout.sync = Logger.new($stdout)  # For stdout logging
+    @logger = Logger.new(@log_file_path)
+    @logger.level = level
+    @logger.formatter = proc do |severity, datetime, progname, msg|
+      "[#{datetime.strftime('%Y-%m-%d %H:%M:%S.%3N')}] #{severity}: #{msg}\n"
+    end
+  end
+  
+  def log_message_created(message)
+    @logger.info("MESSAGE_CREATED: #{message.class.name} - #{message.to_h}")
+  end
+  
+  def log_message_published(message, transport)
+    @logger.info("MESSAGE_PUBLISHED: #{message.class.name} via #{transport.class.name}")
+  end
+  
+  def log_message_received(message_class, payload)
+    @logger.info("MESSAGE_RECEIVED: #{message_class.name} - #{payload}")
+  end
+  
+  def log_message_processed(message_class, result)
+    @logger.info("MESSAGE_PROCESSED: #{message_class.name} - Result: #{result}")
+  end
+  
+  def log_error(message, error)
+    @logger.error("MESSAGE_ERROR: #{message} - #{error.class.name}: #{error.message}")
+  end
+end
+
+# Structured JSON Logger Implementation
+class SmartMessage::Logger::JSONLogger < SmartMessage::Logger::Base
+  attr_reader :log_file_path
+  
+  def initialize(log_file_path)
+    @log_file_path = log_file_path
+    
+    # Ensure log directory exists
+    FileUtils.mkdir_p(File.dirname(@log_file_path))
+  end
+  
+  def log_message_created(message)
+    write_log_entry({
+      event: 'message_created',
+      message_class: message.class.name,
+      message_id: message._sm_header&.message_id,
+      timestamp: Time.now.iso8601,
+      data: message.to_h
+    })
+  end
+  
+  def log_message_published(message, transport)
+    write_log_entry({
+      event: 'message_published',
+      message_class: message.class.name,
+      message_id: message._sm_header&.message_id,
+      transport: transport.class.name,
+      timestamp: Time.now.iso8601
+    })
+  end
+  
+  def log_message_received(message_class, payload)
+    write_log_entry({
+      event: 'message_received',
+      message_class: message_class.name,
+      payload_size: payload.length,
+      timestamp: Time.now.iso8601
+    })
+  end
+  
+  def log_message_processed(message_class, result)
+    write_log_entry({
+      event: 'message_processed',
+      message_class: message_class.name,
+      result: result.to_s,
+      timestamp: Time.now.iso8601
+    })
+  end
+  
+  def log_error(message, error)
+    write_log_entry({
+      event: 'error',
+      message: message.to_s,
+      error_class: error.class.name,
+      error_message: error.message,
+      backtrace: error.backtrace&.first(5),
+      timestamp: Time.now.iso8601
+    })
+  end
+  
+  private
+  
+  def write_log_entry(data)
+    File.open(@log_file_path, 'a') do |file|
+      file.puts(JSON.generate(data))
+    end
+  end
+end
+
+# Console Logger with Emoji Implementation
+class SmartMessage::Logger::EmojiConsoleLogger < SmartMessage::Logger::Base
+  def log_message_created(message)
+    puts "🏗️  Created: #{message.class.name} with data: #{message.to_h}"
+  end
+  
+  def log_message_published(message, transport)
+    puts "📤 Published: #{message.class.name} via #{transport.class.name}"
+  end
+  
+  def log_message_received(message_class, payload)
+    puts "📥 Received: #{message_class.name} (#{payload.length} bytes)"
+  end
+  
+  def log_message_processed(message_class, result)
+    puts "⚙️  Processed: #{message_class.name} → #{result}"
+  end
+  
+  def log_error(message, error)
+    puts "❌ Error: #{message} → #{error.class.name}: #{error.message}"
+  end
+end
+
+# Example: Simple Ruby Logger Wrapper
+# This demonstrates the minimal wrapper needed for Ruby's standard Logger.
+# Use this pattern when you want to integrate with existing logging infrastructure.
+class SmartMessage::Logger::RubyLoggerWrapper < SmartMessage::Logger::Base
+  def initialize(ruby_logger = nil)
+    # Accept any Ruby logger instance, or create a default one
+    @logger = ruby_logger || Logger.new(STDOUT)
+  end
+  
+  def log_message_created(message)
+    @logger.debug { "SmartMessage created: #{message.class.name} ID: #{message._sm_header&.message_id}" }
+  end
+  
+  def log_message_published(message, transport)
+    @logger.info { "SmartMessage published: #{message.class.name} via #{transport.class.name}" }
+  end
+  
+  def log_message_received(message_class, payload)
+    @logger.info { "SmartMessage received: #{message_class.name}" }
+  end
+  
+  def log_message_processed(message_class, result)
+    @logger.info { "SmartMessage processed: #{message_class.name}" }
+  end
+  
+  def log_error(message, error)
+    @logger.error { "SmartMessage error: #{message} - #{error.message}" }
+    @logger.debug { error.backtrace.join("\n") }
+  end
+end
+
+# Example: Rails Logger Wrapper (for Rails applications)
+# Uncomment and use this in your Rails application
+# class SmartMessage::Logger::RailsLogger < SmartMessage::Logger::Base
+#   def log_message_created(message)
+#     Rails.logger.tagged('SmartMessage', message.class.name) do
+#       Rails.logger.info "Message created with ID: #{message._sm_header&.message_id}"
+#     end
+#   end
+#   
+#   def log_message_published(message, transport)
+#     Rails.logger.tagged('SmartMessage', message.class.name) do
+#       Rails.logger.info "Message published via #{transport.class.name}"
+#     end
+#   end
+#   
+#   def log_message_received(message_class, payload)
+#     Rails.logger.tagged('SmartMessage', message_class.name) do
+#       Rails.logger.info "Message received (#{payload.length} bytes)"
+#     end
+#   end
+#   
+#   def log_message_processed(message_class, result)
+#     Rails.logger.tagged('SmartMessage', message_class.name) do
+#       Rails.logger.info "Message processed successfully"
+#     end
+#   end
+#   
+#   def log_error(message, error)
+#     Rails.logger.tagged('SmartMessage') do
+#       Rails.logger.error "Error: #{message}"
+#       Rails.logger.error "#{error.class.name}: #{error.message}"
+#       Rails.logger.debug error.backtrace.join("\n")
+#     end
+#   end
+# end
+
+# Multi-logger that broadcasts to multiple loggers
+class SmartMessage::Logger::MultiLogger < SmartMessage::Logger::Base
+  def initialize(*loggers)
+    @loggers = loggers
+  end
+  
+  def log_message_created(message)
+    @loggers.each { |logger| logger.log_message_created(message) }
+  end
+  
+  def log_message_published(message, transport)
+    @loggers.each { |logger| logger.log_message_published(message, transport) }
+  end
+  
+  def log_message_received(message_class, payload)
+    @loggers.each { |logger| logger.log_message_received(message_class, payload) }
+  end
+  
+  def log_message_processed(message_class, result)
+    @loggers.each { |logger| logger.log_message_processed(message_class, result) }
+  end
+  
+  def log_error(message, error)
+    @loggers.each { |logger| logger.log_error(message, error) }
+  end
+end
+
+# Sample message class with comprehensive logging
+class OrderProcessingMessage < SmartMessage::Base
+  property :order_id
+  property :customer_id
+  property :amount
+  property :status
+  property :items
+  
+  config do
+    transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Configure multi-logger to demonstrate different logging approaches
+    logger SmartMessage::Logger::MultiLogger.new(
+      SmartMessage::Logger::EmojiConsoleLogger.new,
+      SmartMessage::Logger::FileLogger.new('logs/order_processing.log', level: Logger::DEBUG),
+      SmartMessage::Logger::JSONLogger.new('logs/order_processing.json')
+    )
+  end
+  
+  def self.process(message_header, message_payload)
+    # Simulate the logger being called during processing
+    if logger
+      logger.log_message_received(self, message_payload)
+    end
+    
+    # Process the message
+    order_data = JSON.parse(message_payload)
+    result = "Order #{order_data['order_id']} processed successfully"
+    
+    puts "💼 OrderProcessing: #{result}"
+    
+    # Log processing completion
+    if logger
+      logger.log_message_processed(self, result)
+    end
+    
+    result
+  end
+  
+  # Override publish to demonstrate logging hooks
+  def publish
+    # Log message creation
+    logger_instance = logger || self.class.logger
+    if logger_instance
+      logger_instance.log_message_created(self)
+    end
+    
+    # Log publishing
+    transport_instance = transport || self.class.transport
+    if logger_instance
+      logger_instance.log_message_published(self, transport_instance)
+    end
+    
+    # Call original publish method
+    super
+  rescue => error
+    # Log any errors during publishing
+    if logger_instance
+      logger_instance.log_error("Failed to publish #{self.class.name}", error)
+    end
+    raise
+  end
+end
+
+# Notification message with different logger configuration
+class NotificationMessage < SmartMessage::Base
+  property :recipient
+  property :subject
+  property :body
+  property :priority
+  
+  config do
+    transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Use only file logger for notifications
+    logger SmartMessage::Logger::FileLogger.new('logs/notifications.log', level: Logger::WARN)
+  end
+  
+  def self.process(message_header, message_payload)
+    if logger
+      logger.log_message_received(self, message_payload)
+    end
+    
+    notification_data = JSON.parse(message_payload)
+    result = "Notification sent to #{notification_data['recipient']}"
+    
+    puts "📬 Notification: #{result}"
+    
+    if logger
+      logger.log_message_processed(self, result)
+    end
+    
+    result
+  end
+end
+
+# Example: Message class using standard Ruby logger
+# This demonstrates how to use Ruby's standard Logger in production code
+class StandardLoggerMessage < SmartMessage::Base
+  property :content
+  property :level
+  
+  config do
+    transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Example 1: Using Ruby's standard Logger directly
+    # Create a standard Ruby logger that logs to STDOUT
+    ruby_logger = Logger.new(STDOUT)
+    ruby_logger.level = Logger::INFO
+    ruby_logger.progname = 'SmartMessage'
+    
+    # Wrap it in our adapter
+    logger SmartMessage::Logger::RubyLoggerWrapper.new(ruby_logger)
+    
+    # Example 2: Using a file-based Ruby logger (commented out)
+    # file_logger = Logger.new('application.log', 'daily')  # Rotate daily
+    # logger SmartMessage::Logger::RubyLoggerWrapper.new(file_logger)
+    
+    # Example 3: In Rails, you would use Rails.logger (commented out)
+    # logger SmartMessage::Logger::RubyLoggerWrapper.new(Rails.logger)
+  end
+  
+  def self.process(message_header, message_payload)
+    data = JSON.parse(message_payload)
+    puts "📝 Processing: #{data['content']}"
+    "Processed"
+  end
+end
+
+# Example: Message using the built-in Default Logger
+class DefaultLoggerMessage < SmartMessage::Base
+  property :message
+  property :level
+  
+  config do
+    transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Use the built-in default logger - simplest option!
+    logger SmartMessage::Logger::Default.new
+  end
+  
+  def self.process(message_header, message_payload)
+    data = JSON.parse(message_payload)
+    puts "🎯 DefaultLogger: Processing #{data['message']}"
+    "Processed with default logger"
+  end
+end
+
+# Service that uses instance-level logger override
+class PriorityOrderService
+  def initialize
+    puts "🚀 PriorityOrderService: Starting with custom logger..."
+    
+    # Create a priority-specific logger
+    @priority_logger = SmartMessage::Logger::FileLogger.new(
+      'logs/priority_orders.log', 
+      level: Logger::DEBUG
+    )
+  end
+  
+  def process_priority_order(order_data)
+    # Create message with instance-level logger override
+    message = OrderProcessingMessage.new(**order_data)
+    
+    # Override the logger at instance level
+    message.logger(@priority_logger)
+    
+    puts "⚡ Processing priority order with dedicated logger"
+    message.publish
+    
+    message
+  end
+end
+
+# Demo runner
+class LoggerDemo
+  def run
+    puts "🚀 Starting Custom Logger Demo\n"
+    
+    # Clean up any existing log files for a fresh demo
+    FileUtils.rm_rf('logs') if Dir.exist?('logs')
+    
+    # Subscribe to messages
+    OrderProcessingMessage.subscribe
+    NotificationMessage.subscribe
+    
+    puts "\n" + "="*70
+    puts "Demonstrating Different Logger Configurations"
+    puts "="*70
+    
+    # Demo 1: Using the built-in Default Logger (NEW!)
+    puts "\n--- Demo 1: Using SmartMessage Default Logger ---"
+    puts "The Default logger automatically uses Rails.logger or Ruby Logger"
+    
+    # Use the DefaultLoggerMessage class defined above
+    DefaultLoggerMessage.subscribe
+    default_msg = DefaultLoggerMessage.new(
+      message: "Testing the built-in default logger",
+      level: "info"
+    )
+    default_msg.publish
+    sleep(0.5)
+    
+    # Demo 2: Standard order with multi-logger
+    puts "\n--- Demo 2: Standard Order (Multi-Logger) ---"
+    order1 = OrderProcessingMessage.new(
+      order_id: "ORD-001",
+      customer_id: "CUST-123",
+      amount: 99.99,
+      status: "pending",
+      items: ["Widget A", "Widget B"]
+    )
+    order1.publish
+    sleep(0.5)
+    
+    # Demo 3: Notification with file-only logger
+    puts "\n--- Demo 3: Notification (File Logger Only) ---"
+    notification = NotificationMessage.new(
+      recipient: "customer@example.com",
+      subject: "Order Confirmation",
+      body: "Your order has been received",
+      priority: "normal"
+    )
+    notification.publish
+    sleep(0.5)
+    
+    # Demo 4: Priority order with instance-level logger override
+    puts "\n--- Demo 4: Priority Order (Instance Logger Override) ---"
+    priority_service = PriorityOrderService.new
+    priority_order = priority_service.process_priority_order(
+      order_id: "ORD-PRIORITY-001",
+      customer_id: "VIP-456",
+      amount: 299.99,
+      status: "urgent",
+      items: ["Premium Widget", "Express Shipping"]
+    )
+    sleep(0.5)
+    
+    # Demo 5: Using standard Ruby logger
+    puts "\n--- Demo 5: Using Standard Ruby Logger ---"
+    
+    # Use the StandardLoggerMessage class that demonstrates Ruby's standard logger
+    StandardLoggerMessage.subscribe
+    
+    # Create and send a message - watch for the Ruby logger output
+    msg = StandardLoggerMessage.new(
+      content: "Testing with Ruby's standard logger",
+      level: "info"
+    )
+    
+    # The logger will output to STDOUT using Ruby's standard format
+    msg.publish
+    sleep(0.5)
+    
+    puts "\nNote: The above used Ruby's standard Logger class wrapped for SmartMessage"
+    puts "You can use ANY Ruby logger this way: Logger.new, Rails.logger, etc."
+    
+    # Demo 6: Error handling with logging
+    puts "\n--- Demo 6: Error Handling with Logging ---"
+    begin
+      # Create a message that will cause an error
+      faulty_order = OrderProcessingMessage.new(
+        order_id: nil,  # This might cause issues
+        customer_id: "ERROR-TEST",
+        amount: "invalid_amount",
+        status: "error_demo"
+      )
+      
+      # Simulate an error during processing
+      if OrderProcessingMessage.logger
+        OrderProcessingMessage.logger.log_error(
+          "Simulated error for demo",
+          StandardError.new("Invalid order data provided")
+        )
+      end
+      
+    rescue => error
+      puts "🔍 Caught demonstration error: #{error.message}"
+    end
+    
+    # Show log file contents
+    puts "\n" + "="*70
+    puts "📋 Log File Contents"
+    puts "="*70
+    
+    show_log_contents
+    
+    puts "\n✨ Demo completed!"
+    puts "\nThis example demonstrated:"
+    puts "• SmartMessage::Logger::Default - Built-in logger that auto-detects Rails/Ruby"
+    puts "• Integration with Ruby's standard Logger class"
+    puts "• How to wrap Rails.logger or any Ruby logger for SmartMessage"
+    puts "• Custom logger implementations (File, JSON, Console, Multi-logger)"
+    puts "• Class-level and instance-level logger configuration"
+    puts "• Different logging strategies for different message types"
+    puts "• Error logging and message lifecycle logging"
+    puts "• Log file management and structured logging formats"
+    puts "\nKEY TAKEAWAY: Use SmartMessage::Logger::Default.new for instant logging!"
+    puts "It automatically uses Rails.logger in Rails or creates a Ruby Logger otherwise."
+  end
+  
+  private
+  
+  def show_log_contents
+    log_files = Dir.glob('logs/*.log') + Dir.glob('logs/*.json')
+    
+    log_files.each do |log_file|
+      next unless File.exist?(log_file)
+      
+      puts "\n📁 #{log_file}:"
+      puts "-" * 50
+      
+      content = File.read(log_file)
+      if content.length > 500
+        puts content[0..500] + "\n... (truncated, #{content.length} total characters)"
+      else
+        puts content
+      end
+    end
+    
+    if log_files.empty?
+      puts "⚠️  No log files found (they may not have been created yet)"
+    end
+  end
+end
+
+# Run the demo if this file is executed directly
+if __FILE__ == $0
+  demo = LoggerDemo.new
+  demo.run
+end

data/lib/smart_message/logger/default.rb

@@ -0,0 +1,217 @@
+# lib/smart_message/logger/default.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'logger'
+require 'fileutils'
+require 'stringio'
+
+module SmartMessage
+  module Logger
+    # Default logger implementation for SmartMessage
+    # 
+    # This logger automatically detects and uses the best available logging option:
+    # - Rails.logger if running in a Rails application
+    # - Standard Ruby Logger writing to log/smart_message.log otherwise
+    #
+    # Usage:
+    #   # In your message class
+    #   config do
+    #     logger SmartMessage::Logger::Default.new
+    #   end
+    #
+    #   # Or with custom options
+    #   config do
+    #     logger SmartMessage::Logger::Default.new(
+    #       log_file: 'custom/path.log',    # File path
+    #       level: Logger::DEBUG
+    #     )
+    #   end
+    #
+    #   # To log to STDOUT instead of a file
+    #   config do
+    #     logger SmartMessage::Logger::Default.new(
+    #       log_file: STDOUT,               # STDOUT or STDERR
+    #       level: Logger::INFO
+    #     )
+    #   end
+    class Default < Base
+      attr_reader :logger, :log_file, :level
+      
+      def initialize(log_file: nil, level: nil)
+        @log_file = log_file || default_log_file
+        @level = level || default_log_level
+        
+        @logger = setup_logger
+      end
+      
+      # Message lifecycle logging methods
+      
+      def log_message_created(message)
+        logger.debug { "[SmartMessage] Created: #{message.class.name} - #{message_summary(message)}" }
+      end
+      
+      def log_message_published(message, transport)
+        logger.info { "[SmartMessage] Published: #{message.class.name} via #{transport.class.name.split('::').last}" }
+      end
+      
+      def log_message_received(message_class, payload)
+        logger.info { "[SmartMessage] Received: #{message_class.name} (#{payload.bytesize} bytes)" }
+      end
+      
+      def log_message_processed(message_class, result)
+        logger.info { "[SmartMessage] Processed: #{message_class.name} - #{truncate(result.to_s, 100)}" }
+      end
+      
+      def log_message_subscribe(message_class, handler = nil)
+        handler_desc = handler ? " with handler: #{handler}" : ""
+        logger.info { "[SmartMessage] Subscribed: #{message_class.name}#{handler_desc}" }
+      end
+      
+      def log_message_unsubscribe(message_class)
+        logger.info { "[SmartMessage] Unsubscribed: #{message_class.name}" }
+      end
+      
+      # Error logging
+      
+      def log_error(context, error)
+        logger.error { "[SmartMessage] Error in #{context}: #{error.class.name} - #{error.message}" }
+        logger.debug { "[SmartMessage] Backtrace:\n#{error.backtrace.join("\n")}" } if error.backtrace
+      end
+      
+      def log_warning(message)
+        logger.warn { "[SmartMessage] Warning: #{message}" }
+      end
+      
+      # General purpose logging methods matching Ruby's Logger interface
+      
+      def debug(message = nil, &block)
+        logger.debug(message, &block)
+      end
+      
+      def info(message = nil, &block)
+        logger.info(message, &block)
+      end
+      
+      def warn(message = nil, &block)
+        logger.warn(message, &block)
+      end
+      
+      def error(message = nil, &block)
+        logger.error(message, &block)
+      end
+      
+      def fatal(message = nil, &block)
+        logger.fatal(message, &block)
+      end
+      
+      private
+      
+      def setup_logger
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          # Use Rails logger if available
+          setup_rails_logger
+        else
+          # Use standard Ruby logger
+          setup_ruby_logger
+        end
+      end
+      
+      def setup_rails_logger
+        # Wrap Rails.logger to ensure our messages are properly tagged
+        RailsLoggerWrapper.new(Rails.logger, level: @level)
+      end
+      
+      def setup_ruby_logger
+        # Handle IO objects (STDOUT, STDERR) vs file paths
+        if @log_file.is_a?(IO) || @log_file.is_a?(StringIO)
+          # For STDOUT/STDERR, don't use rotation
+          ruby_logger = ::Logger.new(@log_file)
+        else
+          # For file paths, ensure directory exists and use rotation
+          FileUtils.mkdir_p(File.dirname(@log_file))
+          
+          ruby_logger = ::Logger.new(
+            @log_file,
+            10,           # Keep 10 old log files
+            10_485_760    # Rotate when file reaches 10MB
+          )
+        end
+        
+        ruby_logger.level = @level
+        
+        # Set a clean formatter
+        ruby_logger.formatter = proc do |severity, datetime, progname, msg|
+          timestamp = datetime.strftime('%Y-%m-%d %H:%M:%S.%3N')
+          "[#{timestamp}] #{severity.ljust(5)} -- : #{msg}\n"
+        end
+        
+        ruby_logger
+      end
+      
+      def default_log_file
+        if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+          Rails.root.join('log', 'smart_message.log').to_s
+        else
+          'log/smart_message.log'
+        end
+      end
+      
+      def default_log_level
+        if defined?(Rails) && Rails.respond_to?(:env)
+          case Rails.env
+          when 'production'
+            ::Logger::INFO
+          when 'test'
+            ::Logger::ERROR
+          else
+            ::Logger::DEBUG
+          end
+        else
+          # Default to INFO for non-Rails environments
+          ::Logger::INFO
+        end
+      end
+      
+      def message_summary(message)
+        # Create a brief summary of the message for logging
+        if message.respond_to?(:to_h)
+          data = message.to_h
+          # Remove internal header for cleaner logs
+          data.delete(:_sm_header)
+          data.delete('_sm_header')
+          truncate(data.inspect, 200)
+        else
+          truncate(message.inspect, 200)
+        end
+      end
+      
+      def truncate(string, max_length)
+        return string if string.length <= max_length
+        "#{string[0...max_length]}..."
+      end
+      
+      # Internal wrapper for Rails.logger to handle tagged logging
+      class RailsLoggerWrapper
+        def initialize(rails_logger, level: nil)
+          @rails_logger = rails_logger
+          @rails_logger.level = level if level
+        end
+        
+        def method_missing(method, *args, &block)
+          if @rails_logger.respond_to?(:tagged)
+            @rails_logger.tagged('SmartMessage') do
+              @rails_logger.send(method, *args, &block)
+            end
+          else
+            @rails_logger.send(method, *args, &block)
+          end
+        end
+        
+        def respond_to_missing?(method, include_private = false)
+          @rails_logger.respond_to?(method, include_private)
+        end
+      end
+    end
+  end
+end

data/lib/smart_message/logger.rb

@@ -3,5 +3,13 @@
 # frozen_string_literal: true
 
 module SmartMessage::Logger
-  # TODO: write this
+  # Logger module provides logging capabilities for SmartMessage
+  # The Default logger automatically uses Rails.logger if available,
+  # otherwise falls back to a standard Ruby Logger
 end # module SmartMessage::Logger
+
+# Load the base class first
+require_relative 'logger/base'
+
+# Load the default logger implementation
+require_relative 'logger/default'

data/lib/smart_message/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 module SmartMessage
-  VERSION = "0.0.3"
+  VERSION = '0.0.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smart_message
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -204,17 +204,20 @@ files:
 - docs/examples.md
 - docs/getting-started.md
 - docs/ideas_to_think_about.md
+- docs/logging.md
 - docs/message_processing.md
 - docs/proc_handlers_summary.md
 - docs/properties.md
 - docs/serializers.md
 - docs/transports.md
 - docs/troubleshooting.md
+- examples/.gitignore
 - examples/01_point_to_point_orders.rb
 - examples/02_publish_subscribe_events.rb
 - examples/03_many_to_many_chat.rb
 - examples/04_redis_smart_home_iot.rb
 - examples/05_proc_handlers.rb
+- examples/06_custom_logger_example.rb
 - examples/README.md
 - examples/smart_home_iot_dataflow.md
 - examples/tmux_chat/README.md
@@ -233,6 +236,7 @@ files:
 - lib/smart_message/header.rb
 - lib/smart_message/logger.rb
 - lib/smart_message/logger/base.rb
+- lib/smart_message/logger/default.rb
 - lib/smart_message/property_descriptions.rb
 - lib/smart_message/serializer.rb
 - lib/smart_message/serializer/base.rb