cmdx 1.0.1 → 1.1.1

data/docs/logging.md

@@ -6,96 +6,109 @@ CMDx provides comprehensive automatic logging for task execution with structured
 - [TLDR](#tldr)
 - [Log Formatters](#log-formatters)
   - [Standard Formatters](#standard-formatters)
-  - [Stylized Formatters (ANSI Colors)](#stylized-formatters-ansi-colors)
+  - [Stylized Formatters](#stylized-formatters)
 - [Sample Output](#sample-output)
-  - [Success Result](#success-result)
-  - [Skipped Result](#skipped-result)
-  - [Failed Result](#failed-result)
-  - [Failure Chain (Workflow Workflows)](#failure-chain-workflow-workflows)
 - [Configuration](#configuration)
   - [Global Configuration](#global-configuration)
   - [Task-Specific Configuration](#task-specific-configuration)
-  - [Environment-Specific Configuration](#environment-specific-configuration)
 - [Severity Mapping](#severity-mapping)
 - [Manual Logging](#manual-logging)
-- [Advanced Formatter Usage](#advanced-formatter-usage)
-  - [Custom Formatter](#custom-formatter)
+- [Error Handling](#error-handling)
+- [Advanced Usage](#advanced-usage)
+  - [Custom Formatters](#custom-formatters)
   - [Multi-Destination Logging](#multi-destination-logging)
 - [Log Data Structure](#log-data-structure)
 
 ## TLDR
 
-- **Automatic logging** - All task results logged after completion with structured data
-- **8 formatters** - Standard (Line, Json, KeyValue, Logstash, Raw) and Stylized (Pretty variants)
-- **Configuration** - Global via `CMDx.configure` or task-specific via `task_settings!`
-- **Severity mapping** - Success=INFO, Skipped=WARN, Failed=ERROR
-- **Rich metadata** - Includes runtime, chain_id, status, context, and failure chains
-- **Manual logging** - Access `logger` within tasks for custom messages
+```ruby
+# Automatic logging - no setup required
+class ProcessOrderTask < CMDx::Task
+  def call
+    # Task execution automatically logged with metadata
+  end
+end
 
-## Log Formatters
+# Custom formatter
+cmd_settings!(log_formatter: CMDx::LogFormatters::Json.new)
 
-CMDx provides 8 built-in log formatters organized into standard and stylized categories:
+# Manual logging within tasks
+logger.info "Processing order", order_id: context.order_id
 
-### Standard Formatters
-- **`Line`** - Traditional single-line format similar to Ruby's Logger
-- **`Json`** - Compact single-line JSON for structured logging systems
-- **`KeyValue`** - Space-separated key=value pairs for easy parsing
-- **`Logstash`** - ELK stack compatible JSON with @version and @timestamp fields
-- **`Raw`** - Minimal output containing only the message content
+# Global configuration
+CMDx.configure do |config|
+  config.logger = Logger.new("log/cmdx.log")
+  config.log_formatter = CMDx::LogFormatters::Json.new
+end
+```
 
-### Stylized Formatters (ANSI Colors)
+## Log Formatters
 
 > [!NOTE]
-> Stylized formatters include ANSI color codes for terminal readability and are best suited for development environments.
+> All formatters automatically include execution metadata. Choose based on your environment: stylized for development, standard for production.
 
-- **`PrettyLine`** - Colorized line format (default)
-- **`PrettyJson`** - Human-readable multi-line JSON with syntax highlighting
-- **`PrettyKeyValue`** - Colorized key=value pairs for terminal readability
+### Standard Formatters
 
-## Sample Output
+| Formatter | Use Case | Output Style |
+|-----------|----------|--------------|
+| `Line` | Traditional logging | Single-line format |
+| `Json` | Structured systems | Compact JSON |
+| `KeyValue` | Log parsing | `key=value` pairs |
+| `Logstash` | ELK stack | JSON with @version/@timestamp |
+| `Raw` | Minimal output | Message content only |
 
-### Success Result
-```txt
-I, [2022-07-17T18:43:15.000000 #3784] INFO -- CreateOrderTask: index=0 chain_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=CreateOrderTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=complete status=success outcome=success metadata={order_id: 123, confirmation: "ABC123"} runtime=0.45 origin=CMDx
-```
+### Stylized Formatters
 
-### Skipped Result
-```txt
-W, [2022-07-17T18:43:15.000000 #3784] WARN -- ValidatePaymentTask: index=0 chain_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=ValidatePaymentTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=skipped outcome=skipped metadata={reason: "Order already processed"} runtime=0.02 origin=CMDx
-```
+> [!TIP]
+> Stylized formatters include ANSI color codes for better terminal readability in development environments.
 
-### Failed Result
-```txt
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- ProcessPaymentTask: index=0 chain_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=ProcessPaymentTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=failed metadata={reason: "Payment declined", error_code: "INSUFFICIENT_FUNDS"} runtime=0.15 origin=CMDx
-```
+| Formatter | Description |
+|-----------|-------------|
+| `PrettyLine` | Colorized line format (default) |
+| `PrettyJson` | Multi-line JSON with syntax highlighting |
+| `PrettyKeyValue` | Colorized key=value pairs |
 
-### Failure Chain (Workflow Workflows)
-```txt
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- OrderCreationWorkflow: index=0 chain_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Workflow class=OrderCreationWorkflow id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=interrupted metadata={} runtime=0.75 caused_failure={index: 2, class: "ValidatePaymentTask", status: "failed"} threw_failure={index: 1, class: "ProcessPaymentTask", status: "failed"} origin=CMDx
+## Sample Output
+
+```ruby
+# Success (INFO level)
+I, [2022-07-17T18:43:15.000000 #3784] INFO -- CreateOrderTask:
+index=0 chain_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task
+class=CreateOrderTask status=success metadata={order_id: 123} runtime=0.45
+
+# Skipped (WARN level)
+W, [2022-07-17T18:43:15.000000 #3784] WARN -- ValidatePaymentTask:
+index=1 status=skipped metadata={reason: "Order already processed"} runtime=0.02
+
+# Failed (ERROR level)
+E, [2022-07-17T18:43:15.000000 #3784] ERROR -- ProcessPaymentTask:
+index=2 status=failed metadata={error_code: "INSUFFICIENT_FUNDS"} runtime=0.15
+
+# Workflow failure chain
+E, [2022-07-17T18:43:15.000000 #3784] ERROR -- OrderWorkflow:
+caused_failure={index: 2, class: "ProcessPaymentTask", status: "failed"}
+threw_failure={index: 1, class: "ValidatePaymentTask", status: "failed"}
 ```
 
 ## Configuration
 
 ### Global Configuration
 
-Configure logging globally in your CMDx initializer:
-
 ```ruby
 CMDx.configure do |config|
-  config.logger = Logger.new("log/cmdx.log", formatter: CMDx::LogFormatters::Json.new)
-  config.logger.level = Logger::INFO
+  config.logger = Logger.new("log/cmdx.log")
+  config.log_formatter = CMDx::LogFormatters::Json.new
+  config.log_level = Logger::INFO
 end
 ```
 
 ### Task-Specific Configuration
 
-Override logging settings for individual tasks:
-
 ```ruby
 class SendEmailTask < CMDx::Task
-  task_settings!(
+  cmd_settings!(
     logger: Rails.logger,
-    log_formatter: CMDx::LogFormatters::Json.new,
+    log_formatter: CMDx::LogFormatters::Logstash.new,
     log_level: Logger::WARN
   )
 
@@ -104,12 +117,11 @@ class SendEmailTask < CMDx::Task
   end
 end
 
-# Base class with shared logging configuration
+# Base class configuration
 class ApplicationTask < CMDx::Task
-  task_settings!(
+  cmd_settings!(
     logger: Logger.new("log/tasks.log"),
-    log_formatter: CMDx::LogFormatters::Logstash.new,
-    log_level: Logger::INFO
+    log_formatter: CMDx::LogFormatters::Json.new
   )
 end
 ```
@@ -117,55 +129,99 @@ end
 ## Severity Mapping
 
 > [!IMPORTANT]
-> CMDx automatically maps result statuses to appropriate log severity levels. Manual log level overrides are not recommended.
+> CMDx automatically maps result statuses to log severity levels. Manual overrides are not recommended as they break monitoring conventions.
 
-| Result Status | Log Level | Use Case |
-| ------------- | --------- | -------- |
-| `success`     | `INFO`    | Normal successful completion |
-| `skipped`     | `WARN`    | Intentional skip (business logic) |
-| `failed`      | `ERROR`   | Task failure or exception |
+| Status | Log Level | When Used |
+|--------|-----------|-----------|
+| `success` | `INFO` | Normal completion |
+| `skipped` | `WARN` | Intentional skip via business logic |
+| `failed` | `ERROR` | Task failure or exception |
 
 ## Manual Logging
 
-Access the configured logger within tasks for custom log messages:
-
 ```ruby
 class ProcessOrderTask < CMDx::Task
   def call
+    # Structured logging with metadata
     logger.info "Starting order processing", order_id: context.order_id
 
     # Performance-optimized debug logging
     logger.debug { "Order details: #{context.order.inspect}" }
 
-    # Structured logging
-    logger.info "Payment processed", {
-      order_id: context.order_id,
-      amount: context.order.total,
-      payment_method: context.payment_method
-    }
-
-    # Exception handling with logging
+    # Exception context
     begin
       validate_inventory
     rescue StandardError => e
-      logger.error "Inventory validation failed: #{e.message}", {
+      logger.error "Inventory validation failed", {
         exception: e.class.name,
-        order_id: context.order_id
+        order_id: context.order_id,
+        message: e.message
       }
       raise
     end
+
+    # Success with metadata
+    logger.info "Order processed successfully", {
+      order_id: context.order_id,
+      amount: context.order.total
+    }
   end
 end
 ```
 
-## Advanced Formatter Usage
+## Error Handling
 
-### Custom Formatter
+> [!WARNING]
+> Logger configuration errors are handled gracefully, falling back to STDOUT with PrettyLine formatter to ensure execution continuity.
 
-Create custom formatters for specific output requirements:
+### Configuration Error Recovery
 
 ```ruby
-class SlackLogFormatter
+# Invalid logger configuration
+CMDx.configure do |config|
+  config.logger = Logger.new("/invalid/path/cmdx.log")  # Permission denied
+end
+
+# CMDx automatically falls back to:
+# Logger.new(STDOUT, formatter: CMDx::LogFormatters::PrettyLine.new)
+```
+
+### Formatter Error Handling
+
+```ruby
+class BrokenFormatter
+  def call(severity, time, task, message)
+    raise StandardError, "Formatter error"
+  end
+end
+
+class TestTask < CMDx::Task
+  cmd_settings!(log_formatter: BrokenFormatter.new)
+
+  def call
+    # Execution continues with fallback formatter
+    # Error logged to STDERR for debugging
+  end
+end
+```
+
+### Log Level Validation
+
+```ruby
+# Invalid log levels default to INFO
+CMDx.configure do |config|
+  config.log_level = "INVALID"  # → Logger::INFO
+end
+
+# Valid levels: DEBUG, INFO, WARN, ERROR, FATAL
+```
+
+## Advanced Usage
+
+### Custom Formatters
+
+```ruby
+class AlertFormatter
   def call(severity, time, task, message)
     emoji = case severity
             when 'INFO' then '✅'
@@ -174,21 +230,23 @@ class SlackLogFormatter
             else '📝'
             end
 
-    "#{emoji} #{task.class.name}: #{message}\n"
+    "[#{time.strftime('%H:%M:%S')}] #{emoji} #{task.class.name}: #{message}\n"
   end
 end
 
-class SendNotificationTask < CMDx::Task
-  task_settings!(
-    logger: Logger.new("log/notifications.log", formatter: SlackLogFormatter.new)
-  )
+class NotificationTask < CMDx::Task
+  cmd_settings!(log_formatter: AlertFormatter.new)
+
+  def call
+    # Uses custom emoji-based formatting
+  end
 end
 ```
 
 ### Multi-Destination Logging
 
 > [!TIP]
-> Use multi-destination logging to send output to both console and files simultaneously during development.
+> Combine multiple loggers to output to both console and files simultaneously during development.
 
 ```ruby
 class MultiLogger
@@ -197,21 +255,13 @@ class MultiLogger
   end
 
   %w[debug info warn error fatal].each do |level|
-    define_method(level) do |message = nil, &block|
-      @loggers.each { |logger| logger.send(level, message, &block) }
+    define_method(level) do |message = nil, **metadata, &block|
+      @loggers.each { |logger| logger.send(level, message, **metadata, &block) }
     end
   end
-
-  def formatter=(formatter)
-    @loggers.each { |logger| logger.formatter = formatter }
-  end
-
-  def level=(level)
-    @loggers.each { |logger| logger.level = level }
-  end
 end
 
-# Usage
+# Configuration
 CMDx.configure do |config|
   config.logger = MultiLogger.new(
     Logger.new(STDOUT, formatter: CMDx::LogFormatters::PrettyLine.new),
@@ -222,32 +272,45 @@ end
 
 ## Log Data Structure
 
-CMDx logs contain comprehensive execution metadata:
-
-#### Standard Fields
-- `severity` - Log level (INFO, WARN, ERROR)
-- `pid` - Process ID for multi-process debugging
-- `timestamp` - ISO 8601 formatted execution time
-- `origin` - Always "CMDx" for filtering
-
-#### Task Identification
-- `index` - Position in execution sequence
-- `chain_id` - Unique identifier for execution chain
-- `type` - Task or Workflow
-- `class` - Task class name
-- `id` - Unique task instance identifier
-- `tags` - Custom tags for categorization
-
-#### Execution Information
-- `state` - Execution lifecycle state (initialized, executing, complete, interrupted)
-- `status` - Business logic outcome (success, skipped, failed)
-- `outcome` - Final result classification
-- `metadata` - Custom data from skip!/fail! calls
-- `runtime` - Execution time in seconds
-
-#### Failure Chain (Complex Workflows)
-- `caused_failure` - Original failing task information
-- `threw_failure` - Task that propagated the failure
+> [!NOTE]
+> All log entries include comprehensive execution metadata for debugging and monitoring. Field availability depends on the execution context.
+
+### Core Fields
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `severity` | Log level | `INFO`, `WARN`, `ERROR` |
+| `timestamp` | ISO 8601 execution time | `2022-07-17T18:43:15.000000` |
+| `pid` | Process ID | `3784` |
+| `origin` | Source identifier | `CMDx` |
+
+### Task Information
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `index` | Execution sequence position | `0`, `1`, `2` |
+| `chain_id` | Unique execution chain ID | `018c2b95-b764-7615...` |
+| `type` | Execution unit type | `Task`, `Workflow` |
+| `class` | Task class name | `ProcessOrderTask` |
+| `id` | Unique task instance ID | `018c2b95-b764-7615...` |
+| `tags` | Custom categorization | `["priority", "payment"]` |
+
+### Execution Data
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `state` | Lifecycle state | `complete`, `interrupted` |
+| `status` | Business outcome | `success`, `skipped`, `failed` |
+| `outcome` | Final classification | `success`, `interrupted` |
+| `metadata` | Custom task data | `{order_id: 123, amount: 99.99}` |
+| `runtime` | Execution time (seconds) | `0.45` |
+
+### Failure Chain (Workflows)
+
+| Field | Description |
+|-------|-------------|
+| `caused_failure` | Original failing task details |
+| `threw_failure` | Task that propagated the failure |
 
 ---