legion-logging 1.5.2 → 1.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57e4eef04828ffa39cae5277822be4f2f5264d4010b05e724dbb179f0af5b771
-  data.tar.gz: 740663a6979cf6b5c5d90a12bc8c43e0fcd989b8d8253269d8a1f1bf9aff9d03
+  metadata.gz: f751e228eb4c00edae10784b3edf4176afb2f84ec7a8df1525a9c8432145c50f
+  data.tar.gz: 728db26335f6bffdcef54523760d9b8051615f0bee280ac01a897a3373b3403f
 SHA512:
-  metadata.gz: c590642e775a8f6ed7f87f9b4525049033c3e3f42635ea2e460e5b4ddd89e646a97d8744b80755a82db340ba6e813d8e95e3a8b27ffc17a63f8f3aee99e5b5a6
-  data.tar.gz: b812f47d57057a466655f22ae1f3922b6326a22fd40297ce602850069092efaf20ff40a6689ecbfe22a7498429bb3266df70ec40efb69617d11da045695155bd
+  metadata.gz: 3ba593790cf603ab542162e685c97450f7db2d18da76dd288981317ecf627b708a391e2b0f1eecfef43e3a308f0391a89a6bc636ab3216c6450a973d653b7e3e
+  data.tar.gz: 5c6fb87b90d197c3f70e0d69e1d5a3a13c55083aa1f8ebbd79676ff8926b12686e3fa9b2df91286ac2a216ace987863eb719b21df8693e3f0981768a2f70f748

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

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/lib/legion/logging/helper.rb

@@ -487,8 +487,18 @@ module Legion
         context_line = build_context_line(event)
         lines << "  #{context_line}" unless context_line.empty?
 
-        bt = exception.backtrace
-        bt.each { |frame| lines << "  #{frame}" } if bt&.any?
+        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")
       end

data/lib/legion/logging/methods.rb

@@ -102,17 +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?
-          lines = ["#{exception.class}: #{msg}"]
-          bt.each { |frame| lines << "  #{frame}" }
-          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
@@ -155,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.2'
+    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.2
+  version: 1.5.3
 platform: ruby
 authors:
 - Esity