legion-logging 1.4.3 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 707d2460ca4e016ca62cc8ef83bf2d646819439ed67ef5549a164518ba2d3bf5
-  data.tar.gz: a013c59d975f901f25b153cbbfe4ed288dbedb262098627aed6d71baeb70031a
+  metadata.gz: 46129a3dbab733493155c3883562e0b8f867959f9749b0ead2c55096eaaa91f0
+  data.tar.gz: e5de12a36bdaa85ceca97cf8936312257ad607393b56fa3663ac0f827d850315
 SHA512:
-  metadata.gz: f5f3d87c609bca88c501e32d241fabc796e48b8aae8912fed39ac3615e0565f2a7d4672b66f12b0fdf606c6d3e0b40abb2b04b9b38d554edca4e9fa4b063a40a
-  data.tar.gz: 741697e72078cb1cbede684a8729d8a9a0b79c25a8beb4ed465aa53ae89711e11f482b9e93f434f51dae0778dfdf3bf49855282e80a7df17f98054d980d3e037
+  metadata.gz: cbedead38cab56af14b780484b110f6f9a8bb6fbc28934478f203d02dea738208fe9fbc63e3c7bdb8d8cc90a33b3328ba39e5059cff85a0ab8be7e83a7068c7f
+  data.tar.gz: 337d49c5e424fc9cf487cec98295e4fd80a71da2882a5892c2b478d896cf05e52f6f10632719737df4072abbc555193c1475ae7b01d0e9f51d88ac5df3cc62fc

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Legion::Logging Changelog
 
+## [1.5.1] - 2026-04-08
+
+### Added
+- `Legion::Logging::MethodTracer` module: opt-in TracePoint-based method call tracing with indent-aware call/return output and parameter formatting
+- `Helper.included` / `Helper.extended` hooks auto-attach `MethodTracer` when `MethodTracer::ENABLED` is true
+- `log_exception` now formats backtrace (up to 10 frames + overflow count) inline in the stdout/file log line
+- `Legion::Logging.current_settings` and `.configuration_generation` so helper mixins can refresh memoized tagged loggers after runtime reconfiguration
+- Component logger overrides from local `settings`, top-level `Legion::Settings[component]`, and `Legion::Settings.dig(:extensions, component)` for `log_level`, `trace`, `trace_size`, and `extended`
+- `Methods#emit_tagged` / `TaggedLogger#dispatch` path so component-level loggers can emit with their own level while preserving tagged context
+- Fallback exception event construction in `Helper#handle_exception` when structured exception support is unavailable
+
+### Changed
+- `setup` and `Builder#log_level` now default to `debug`
+- Default helper/tagged logger behavior enables trace and extended metadata
+- `Helper#log` rebuilds memoized `TaggedLogger` instances when logging configuration changes
+- Runtime logger settings take precedence over loaded global settings for helper-mixed components
+
+### Fixed
+- `setup(async: true)` now tolerates boolean `logging.async` settings without probing for `buffer_size`
+- Exception stdout/file output now falls back safely when singleton logger helpers are unavailable
+- Structured exception publishing is skipped when the exception writer/EventBuilder path is unavailable
+- `TaggedLogger#unknown` falls back to `debug` output when `Legion::Logging.unknown` is unavailable
+
 ## [1.4.3] - 2026-04-01
 
 ### Added
@@ -176,4 +199,4 @@
 - `format_for_elk` produces ELK-compatible event hashes
 
 ## v1.2.0
-Moving from BitBucket to GitHub. All git history is reset from this point on
+Moving from BitBucket to GitHub. All git history is reset from this point on

data/CLAUDE.md

@@ -8,40 +8,50 @@
 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.
 
 **GitHub**: https://github.com/LegionIO/legion-logging
-**Version**: 1.3.2
+**Version**: 1.5.0
 **License**: Apache-2.0
 
 ## Architecture
 
 ```
 Legion::Logging (singleton module)
-├── Methods         # Log level methods: debug, info, warn, error, fatal, unknown
-├── 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)
-├── 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
-├── SIEMExporter    # PHI-redacting SIEM export (Splunk HEC, ELK/OpenSearch)
-├── Shipper         # Buffered log event forwarding (file/http transports)
-├── Redactor        # PII/PHI pattern redaction
-└── Version         # VERSION constant
+├── 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:) {})
 ```
 
 ### 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
-- **Setup Method**: `Legion::Logging.setup(log_file:, level:, async: true)` configures output destination, level, and async mode
-- **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.dig(: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
+- **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 — never impact the logger. 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.
+- **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.
 
 ## Dependencies
 
@@ -62,7 +72,15 @@ Legion::Logging (singleton module)
 | `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 |
+| `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 |
 
 ## Role in LegionIO

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.4.1
+**Version**: 1.5.0
 
 ## Installation
 

data/lib/legion/logging/async_writer.rb

@@ -5,40 +5,58 @@ require_relative 'methods'
 module Legion
   module Logging
     class AsyncWriter
-      LogEntry = ::Data.define(:level, :message, :writer_context, :segments, :method_ctx)
+      LogEntry = ::Data.define(:level, :message, :writer_context, :segments, :method_ctx, :caller_trace)
       SHUTDOWN = :shutdown
 
+      attr_reader :logger
+
       def initialize(logger, buffer_size: 10_000)
         @logger = logger
+        @buffer_size = buffer_size
         @queue  = SizedQueue.new(buffer_size)
         @thread = nil
+        @state_mutex = Mutex.new
+        @accepting = true
       end
 
       def start
         return if @thread&.alive?
 
+        @state_mutex.synchronize { @accepting = true }
         drain
+        @queue = SizedQueue.new(@buffer_size)
         @thread = Thread.new { consume }
         @thread.name = 'legion-log-writer'
         @thread.abort_on_exception = false
       end
 
+      # rubocop:disable Naming/PredicateMethod
       def stop(timeout: 2)
-        return unless @thread&.alive?
+        @state_mutex.synchronize { @accepting = false }
 
-        begin
-          @queue.push(SHUTDOWN, true)
-        rescue ThreadError
-          # Queue full — fall through to join/kill + drain
+        unless @thread&.alive?
+          drain
+          @thread = nil
+          return true
         end
-        @thread.join(timeout)
-        @thread.kill if @thread&.alive?
-        drain
+
+        @queue.close
+        timeout ? @thread.join(timeout) : @thread.join
+        return false if @thread&.alive?
+
+        @thread = nil
+        true
       end
 
       def push(entry)
+        return false unless accepting?
+
         @queue.push(entry)
+        true
+      rescue ClosedQueueError
+        false
       end
+      # rubocop:enable Naming/PredicateMethod
 
       def alive?
         @thread&.alive? || false
@@ -49,7 +67,7 @@ module Legion
       def consume
         loop do
           entry = @queue.pop
-          break if entry == SHUTDOWN
+          break if entry.nil? || entry == SHUTDOWN
 
           write_entry(entry)
         end
@@ -58,8 +76,10 @@ module Legion
       def write_entry(entry)
         prev_segments   = Thread.current[:legion_log_segments]
         prev_method_ctx = Thread.current[:legion_log_method]
+        prev_caller     = Thread.current[:legion_log_caller]
         Thread.current[:legion_log_segments] = entry.segments
         Thread.current[:legion_log_method]   = entry.method_ctx
+        Thread.current[:legion_log_caller]   = entry.caller_trace
         @logger.send(entry.level, entry.message)
         fire_writer(entry) if entry.writer_context
       rescue StandardError => e
@@ -67,6 +87,7 @@ module Legion
       ensure
         Thread.current[:legion_log_segments] = prev_segments
         Thread.current[:legion_log_method]   = prev_method_ctx
+        Thread.current[:legion_log_caller]   = prev_caller
       end
 
       def drain
@@ -78,6 +99,10 @@ module Legion
         nil
       end
 
+      def accepting?
+        @state_mutex.synchronize { @accepting }
+      end
+
       def fire_writer(entry)
         ctx = entry.writer_context
         event = ctx[:event]

data/lib/legion/logging/builder.rb

@@ -41,7 +41,7 @@ module Legion
       def text_format(include_pid: false, **options)
         log.formatter = proc do |severity, datetime, _progname, msg|
           lex_name = resolve_lex_tag(options)
-          runner_trace = build_runner_trace if lex_name
+          runner_trace = Thread.current[:legion_log_caller] || build_runner_trace if lex_name
 
           string = "[#{datetime}]"
           string.concat("[#{::Process.pid}]") if include_pid
@@ -69,8 +69,7 @@ module Legion
         tag
       end
 
-      def build_runner_trace
-        loc = caller_locations(6, 1)&.first
+      def build_runner_trace(loc = caller_locations(6, 1)&.first)
         return unless loc
 
         path = loc.to_s.split('/').last(2)
@@ -91,16 +90,25 @@ module Legion
       end
 
       def set_log(logfile: nil, log_stdout: nil, **)
+        previous_log = @log
+
         if logfile && log_stdout != false
           path = prepare_log_path(logfile)
           require_relative 'multi_io'
-          io = MultiIO.new($stdout, File.open(path, 'a'))
+          file = File.new(path, 'a')
+          file.sync = true
+          io = MultiIO.new($stdout, file)
           @log = ::Logger.new(io)
         elsif logfile
-          @log = ::Logger.new(prepare_log_path(logfile))
+          file = File.new(prepare_log_path(logfile), 'a')
+          file.sync = true
+          @log = ::Logger.new(file)
         else
           @log = ::Logger.new($stdout)
         end
+
+        close_replaced_log(previous_log)
+        @log
       end
 
       def prepare_log_path(path)
@@ -113,7 +121,7 @@ module Legion
         log.level
       end
 
-      def log_level(level = 'info')
+      def log_level(level = 'debug')
         log.level = case level
                     when 'trace', 'debug'
                       ::Logger::DEBUG
@@ -140,19 +148,41 @@ module Legion
         (@async == true && @async_writer&.alive?) || false
       end
 
+      # rubocop:disable Naming/PredicateMethod
       def start_async_writer(buffer_size: 10_000)
         require_relative 'async_writer'
-        stop_async_writer if @async_writer&.alive?
+        return false if @async_writer&.alive? && stop_async_writer == false
+
         @async_writer = AsyncWriter.new(log, buffer_size: buffer_size)
         @async_writer.start
         @async = true
+        true
       end
 
       def stop_async_writer
         writer = @async_writer
-        @async_writer = nil
+        stopped = writer&.stop
+        return false if stopped == false
+
+        close_replaced_log(writer.logger) if writer.respond_to?(:logger)
+        @async_writer = nil if @async_writer.equal?(writer)
         @async = false
-        writer&.stop
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      private
+
+      def close_replaced_log(logger)
+        return unless logger
+        return if logger.equal?(@log)
+        return if @async_writer&.alive? && @async_writer.respond_to?(:logger) && @async_writer.logger.equal?(logger)
+
+        log_device = logger.instance_variable_get(:@logdev)
+        dev = log_device&.dev
+        return if dev.nil? || [$stdout, $stderr].include?(dev)
+
+        dev.close if dev.respond_to?(:close)
       end
     end
   end

data/lib/legion/logging/event_builder.rb

@@ -11,6 +11,29 @@ module Legion
       MAX_PAYLOAD_BYTES        = 8192
       MAX_TOTAL_BYTES          = 65_536
       BACKTRACE_FALLBACK_FRAMES = 20
+      MIN_TRUNCATED_FIELD_BYTES = 256
+
+      CORE_EXCEPTION_FIELDS = %i[
+        timestamp
+        level
+        exception_class
+        message
+        caller_file
+        caller_line
+        caller_function
+        lex
+        component_type
+        gem_name
+        lex_version
+        handled
+        pid
+        thread
+        task_id
+        conversation_id
+        user
+        error_fingerprint
+        node
+      ].freeze
 
       GEM_SPEC_CACHE_MUTEX = Mutex.new
       private_constant :GEM_SPEC_CACHE_MUTEX
@@ -310,6 +333,56 @@ module Legion
           return if safe_json_bytesize(event) <= MAX_TOTAL_BYTES
 
           event[:message] = truncate_bytes(event[:message].to_s, 1024)
+          trim_optional_fields!(event)
+          hard_cap_message!(event)
+        end
+
+        def trim_optional_fields!(event)
+          while safe_json_bytesize(event) > MAX_TOTAL_BYTES
+            key = largest_optional_field(event)
+            break unless key
+
+            reduced = reduce_field(event[key])
+            if reduced.nil?
+              event.delete(key)
+            else
+              event[key] = reduced
+            end
+          end
+        end
+
+        def largest_optional_field(event)
+          event.each_key
+               .reject { |key| CORE_EXCEPTION_FIELDS.include?(key) }
+               .max_by { |key| safe_json_bytesize(event[key]) }
+        end
+
+        def reduce_field(value)
+          case value
+          when String
+            return nil if value.bytesize <= MIN_TRUNCATED_FIELD_BYTES
+
+            truncate_bytes(value, [value.bytesize / 2, MIN_TRUNCATED_FIELD_BYTES].max)
+          when Array
+            return nil if value.size <= 1
+
+            value.first([value.size / 2, 1].max)
+          when Hash
+            return nil if value.size <= 1
+
+            value.first([value.size / 2, 1].max).to_h
+          end
+        end
+
+        def hard_cap_message!(event)
+          return if safe_json_bytesize(event) <= MAX_TOTAL_BYTES
+
+          event[:message] = truncate_bytes(event[:message].to_s, MIN_TRUNCATED_FIELD_BYTES)
+          return if safe_json_bytesize(event) <= MAX_TOTAL_BYTES
+
+          message_overhead = safe_json_bytesize(event.merge(message: ''))
+          available = MAX_TOTAL_BYTES - message_overhead
+          event[:message] = truncate_bytes(event[:message].to_s, [available, 0].max)
         end
       end
     end