legion-logging 1.5.1 → 1.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46129a3dbab733493155c3883562e0b8f867959f9749b0ead2c55096eaaa91f0
-  data.tar.gz: e5de12a36bdaa85ceca97cf8936312257ad607393b56fa3663ac0f827d850315
+  metadata.gz: f751e228eb4c00edae10784b3edf4176afb2f84ec7a8df1525a9c8432145c50f
+  data.tar.gz: 728db26335f6bffdcef54523760d9b8051615f0bee280ac01a897a3373b3403f
 SHA512:
-  metadata.gz: cbedead38cab56af14b780484b110f6f9a8bb6fbc28934478f203d02dea738208fe9fbc63e3c7bdb8d8cc90a33b3328ba39e5059cff85a0ab8be7e83a7068c7f
-  data.tar.gz: 337d49c5e424fc9cf487cec98295e4fd80a71da2882a5892c2b478d896cf05e52f6f10632719737df4072abbc555193c1475ae7b01d0e9f51d88ac5df3cc62fc
+  metadata.gz: 3ba593790cf603ab542162e685c97450f7db2d18da76dd288981317ecf627b708a391e2b0f1eecfef43e3a308f0391a89a6bc636ab3216c6450a973d653b7e3e
+  data.tar.gz: 5c6fb87b90d197c3f70e0d69e1d5a3a13c55083aa1f8ebbd79676ff8926b12686e3fa9b2df91286ac2a216ace987863eb719b21df8693e3f0981768a2f70f748

data/.gitignore

@@ -9,7 +9,8 @@
 /tmp/
 /legion/.idea/
 /.idea/
+*.gem
 *.key
 # rspec failure tracking
 .rspec_status
-legionio.key
+legionio.key

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Legion::Logging Changelog
 
+## [1.5.3] - 2026-05-13
+
+### Added
+- `backtrace_limit:` kwarg on `log_exception` and `handle_exception` (nil=full, 0=suppress, N=cap at N frames)
+- `backtrace_limit` key in `Legion::Logging::Settings.default` (defaults to nil — full backtraces)
+- Settings-driven default reads from `Legion::Settings[:logging][:backtrace_limit]` when no explicit kwarg is passed
+
+## [1.5.2] - 2026-04-27
+
+### Changed
+- Exception stdout/file log lines now include the full backtrace instead of truncating after 10 frames with a `... N more` suffix.
+
 ## [1.5.1] - 2026-04-08
 
 ### Added

data/CLAUDE.md

@@ -1,92 +1,46 @@
-# legion-logging: Logging Framework for LegionIO
+# legion-logging
 
-**Repository Level 3 Documentation**
-- **Parent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
-
-## Purpose
-
-Ruby logging class for the LegionIO framework. Provides colorized console output via Rainbow, structured JSON logging (`format: :json`), and a consistent logging interface across all Legion gems and extensions.
+Structured logging framework for LegionIO. Provides colorized console output (Rainbow), structured JSON logging, and a consistent interface across all Legion gems and extensions.
 
 **GitHub**: https://github.com/LegionIO/legion-logging
-**Version**: 1.5.0
-**License**: Apache-2.0
+**Version**: 1.5.3
 
 ## Architecture
 
 ```
 Legion::Logging (singleton module)
-├── Methods           # Log level methods: debug, info, warn, error, fatal, unknown; log_exception helper
-├── Builder           # Output destination (stdout/file), log level, formatter, async: keyword
-├── AsyncWriter       # Non-blocking SizedQueue-backed writer thread; fatal calls bypass queue
-├── Hooks             # Callback registry for fatal/error/warn events (on_fatal, on_error, on_warn)
-├── EventBuilder      # Structured event payload builder (caller, exception, lex, gem metadata); fingerprint for dedup
-├── Helper            # Injectable log mixin for LEX extensions (derives logger tags from segments/class)
-├── Logger            # Core logger configuration and setup
-├── MultiIO           # Write to multiple destinations simultaneously
-├── TaggedLogger      # Logger wrapper that prepends structured tags to each message
-├── CategoryRegistry  # Registry of named log categories with description and expected_fields
-├── MethodTracer      # Tracing module for instrumenting method calls (call/return, formatted args)
-├── SIEMExporter      # PHI-redacting SIEM export (Splunk HEC, ELK/OpenSearch)
-├── Shipper           # Buffered log event forwarding; sub-transports: FileTransport, HttpTransport
-├── Redactor          # PII/PHI + secret pattern redaction; opt-in via logging.redaction.enabled
-└── Version           # VERSION constant
-
-# Module-level writers (pluggable lambda slots replacing old Hooks for AMQP forwarding)
-Legion::Logging.log_writer       # -> lambda(->(event, routing_key:) {})
-Legion::Logging.exception_writer # -> lambda(->(event, routing_key:, headers:, properties:) {})
+├── Methods           # debug, info, warn, error, fatal, unknown; log_exception
+├── Builder           # Output destination, log level, formatter, async: keyword
+├── AsyncWriter       # Non-blocking SizedQueue-backed writer thread
+├── Hooks             # Callback registry for fatal/error/warn events
+├── EventBuilder      # Structured event payload + fingerprint for dedup
+├── Helper            # Injectable log mixin for LEX extensions
+├── TaggedLogger      # Prepends structured tags to each message
+├── CategoryRegistry  # Named log categories with expected_fields
+├── SIEMExporter      # PHI-redacting SIEM export (Splunk HEC, ELK)
+├── Shipper           # Buffered forwarding (FileTransport, HttpTransport)
+├── Redactor          # PII/PHI + secret pattern redaction (opt-in)
+└── MultiIO           # Write to multiple destinations simultaneously
+
+# Module-level writer lambdas (pluggable forwarding slots)
+Legion::Logging.log_writer       # ->(event, routing_key:) {}
+Legion::Logging.exception_writer # ->(event, routing_key:, headers:, properties:) {}
 ```
 
-### Key Design Patterns
-
-- **Singleton Module**: `Legion::Logging` uses `class << self` — called directly: `Legion::Logging.info("msg")`
-- **Rainbow Colorization**: Console output uses Rainbow gem for colored terminal output. Color auto-disabled in JSON format and when writing to a log file.
-- **Setup Method**: `Legion::Logging.setup(level:, format:, async:, **options)` configures output, level, format, and async mode. Increments `configuration_generation` on each call.
-- **Async by Default**: `setup` enables async logging — calls return immediately. Fatal calls always bypass the queue. `stop_async_writer` flushes and stops on shutdown. Buffer size configurable via `Legion::Settings[:logging][:async][:buffer_size]` (default 10,000). Back-pressure: callers block when buffer is full.
-- **Structured JSON**: `format: :json` in settings outputs machine-parseable JSON log lines (disables color)
-- **Shared Interface**: Same method signature (`info`, `warn`, `error`, etc.) across all Legion components
-- **MultiIO**: Splits writes to stdout and a log file simultaneously (used by Builder when `log_file` is set)
-- **SIEMExporter**: PHI redaction (SSN, phone, MRN, DOB patterns), `export_to_splunk` (HEC), `format_for_elk`
-- **Hook Callbacks**: `on_fatal`, `on_error`, `on_warn` register procs called after each log at those levels. Hooks are gated by `enable_hooks!`/`disable_hooks!`. Hook failures are silently rescued. Hooks fire on the async writer thread; event context captured on caller thread.
-- **EventBuilder**: Builds structured event hashes from log context (caller location, exception info, lex identity, gem metadata). All from in-memory data, zero IO. `fingerprint` produces MD5 for dedup in log aggregation.
-- **Helper mixin**: `Legion::Logging::Helper` is injectable into LEX extensions. Derives logger tags from `segments`, `lex_filename`, or class name. Passes through `settings[:logger]` config when available.
-- **Writer Lambdas**: `log_writer` and `exception_writer` are module-level lambda slots for forwarding to external systems (AMQP, etc.). Default implementations are no-ops. Set via `Legion::Logging.log_writer = lambda`.
-- **CategoryRegistry**: Named log categories with description and expected_fields. Register via `Legion::Logging.register_category`. Used for structured log validation.
-- **Redactor**: Opt-in PII/PHI redaction (`logging.redaction.enabled: true`). Guards against Settings recursive init via `@loader` ivar check. Patterns: SSN, phone, MRN, DOB, Vault tokens, JWTs, bearer tokens, lease IDs.
+## Key Patterns
 
-## Dependencies
-
-| Gem | Purpose |
-|-----|---------|
-| `rainbow` (~> 3) | Terminal colorization |
-
-## File Map
-
-| Path | Purpose |
-|------|---------|
-| `lib/legion/logging.rb` | Module entry point |
-| `lib/legion/logging/methods.rb` | Log level methods |
-| `lib/legion/logging/builder.rb` | Output config and formatter (async: keyword) |
-| `lib/legion/logging/async_writer.rb` | Non-blocking SizedQueue-backed writer thread with back-pressure |
-| `lib/legion/logging/helper.rb` | Injectable log mixin for LEX extensions |
-| `lib/legion/logging/logger.rb` | Core logger setup |
-| `lib/legion/logging/multi_io.rb` | Multi-output IO (write to multiple destinations simultaneously) |
-| `lib/legion/logging/siem_exporter.rb` | PHI-redacting SIEM export helpers (Splunk HEC, ELK format) |
-| `lib/legion/logging/hooks.rb` | Callback registry (fatal/error/warn hook arrays, enable/disable/clear) |
-| `lib/legion/logging/event_builder.rb` | Structured event payload builder; `fingerprint` for MD5 dedup |
-| `lib/legion/logging/tagged_logger.rb` | Logger wrapper that prepends structured tags to each message |
-| `lib/legion/logging/category_registry.rb` | Named log category registration and lookup |
-| `lib/legion/logging/method_tracer.rb` | Method call tracing instrumentation (call/return, formatted args) |
-| `lib/legion/logging/shipper.rb` | Buffered log event forwarding to external systems |
-| `lib/legion/logging/shipper/file_transport.rb` | File-based log shipper transport |
-| `lib/legion/logging/shipper/http_transport.rb` | HTTP-based log shipper transport |
-| `lib/legion/logging/siem_exporter.rb` | PHI-redacting SIEM export (Splunk HEC, ELK format) |
-| `lib/legion/logging/redactor.rb` | PII/PHI + secret pattern redaction (opt-in) |
-| `lib/legion/logging/version.rb` | VERSION constant |
+- **Singleton module** — `class << self`; called directly: `Legion::Logging.info("msg")`
+- **Async by default** — `setup` enables async logging; fatal bypasses queue. Buffer size via `Settings[:logging][:async][:buffer_size]` (default 10,000). Back-pressure blocks callers when full.
+- **Structured JSON** — `format: :json` outputs machine-parseable JSON lines (disables color)
+- **Helper mixin** — `Legion::Logging::Helper` injects into LEX extensions; derives tags from `segments`, `lex_filename`, or class name
+- **Writer lambdas** — `log_writer` and `exception_writer` are module-level lambda slots for forwarding to external systems (AMQP, etc.). Default no-ops.
+- **Redactor** — Opt-in (`logging.redaction.enabled: true`). Patterns: SSN, phone, MRN, DOB, Vault tokens, JWTs, bearer tokens, lease IDs. Guards against Settings recursive init.
+- **Hook callbacks** — `on_fatal`, `on_error`, `on_warn` register procs; gated by `enable_hooks!`/`disable_hooks!`; fire on async writer thread
+- **EventBuilder** — Structured event hashes from log context (caller, exception, lex identity). `fingerprint` produces MD5 for dedup.
 
 ## Role in LegionIO
 
-**Foundational gem** - used by `legion-cache`, `legion-data`, and `LegionIO` as a direct dependency. First module initialized during `Legion::Service` startup.
+Foundational gem — dependency of `legion-cache`, `legion-data`, and `LegionIO`. First module initialized during `Legion::Service` startup.
 
 ---
-
 **Maintained By**: Matthew Iverson (@Esity)

data/README.md

@@ -2,7 +2,7 @@
 
 Logging module for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Provides colorized console output via Rainbow, structured JSON logging, multi-output IO, and a consistent logging interface across all Legion gems and extensions.
 
-**Version**: 1.5.0
+**Version**: 1.5.2
 
 ## Installation
 
@@ -96,23 +96,46 @@ end
 
 ### Exception Logging
 
-`log_exception` provides a single call for complete structured exception events with component context:
+`log_exception` provides a single call for complete exception logging with component context. It writes a human-readable exception line through the configured logger and publishes a structured exception event when an `exception_writer` is configured.
 
 ```ruby
-Legion::Logging.log_exception(exception,
-  handled: true,
-  component_type: :runner,
-  lex: 'my_extension',
-  task_id: 'abc-123')
+begin
+  runner.call
+rescue StandardError => e
+  Legion::Logging.log_exception(
+    e,
+    handled: true,
+    component_type: :runner,
+    lex: 'my_extension',
+    task_id: 'abc-123'
+  )
+end
 ```
 
+The synchronous log line includes the full Ruby backtrace. Legion does not truncate it to a fixed frame count or replace the tail with `... N more`, because the missing frames are often the useful part of production failures.
+
+Structured exception events include:
+
+- exception class and message
+- full backtrace array
+- caller file, line, and function where available
+- log level and handled/unhandled status
+- component type, lex name, gem name, version, and source path metadata
+- task and thread context
+- stable error fingerprint for deduplication
+
 ### Writer Lambdas
 
 `log_writer` and `exception_writer` are pluggable lambda slots that replace the old Hooks system. Assign them to forward events to external systems:
 
 ```ruby
-Legion::Logging.exception_writer = ->(payload, routing_key:, headers:, properties:) { publish_to_amqp(payload) }
-Legion::Logging.log_writer = ->(context, routing_key:) { publish_log(context) }
+Legion::Logging.exception_writer = lambda do |payload, routing_key:, headers:, properties:|
+  publish_to_amqp(payload, routing_key:, headers:, properties:)
+end
+
+Legion::Logging.log_writer = lambda do |context, routing_key:|
+  publish_log(context, routing_key:)
+end
 ```
 
 ### EventBuilder
@@ -121,7 +144,9 @@ Legion::Logging.log_writer = ->(context, routing_key:) { publish_log(context) }
 
 ### Redactor
 
-`Legion::Logging::Redactor` redacts PII/PHI patterns (SSN, phone, MRN, DOB) plus Vault tokens, JWTs, bearer tokens, and lease IDs from log messages. Redaction is opt-in: load the module (for example via `require 'legion/logging/redactor'`) and enable it with `logging.redaction.enabled: true`. When loaded and enabled, it is wired into all log methods in the write path.
+`Legion::Logging::Redactor` redacts PII/PHI patterns (SSN, email, phone, MRN, DOB, credit card) plus Vault tokens, JWTs, bearer tokens, `vault://` URIs, `lease://` URIs, and lease IDs from log messages. Redaction is opt-in for text log lines: load the module (for example via `require 'legion/logging/redactor'`) and enable it with `logging.redaction.enabled: true`. When loaded and enabled, it is wired into all log methods in the write path.
+
+Structured exception events are redacted before publishing when the redactor is loaded. This includes event identity fields such as `user`, so email-shaped local usernames are not forwarded raw.
 
 ## Requirements
 

data/lib/legion/logging/helper.rb

@@ -32,7 +32,6 @@ module Legion
         'middleware' => :middleware
       }.freeze
 
-      EXCEPTION_BACKTRACE_LIMIT = 10
       EXCEPTION_PRIORITY = { warn: 0, error: 5, fatal: 9 }.freeze
       EXCEPTION_COLORS = {
         fatal:   :darkred,
@@ -488,11 +487,17 @@ module Legion
         context_line = build_context_line(event)
         lines << "  #{context_line}" unless context_line.empty?
 
-        bt = exception.backtrace
-        if bt&.any?
-          bt.first(EXCEPTION_BACKTRACE_LIMIT).each { |frame| lines << "  #{frame}" }
-          remaining = bt.length - EXCEPTION_BACKTRACE_LIMIT
-          lines << "  ... #{remaining} more" if remaining.positive?
+        max_frames = if event[:backtrace_limit].nil?
+                       defined?(Legion::Settings) ? Legion::Settings[:logging][:backtrace_limit] : nil
+                     else
+                       event[:backtrace_limit]
+                     end
+        unless max_frames&.zero?
+          bt = exception.backtrace
+          if bt&.any?
+            frames = max_frames ? bt.first(max_frames) : bt
+            frames.each { |frame| lines << "  #{frame}" }
+          end
         end
 
         lines.join("\n")

data/lib/legion/logging/methods.rb

@@ -102,20 +102,12 @@ module Legion
       def log_exception(exception, level: :error, lex: nil, component_type: nil,
                         gem_name: nil, lex_version: nil, gem_path: nil,
                         source_code_uri: nil, handled: false, payload_summary: nil,
-                        task_id: nil, **extra)
+                        task_id: nil, backtrace_limit: nil, **extra)
         level = level.to_sym if level.respond_to?(:to_sym)
         # 1. Log human-readable line + backtrace to stdout/file (bypass writer callbacks)
         msg = exception.respond_to?(:message) ? exception.message : exception.to_s
         msg = maybe_redact(msg)
-        bt = Array(exception.backtrace)
-        if bt.any?
-          limit = defined?(Legion::Logging::Helper::EXCEPTION_BACKTRACE_LIMIT) ? Legion::Logging::Helper::EXCEPTION_BACKTRACE_LIMIT : 10
-          lines = ["#{exception.class}: #{msg}"]
-          bt.first(limit).each { |frame| lines << "  #{frame}" }
-          remaining = bt.length - limit
-          lines << "  ... #{remaining} more" if remaining.positive?
-          msg = lines.join("\n")
-        end
+        msg = build_exception_log_message(exception, msg, backtrace_limit)
         log.public_send(level, msg) if respond_to?(:log) && log.respond_to?(level)
 
         # 2. Build rich exception event
@@ -158,6 +150,30 @@ module Legion
 
       private
 
+      def resolve_backtrace_limit(explicit_limit)
+        return explicit_limit unless explicit_limit.nil?
+        return nil unless defined?(Legion::Settings)
+
+        Legion::Settings[:logging][:backtrace_limit]
+      end
+
+      def build_exception_log_message(exception, msg, backtrace_limit)
+        max_frames = resolve_backtrace_limit(backtrace_limit)
+        bt = collect_backtrace_frames(exception, max_frames)
+        return msg unless bt.any?
+
+        lines = ["#{exception.class}: #{msg}"]
+        bt.each { |frame| lines << "  #{frame}" }
+        lines.join("\n")
+      end
+
+      def collect_backtrace_frames(exception, max_frames)
+        return [] if max_frames&.zero?
+
+        frames = Array(exception.backtrace)
+        max_frames ? frames.first(max_frames) : frames
+      end
+
       def maybe_redact(message)
         return message unless message.is_a?(String)
         return message unless redaction_enabled?

data/lib/legion/logging/settings.rb

@@ -5,10 +5,11 @@ module Legion
     module Settings
       def self.default
         {
-          level:      :info,
-          trace:      true,
-          trace_size: 4,
-          extended:   true
+          level:           :info,
+          trace:           true,
+          trace_size:      4,
+          extended:        true,
+          backtrace_limit: nil
         }
       end
     end

data/lib/legion/logging/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Logging
-    VERSION = '1.5.1'
+    VERSION = '1.5.3'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-logging
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.5.3
 platform: ruby
 authors:
 - Esity