cmdx 0.5.0 → 1.0.0

data/lib/cmdx/log_formatters/json.rb

@@ -2,8 +2,54 @@
 
 module CMDx
   module LogFormatters
+    # JSON log formatter for CMDx logging system.
+    #
+    # Formats log entries as single-line JSON objects containing task execution metadata
+    # including severity, timestamp, process ID, and serialized task information.
+    # Ideal for structured logging systems that need to parse log data programmatically.
+    #
+    # @example Basic usage with global logger configuration
+    #   CMDx.configure do |config|
+    #     config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Json.new)
+    #   end
+    #
+    # @example Task-specific formatter configuration
+    #   class ProcessOrderTask < CMDx::Task
+    #     task_settings!(log_format: CMDx::LogFormatters::Json.new)
+    #
+    #     def call
+    #       logger.info "Processing order #{order_id}"
+    #     end
+    #   end
+    #
+    # @example Sample JSON output
+    #   {"severity":"INFO","pid":1234,"timestamp":"2022-07-17T18:43:15.000000","index":0,"chain_id":"018c2b95-b764-7615","type":"Task","class":"ProcessOrderTask","id":"018c2b95-b764-7615","tags":[],"state":"complete","status":"success","outcome":"success","metadata":{},"runtime":15,"origin":"CMDx"}
+    #
+    # @see CMDx::LogFormatters::PrettyJson For human-readable JSON formatting
+    # @see CMDx::LoggerSerializer For details on serialized data structure
     class Json
 
+      # Formats a log entry as a single-line JSON string.
+      #
+      # Combines task execution metadata with severity, process ID, and timestamp
+      # information to create a comprehensive JSON log entry suitable for
+      # structured logging systems and log aggregation tools.
+      #
+      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param time [Time] Timestamp when the log entry was created
+      # @param task [CMDx::Task] Task instance being logged
+      # @param message [Object] Log message or data to be included
+      #
+      # @return [String] Single-line JSON string with newline terminator
+      #
+      # @example Success log entry
+      #   formatter = CMDx::LogFormatters::Json.new
+      #   output = formatter.call("INFO", Time.now, task, "Order processed")
+      #   # => {"severity":"INFO","pid":1234,...}\n
+      #
+      # @example Error log entry with metadata
+      #   output = formatter.call("ERROR", Time.now, task, error_details)
+      #   # => {"severity":"ERROR","pid":1234,"caused_failure":{...},...}\n
       def call(severity, time, task, message)
         m = LoggerSerializer.call(severity, time, task, message).merge!(
           severity:,

data/lib/cmdx/log_formatters/key_value.rb

@@ -2,8 +2,54 @@
 
 module CMDx
   module LogFormatters
+    # Key-value log formatter for CMDx logging system.
+    #
+    # Formats log entries as space-separated key=value pairs on a single line.
+    # Provides a compact, structured format that is easily parseable by log
+    # processing tools while remaining human-readable for basic inspection.
+    #
+    # @example Basic usage with global logger configuration
+    #   CMDx.configure do |config|
+    #     config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::KeyValue.new)
+    #   end
+    #
+    # @example Task-specific formatter configuration
+    #   class ProcessOrderTask < CMDx::Task
+    #     task_settings!(log_format: CMDx::LogFormatters::KeyValue.new)
+    #
+    #     def call
+    #       logger.info "Processing order #{order_id}"
+    #     end
+    #   end
+    #
+    # @example Sample key-value output
+    #   severity=INFO pid=1234 timestamp=2022-07-17T18:43:15.000000 index=0 chain_id=018c2b95-b764-7615 type=Task class=ProcessOrderTask id=018c2b95-b764-7615 tags=[] state=complete status=success outcome=success metadata={} runtime=15 origin=CMDx
+    #
+    # @see CMDx::LogFormatters::PrettyKeyValue For ANSI-colorized key-value formatting
+    # @see CMDx::LoggerSerializer For details on serialized data structure
     class KeyValue
 
+      # Formats a log entry as space-separated key=value pairs.
+      #
+      # Combines task execution metadata with severity, process ID, and timestamp
+      # information to create a compact key-value log entry suitable for
+      # structured logging systems that prefer flat field formats.
+      #
+      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param time [Time] Timestamp when the log entry was created
+      # @param task [CMDx::Task] Task instance being logged
+      # @param message [Object] Log message or data to be included
+      #
+      # @return [String] Single-line key=value formatted string with newline terminator
+      #
+      # @example Success log entry
+      #   formatter = CMDx::LogFormatters::KeyValue.new
+      #   output = formatter.call("INFO", Time.now, task, "Order processed")
+      #   # => "severity=INFO pid=1234 timestamp=... status=success\n"
+      #
+      # @example Error log entry with failure metadata
+      #   output = formatter.call("ERROR", Time.now, task, error_details)
+      #   # => "severity=ERROR pid=1234 ... caused_failure={...} threw_failure={...}\n"
       def call(severity, time, task, message)
         m = LoggerSerializer.call(severity, time, task, message).merge!(
           severity:,

data/lib/cmdx/log_formatters/line.rb

@@ -2,8 +2,62 @@
 
 module CMDx
   module LogFormatters
+    # Line log formatter for CMDx logging system.
+    #
+    # Formats log entries in a traditional single-line format similar to Ruby's
+    # standard Logger output. Combines severity indicators, timestamps, process
+    # information, and task details in a compact, readable format suitable for
+    # standard logging environments.
+    #
+    # @example Basic usage with global logger configuration
+    #   CMDx.configure do |config|
+    #     config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
+    #   end
+    #
+    # @example Task-specific formatter configuration
+    #   class ProcessOrderTask < CMDx::Task
+    #     task_settings!(log_format: CMDx::LogFormatters::Line.new)
+    #
+    #     def call
+    #       logger.info "Processing order #{order_id}"
+    #     end
+    #   end
+    #
+    # @example Sample line output
+    #   I, [2022-07-17T18:43:15.000000 #1234] INFO -- ProcessOrderTask: state=complete status=success outcome=success runtime=15
+    #
+    # @example Error line output with failure details
+    #   E, [2022-07-17T18:43:15.000000 #1234] ERROR -- ProcessOrderTask: state=interrupted status=failed outcome=failed caused_failure={...}
+    #
+    # @see CMDx::LogFormatters::PrettyLine For ANSI-colorized line formatting
+    # @see CMDx::LoggerSerializer For details on serialized data structure
+    # @see CMDx::Utils::LogTimestamp For timestamp formatting
     class Line
 
+      # Formats a log entry as a traditional single-line log entry.
+      #
+      # Creates a log entry in the format: "SEVERITY_INITIAL, [TIMESTAMP #PID] SEVERITY -- CLASS: MESSAGE"
+      # where MESSAGE contains key=value pairs of task execution metadata.
+      #
+      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param time [Time] Timestamp when the log entry was created
+      # @param task [CMDx::Task] Task instance being logged
+      # @param message [Object] Log message or data to be included
+      #
+      # @return [String] Single-line formatted log entry with newline terminator
+      #
+      # @example Success log entry
+      #   formatter = CMDx::LogFormatters::Line.new
+      #   output = formatter.call("INFO", Time.now, task, "Order processed")
+      #   # => "I, [2022-07-17T18:43:15.000000 #1234] INFO -- ProcessOrderTask: state=complete status=success\n"
+      #
+      # @example Debug log entry with detailed metadata
+      #   output = formatter.call("DEBUG", Time.now, task, debug_info)
+      #   # => "D, [2022-07-17T18:43:15.000000 #1234] DEBUG -- ProcessOrderTask: index=0 chain_id=... metadata={...}\n"
+      #
+      # @example Error log entry with failure chain
+      #   output = formatter.call("ERROR", Time.now, task, error_details)
+      #   # => "E, [2022-07-17T18:43:15.000000 #1234] ERROR -- ProcessOrderTask: status=failed caused_failure={...} threw_failure={...}\n"
       def call(severity, time, task, message)
         t = Utils::LogTimestamp.call(time.utc)
         m = LoggerSerializer.call(severity, time, task, message)

data/lib/cmdx/log_formatters/logstash.rb

@@ -2,8 +2,72 @@
 
 module CMDx
   module LogFormatters
+    # Logstash log formatter for CMDx logging system.
+    #
+    # Formats log entries as JSON objects compatible with Logstash and the ELK stack
+    # (Elasticsearch, Logstash, Kibana). Includes Logstash-specific fields like
+    # @version and @timestamp for seamless integration with log aggregation pipelines.
+    #
+    # @example Basic usage with global logger configuration
+    #   CMDx.configure do |config|
+    #     config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Logstash.new)
+    #   end
+    #
+    # @example Task-specific formatter configuration for ELK stack
+    #   class ProcessOrderTask < CMDx::Task
+    #     task_settings!(log_format: CMDx::LogFormatters::Logstash.new)
+    #
+    #     def call
+    #       logger.info "Processing order #{order_id}"
+    #     end
+    #   end
+    #
+    # @example Sample Logstash JSON output
+    #   {"@version":"1","@timestamp":"2022-07-17T18:43:15.000000","severity":"INFO","pid":1234,"index":0,"chain_id":"018c2b95-b764-7615","type":"Task","class":"ProcessOrderTask","id":"018c2b95-b764-7615","tags":[],"state":"complete","status":"success","outcome":"success","metadata":{},"runtime":15,"origin":"CMDx"}
+    #
+    # @example Logstash configuration for CMDx logs
+    #   input {
+    #     file {
+    #       path => "/var/log/cmdx/*.log"
+    #       codec => "json"
+    #     }
+    #   }
+    #   filter {
+    #     if [origin] == "CMDx" {
+    #       # Process CMDx-specific fields
+    #     }
+    #   }
+    #
+    # @see CMDx::LogFormatters::Json For standard JSON formatting without Logstash fields
+    # @see CMDx::LoggerSerializer For details on serialized data structure
+    # @see https://www.elastic.co/guide/en/logstash/current/event-api.html Logstash Event API
     class Logstash
 
+      # Formats a log entry as a Logstash-compatible JSON string.
+      #
+      # Creates a JSON object with Logstash-specific metadata fields (@version, @timestamp)
+      # combined with task execution data, severity, and process information for
+      # seamless integration with ELK stack log processing pipelines.
+      #
+      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param time [Time] Timestamp when the log entry was created
+      # @param task [CMDx::Task] Task instance being logged
+      # @param message [Object] Log message or data to be included
+      #
+      # @return [String] Single-line Logstash-compatible JSON string with newline terminator
+      #
+      # @example Success log entry for Logstash
+      #   formatter = CMDx::LogFormatters::Logstash.new
+      #   output = formatter.call("INFO", Time.now, task, "Order processed")
+      #   # => {"@version":"1","@timestamp":"2022-07-17T18:43:15.000000","severity":"INFO",...}\n
+      #
+      # @example Error log entry with failure chain for ELK analysis
+      #   output = formatter.call("ERROR", Time.now, task, error_details)
+      #   # => {"@version":"1","severity":"ERROR","caused_failure":{...},"threw_failure":{...},...}\n
+      #
+      # @note The @version field is always set to "1" following Logstash conventions
+      # @note The @timestamp field uses ISO 8601 format for Elasticsearch compatibility
+      # @note All CMDx logs include an "origin" field set to "CMDx" for easy filtering
       def call(severity, time, task, message)
         m = LoggerSerializer.call(severity, time, task, message).merge!(
           severity:,

data/lib/cmdx/log_formatters/pretty_json.rb

@@ -2,8 +2,65 @@
 
 module CMDx
   module LogFormatters
+    # Pretty JSON log formatter for CMDx logging system.
+    #
+    # Formats log entries as human-readable, multi-line JSON objects with proper
+    # indentation and formatting. Contains the same structured data as the JSON
+    # formatter but optimized for development environments and manual inspection.
+    #
+    # @example Basic usage with global logger configuration
+    #   CMDx.configure do |config|
+    #     config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::PrettyJson.new)
+    #   end
+    #
+    # @example Task-specific formatter configuration
+    #   class ProcessOrderTask < CMDx::Task
+    #     task_settings!(log_format: CMDx::LogFormatters::PrettyJson.new)
+    #
+    #     def call
+    #       logger.info "Processing order #{order_id}"
+    #     end
+    #   end
+    #
+    # @example Sample pretty JSON output
+    #   {
+    #     "severity": "INFO",
+    #     "pid": 1234,
+    #     "timestamp": "2022-07-17T18:43:15.000000",
+    #     "index": 0,
+    #     "chain_id": "018c2b95-b764-7615",
+    #     "type": "Task",
+    #     "class": "ProcessOrderTask",
+    #     "state": "complete",
+    #     "status": "success",
+    #     "outcome": "success"
+    #   }
+    #
+    # @see CMDx::LogFormatters::Json For compact single-line JSON formatting
+    # @see CMDx::LoggerSerializer For details on serialized data structure
     class PrettyJson
 
+      # Formats a log entry as a pretty-printed JSON string.
+      #
+      # Combines task execution metadata with severity, process ID, and timestamp
+      # information to create a human-readable JSON log entry with proper
+      # indentation and formatting for development and debugging purposes.
+      #
+      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param time [Time] Timestamp when the log entry was created
+      # @param task [CMDx::Task] Task instance being logged
+      # @param message [Object] Log message or data to be included
+      #
+      # @return [String] Multi-line pretty-formatted JSON string with newline terminator
+      #
+      # @example Success log entry
+      #   formatter = CMDx::LogFormatters::PrettyJson.new
+      #   output = formatter.call("INFO", Time.now, task, "Order processed")
+      #   # => Multi-line formatted JSON output
+      #
+      # @example Error log entry with nested metadata
+      #   output = formatter.call("ERROR", Time.now, task, error_details)
+      #   # => Pretty-formatted JSON with nested failure information
       def call(severity, time, task, message)
         m = LoggerSerializer.call(severity, time, task, message).merge!(
           severity:,

data/lib/cmdx/log_formatters/pretty_key_value.rb

@@ -2,8 +2,59 @@
 
 module CMDx
   module LogFormatters
+    # Pretty key-value log formatter for CMDx logging system.
+    #
+    # Formats log entries as space-separated key=value pairs with ANSI color
+    # highlighting for improved readability in terminal environments. Provides
+    # the same structured data as KeyValue formatter with enhanced visual presentation.
+    #
+    # @example Basic usage with global logger configuration
+    #   CMDx.configure do |config|
+    #     config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::PrettyKeyValue.new)
+    #   end
+    #
+    # @example Task-specific formatter configuration
+    #   class ProcessOrderTask < CMDx::Task
+    #     task_settings!(log_format: CMDx::LogFormatters::PrettyKeyValue.new)
+    #
+    #     def call
+    #       logger.info "Processing order #{order_id}"
+    #     end
+    #   end
+    #
+    # @example Sample pretty key-value output (with ANSI colors)
+    #   severity=INFO pid=1234 timestamp=2022-07-17T18:43:15.000000 index=0 chain_id=018c2b95-b764-7615 type=Task class=ProcessOrderTask state=complete status=success outcome=success runtime=15
+    #   # Colors applied: severity levels, status values, class names, etc.
+    #
+    # @see CMDx::LogFormatters::KeyValue For plain key-value formatting without colors
+    # @see CMDx::LoggerAnsi For ANSI color definitions
+    # @see CMDx::LoggerSerializer For details on serialized data structure
     class PrettyKeyValue
 
+      # Formats a log entry as ANSI-colorized key=value pairs.
+      #
+      # Combines task execution metadata with severity, process ID, and timestamp
+      # information to create a visually enhanced key-value log entry with ANSI
+      # color codes for improved readability in terminal environments.
+      #
+      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param time [Time] Timestamp when the log entry was created
+      # @param task [CMDx::Task] Task instance being logged
+      # @param message [Object] Log message or data to be included
+      #
+      # @return [String] Single-line ANSI-colorized key=value formatted string with newline terminator
+      #
+      # @example Success log entry with colors
+      #   formatter = CMDx::LogFormatters::PrettyKeyValue.new
+      #   output = formatter.call("INFO", Time.now, task, "Order processed")
+      #   # => ANSI-colored "severity=INFO pid=1234 ... status=success\n"
+      #
+      # @example Error log entry with colored failure indicators
+      #   output = formatter.call("ERROR", Time.now, task, error_details)
+      #   # => ANSI-colored "severity=ERROR ... status=failed\n" (red highlighting)
+      #
+      # @note ANSI colors are automatically applied to key elements like severity levels,
+      #   status values, class names, and metadata for enhanced visual distinction
       def call(severity, time, task, message)
         m = LoggerSerializer.call(severity, time, task, message, ansi_colorize: true).merge!(
           severity:,

data/lib/cmdx/log_formatters/pretty_line.rb

@@ -2,8 +2,68 @@
 
 module CMDx
   module LogFormatters
+    # Pretty line log formatter for CMDx logging system.
+    #
+    # Formats log entries in a traditional single-line format enhanced with ANSI color
+    # highlighting for improved readability in terminal environments. Provides the same
+    # structured format as Line formatter with visual enhancements for severity levels,
+    # status indicators, and task information.
+    #
+    # @example Basic usage with global logger configuration
+    #   CMDx.configure do |config|
+    #     config.logger = Logger.new(STDOUT, formatter: CMDx::LogFormatters::PrettyLine.new)
+    #   end
+    #
+    # @example Task-specific formatter configuration
+    #   class ProcessOrderTask < CMDx::Task
+    #     task_settings!(log_format: CMDx::LogFormatters::PrettyLine.new)
+    #
+    #     def call
+    #       logger.info "Processing order #{order_id}"
+    #     end
+    #   end
+    #
+    # @example Sample pretty line output (with ANSI colors)
+    #   I, [2022-07-17T18:43:15.000000 #1234] INFO -- ProcessOrderTask: state=complete status=success outcome=success runtime=15
+    #   # Colors applied: INFO in blue, success in green, class name highlighted
+    #
+    # @example Error pretty line output with colored failure indicators
+    #   E, [2022-07-17T18:43:15.000000 #1234] ERROR -- ProcessOrderTask: state=interrupted status=failed outcome=failed
+    #   # Colors applied: ERROR in red, failed in red, class name highlighted
+    #
+    # @see CMDx::LogFormatters::Line For plain line formatting without colors
+    # @see CMDx::LoggerAnsi For ANSI color definitions
+    # @see CMDx::LoggerSerializer For details on serialized data structure
+    # @see CMDx::Utils::LogTimestamp For timestamp formatting
     class PrettyLine
 
+      # Formats a log entry as an ANSI-colorized single-line log entry.
+      #
+      # Creates a log entry in the format: "[COLORED_SEVERITY_INITIAL], [TIMESTAMP #PID] [COLORED_SEVERITY] -- CLASS: [COLORED_MESSAGE]"
+      # where colors are applied to severity indicators, status values, and other key elements.
+      #
+      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
+      # @param time [Time] Timestamp when the log entry was created
+      # @param task [CMDx::Task] Task instance being logged
+      # @param message [Object] Log message or data to be included
+      #
+      # @return [String] Single-line ANSI-colorized log entry with newline terminator
+      #
+      # @example Success log entry with colors
+      #   formatter = CMDx::LogFormatters::PrettyLine.new
+      #   output = formatter.call("INFO", Time.now, task, "Order processed")
+      #   # => ANSI-colored "I, [2022-07-17T18:43:15.000000 #1234] INFO -- ProcessOrderTask: state=complete status=success\n"
+      #
+      # @example Warning log entry with colored indicators
+      #   output = formatter.call("WARN", Time.now, task, "Order delayed")
+      #   # => ANSI-colored "W, [2022-07-17T18:43:15.000000 #1234] WARN -- ProcessOrderTask: state=interrupted status=skipped\n"
+      #
+      # @example Error log entry with red highlighting
+      #   output = formatter.call("ERROR", Time.now, task, error_details)
+      #   # => ANSI-colored "E, [2022-07-17T18:43:15.000000 #1234] ERROR -- ProcessOrderTask: status=failed caused_failure={...}\n"
+      #
+      # @note This is the default formatter for CMDx when no specific formatter is configured
+      # @note ANSI colors are automatically applied based on severity levels and status values
       def call(severity, time, task, message)
         i = LoggerAnsi.call(severity[0])
         s = LoggerAnsi.call(severity)

data/lib/cmdx/log_formatters/raw.rb

@@ -2,8 +2,62 @@
 
 module CMDx
   module LogFormatters
+    # Raw log formatter for CMDx logging system.
+    #
+    # Outputs only the raw message content without any additional formatting,
+    # timestamps, severity indicators, or task metadata. Provides the simplest
+    # possible log output containing just the inspected message content.
+    #
+    # @example Basic usage with global logger configuration
+    #   CMDx.configure do |config|
+    #     config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Raw.new)
+    #   end
+    #
+    # @example Task-specific formatter configuration
+    #   class ProcessOrderTask < CMDx::Task
+    #     task_settings!(log_format: CMDx::LogFormatters::Raw.new)
+    #
+    #     def call
+    #       logger.info "Processing order #{order_id}"
+    #       logger.debug({ order_details: order.attributes })
+    #     end
+    #   end
+    #
+    # @example Sample raw output
+    #   "Processing order 12345"
+    #   {:order_details=>{:id=>12345, :status=>"pending"}}
+    #
+    # @see CMDx::LogFormatters::Line For structured log formatting with metadata
+    # @see CMDx::LogFormatters::Json For JSON-formatted output
     class Raw
 
+      # Formats a log entry as raw message content only.
+      #
+      # Outputs only the message parameter using Ruby's inspect method,
+      # ignoring all other log context including severity, timestamp, and task information.
+      # Useful for debugging scenarios where only the message content is relevant.
+      #
+      # @param _severity [String] Log severity level (ignored)
+      # @param _time [Time] Timestamp when the log entry was created (ignored)
+      # @param _task [CMDx::Task] Task instance being logged (ignored)
+      # @param message [Object] Log message or data to be output
+      #
+      # @return [String] Raw message content with inspect formatting and newline terminator
+      #
+      # @example String message output
+      #   formatter = CMDx::LogFormatters::Raw.new
+      #   output = formatter.call("INFO", Time.now, task, "Order processed")
+      #   # => "\"Order processed\"\n"
+      #
+      # @example Hash message output
+      #   data = { order_id: 12345, status: "completed" }
+      #   output = formatter.call("DEBUG", Time.now, task, data)
+      #   # => "{:order_id=>12345, :status=>\"completed\"}\n"
+      #
+      # @example Array message output
+      #   items = ["item1", "item2", "item3"]
+      #   output = formatter.call("INFO", Time.now, task, items)
+      #   # => "[\"item1\", \"item2\", \"item3\"]\n"
       def call(_severity, _time, _task, message)
         message.inspect << "\n"
       end

data/lib/cmdx/logger.rb

@@ -1,10 +1,95 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Logger configuration and setup module for CMDx tasks.
+  #
+  # The Logger module provides centralized logger configuration and initialization
+  # for CMDx tasks. It handles logger setup, formatter assignment, log level
+  # configuration, and progname assignment based on task settings.
+  #
+  # @example Basic logger usage
+  #   class ProcessOrderTask < CMDx::Task
+  #     def call
+  #       logger.info "Processing order #{order_id}"
+  #       logger.debug { "Order details: #{order.inspect}" }
+  #     end
+  #   end
+  #
+  # @example Task-specific logger configuration
+  #   class ProcessOrderTask < CMDx::Task
+  #     task_settings!(
+  #       logger: Rails.logger,
+  #       log_formatter: CMDx::LogFormatters::Json.new,
+  #       log_level: Logger::INFO
+  #     )
+  #   end
+  #
+  # @example Global logger configuration
+  #   CMDx.configure do |config|
+  #     config.logger = Logger.new($stdout)
+  #     config.log_formatter = CMDx::LogFormatters::PrettyLine.new
+  #     config.log_level = Logger::WARN
+  #   end
+  #
+  # @example Custom logger with specific formatter
+  #   logger = Logger.new(STDOUT)
+  #   logger.formatter = CMDx::LogFormatters::Logstash.new
+  #   logger.level = Logger::DEBUG
+  #
+  #   class MyTask < CMDx::Task
+  #     task_settings!(logger: logger)
+  #   end
+  #
+  # @see CMDx::LogFormatters Log formatting options
+  # @see CMDx::ResultLogger Result-specific logging functionality
+  # @see CMDx::Task Task logging integration
   module Logger
 
     module_function
 
+    # Configures and returns a logger instance for a task.
+    #
+    # Retrieves the logger from task settings and applies additional configuration
+    # including formatter, log level, and progname if specified in task settings.
+    # Returns nil if no logger is configured.
+    #
+    # @param task [CMDx::Task] The task instance to configure logging for
+    # @return [::Logger, nil] Configured logger instance or nil if not set
+    #
+    # @example Basic logger retrieval
+    #   task = ProcessOrderTask.new
+    #   logger = Logger.call(task)
+    #   logger.info "Task started" if logger
+    #
+    # @example Logger with custom formatter
+    #   class MyTask < CMDx::Task
+    #     task_settings!(
+    #       logger: Logger.new(STDOUT),
+    #       log_formatter: CMDx::LogFormatters::Json.new
+    #     )
+    #   end
+    #
+    #   task = MyTask.new
+    #   logger = Logger.call(task)  # Logger with JSON formatter applied
+    #
+    # @example Logger with custom level
+    #   class MyTask < CMDx::Task
+    #     task_settings!(
+    #       logger: Logger.new(STDOUT),
+    #       log_level: Logger::DEBUG
+    #     )
+    #   end
+    #
+    #   task = MyTask.new
+    #   logger = Logger.call(task)  # Logger with DEBUG level applied
+    #
+    # @example No logger configured
+    #   class MyTask < CMDx::Task
+    #     # No logger setting
+    #   end
+    #
+    #   task = MyTask.new
+    #   logger = Logger.call(task)  # => nil
     def call(task)
       logger = task.task_setting(:logger)