legion-logging 1.4.3 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 707d2460ca4e016ca62cc8ef83bf2d646819439ed67ef5549a164518ba2d3bf5
-  data.tar.gz: a013c59d975f901f25b153cbbfe4ed288dbedb262098627aed6d71baeb70031a
+  metadata.gz: 62c3c14ff8e6f67a11941a869f4f4ea2b682686c85c41bb1568368b448f23d0c
+  data.tar.gz: af9c1588f601a09f6b986d9dc47cc07b1c8e9b966e482b45d1a7242342e8d500
 SHA512:
-  metadata.gz: f5f3d87c609bca88c501e32d241fabc796e48b8aae8912fed39ac3615e0565f2a7d4672b66f12b0fdf606c6d3e0b40abb2b04b9b38d554edca4e9fa4b063a40a
-  data.tar.gz: 741697e72078cb1cbede684a8729d8a9a0b79c25a8beb4ed465aa53ae89711e11f482b9e93f434f51dae0778dfdf3bf49855282e80a7df17f98054d980d3e037
+  metadata.gz: 66a26f844b44432886b1d703d93dbb9547134ede3542610861e123e240b8ec89746d7bdc522ae8e831c93e212f9e1a9bff5fc9b2fa19a78dfb47007373c5e0ab
+  data.tar.gz: add0a140cbe3c101dc83dcfb4b1c3eef385e4c778a4b6957be6d71b2ec95a9316c3b36d7b687906867046d482b2246ad0a44e8fd4cc98472ad1157994207146a

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Legion::Logging Changelog
 
+## [1.5.0] - 2026-04-02
+
+### Added
+- `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 +196,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/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

data/lib/legion/logging/helper.rb

@@ -54,7 +54,19 @@ module Legion
       end
 
       def log
-        @log ||= Legion::Logging::TaggedLogger.new(segments: derive_log_segments, **resolve_logger_settings)
+        current_generation =
+          if defined?(Legion::Logging) && Legion::Logging.respond_to?(:configuration_generation)
+            Legion::Logging.configuration_generation
+          else
+            0
+          end
+
+        if !defined?(@log) || @log.nil? || @log_generation != current_generation
+          @log = Legion::Logging::TaggedLogger.new(segments: derive_log_segments, **tagged_logger_settings)
+          @log_generation = current_generation
+        end
+
+        @log
       end
 
       def with_log_context(method_name)
@@ -70,19 +82,13 @@ module Legion
         spec = gem_spec
         ctx = Thread.current[:legion_context] || {}
 
-        event = Legion::Logging::EventBuilder.build_exception(
+        event = build_exception_event(
           exception:       exception,
           level:           level,
-          lex:             log_name,
-          component_type:  derive_component_type,
-          gem_name:        gem_name,
-          lex_version:     spec&.version&.to_s,
-          gem_path:        spec&.full_gem_path,
-          source_code_uri: spec&.metadata&.[]('source_code_uri'),
+          spec:            spec,
           handled:         handled,
           task_id:         task_id || ctx[:task_id],
-          payload_summary: opts.empty? ? nil : opts,
-          caller_offset:   3
+          payload_summary: opts.empty? ? nil : opts
         )
 
         event[:conversation_id] ||= ctx[:conversation_id]
@@ -93,11 +99,57 @@ module Legion
         event = Legion::Logging::Redactor.redact(event) if defined?(Legion::Logging::Redactor)
 
         write_exception_to_log(exception, event, level, segments)
-        publish_exception(event, level)
+        publish_exception(event, level) if structured_exception_support?
       end
 
       private
 
+      def build_exception_event(exception:, level:, spec:, handled:, task_id:, payload_summary:)
+        unless structured_exception_support?
+          return fallback_exception_event(
+            exception:       exception,
+            level:           level,
+            spec:            spec,
+            handled:         handled,
+            task_id:         task_id,
+            payload_summary: payload_summary
+          )
+        end
+
+        Legion::Logging::EventBuilder.build_exception(
+          exception:       exception,
+          level:           level,
+          lex:             log_name,
+          component_type:  derive_component_type,
+          gem_name:        gem_name,
+          lex_version:     spec&.version&.to_s,
+          gem_path:        spec&.full_gem_path,
+          source_code_uri: spec&.metadata&.[]('source_code_uri'),
+          handled:         handled,
+          task_id:         task_id,
+          payload_summary: payload_summary,
+          caller_offset:   3
+        )
+      end
+
+      def fallback_exception_event(exception:, level:, spec:, handled:, task_id:, payload_summary:)
+        {
+          exception_class:   exception.class.to_s,
+          message:           exception.message,
+          level:             level,
+          lex:               log_name,
+          component_type:    derive_component_type,
+          gem_name:          gem_name,
+          lex_version:       spec&.version&.to_s,
+          gem_path:          spec&.full_gem_path,
+          source_code_uri:   spec&.metadata&.[]('source_code_uri'),
+          handled:           handled,
+          task_id:           task_id,
+          payload_summary:   payload_summary,
+          error_fingerprint: SecureRandom.uuid
+        }
+      end
+
       def derive_log_segments
         key = respond_to?(:ancestors) ? ancestors.first : self.class
         return SEGMENT_CACHE[key] if SEGMENT_CACHE.key?(key)
@@ -167,22 +219,238 @@ module Legion
         @gem_spec_value = nil
       end
 
-      def settings
-        { logger: logger_settings }
+      def instance_log_level(default = Legion::Logging::Settings.default[:level] || :info)
+        component_level = component_log_level
+        return component_level if present_log_level?(component_level)
+
+        global_level = global_log_level
+        return global_level if present_log_level?(global_level)
+
+        Legion::Logging::Settings.default[:level] || default
+      rescue StandardError => e
+        Legion::Logging.warn("Legion::Logging::Helper.instance_log_level(#{default}) failed: #{e.class}: #{e.message}")
+        Legion::Logging::Settings.default[:level] || default
       end
 
-      def logger_settings
-        return Legion::Settings[:logging] if defined?(Legion::Settings) && Legion::Settings[:logging].is_a?(Hash)
+      def global_logger_settings
+        defaults = defined?(Legion::Logging::Settings) ? Legion::Logging::Settings.default.dup : {}
+        settings_logging = if defined?(Legion::Settings) &&
+                              Legion::Settings.respond_to?(:loaded?) &&
+                              Legion::Settings.loaded?
+                             raw = Legion::Settings[:logging]
+                             raw.is_a?(Hash) ? raw : {}
+                           else
+                             {}
+                           end
+        runtime_logging = if defined?(Legion::Logging) &&
+                             Legion::Logging.respond_to?(:current_settings)
+                            current = Legion::Logging.current_settings
+                            current.is_a?(Hash) ? current : {}
+                          else
+                            {}
+                          end
 
-        Legion::Logging::Settings.default
+        defaults.merge(settings_logging).merge(runtime_logging)
       end
 
       def resolve_logger_settings
-        s = settings
-        return Legion::Logging::Settings.default unless s.is_a?(Hash)
+        base = global_logger_settings
+        override = component_logger_settings
+        merged = override ? base.merge(override) : base
+        merged.merge(
+          level:      instance_log_level(merged[:level]),
+          trace:      instance_trace(merged[:trace]),
+          trace_size: instance_trace_size(merged[:trace_size]),
+          extended:   instance_extended(merged[:extended])
+        )
+      rescue StandardError
+        defined?(Legion::Logging::Settings) ? Legion::Logging::Settings.default : {}
+      end
+
+      def tagged_logger_settings
+        settings = resolve_logger_settings
+        {
+          level:      settings[:level],
+          trace:      settings[:trace],
+          trace_size: settings[:trace_size],
+          extended:   settings[:extended]
+        }
+      end
+
+      def component_logger_settings
+        source = component_settings
+        raw = settings_value(source, :logger)
+        raw.is_a?(Hash) ? raw : nil
+      end
+
+      def component_log_level
+        source = component_settings
+        return unless source.is_a?(Hash)
+
+        settings_value(source, :log_level) ||
+          settings_value(source, :logger_level) ||
+          settings_value(source, :logger, :level)
+      end
+
+      def instance_trace(default = Legion::Logging::Settings.default[:trace])
+        component_trace = component_logger_option(:trace)
+        return component_trace unless component_trace.nil?
+
+        global_trace = global_logger_option(:trace)
+        return global_trace unless global_trace.nil?
+
+        Legion::Logging::Settings.default[:trace].nil? ? default : Legion::Logging::Settings.default[:trace]
+      rescue StandardError => e
+        Legion::Logging.warn("Legion::Logging::Helper.instance_trace(#{default}) failed: #{e.class}: #{e.message}")
+        Legion::Logging::Settings.default[:trace].nil? ? default : Legion::Logging::Settings.default[:trace]
+      end
+
+      def instance_trace_size(default = Legion::Logging::Settings.default[:trace_size] || 4)
+        component_trace_size = component_logger_option(:trace_size)
+        return component_trace_size unless component_trace_size.nil?
+
+        global_trace_size = global_logger_option(:trace_size)
+        return global_trace_size unless global_trace_size.nil?
 
-        raw = s[:logger]
-        raw.is_a?(Hash) ? raw : Legion::Logging::Settings.default
+        Legion::Logging::Settings.default[:trace_size] || default
+      rescue StandardError => e
+        Legion::Logging.warn("Legion::Logging::Helper.instance_trace_size(#{default}) failed: #{e.class}: #{e.message}")
+        Legion::Logging::Settings.default[:trace_size] || default
+      end
+
+      def instance_extended(default = Legion::Logging::Settings.default[:extended])
+        component_extended = component_logger_option(:extended)
+        return component_extended unless component_extended.nil?
+
+        global_extended = global_logger_option(:extended)
+        return global_extended unless global_extended.nil?
+
+        Legion::Logging::Settings.default[:extended].nil? ? default : Legion::Logging::Settings.default[:extended]
+      rescue StandardError => e
+        Legion::Logging.warn("Legion::Logging::Helper.instance_extended(#{default}) failed: #{e.class}: #{e.message}")
+        Legion::Logging::Settings.default[:extended].nil? ? default : Legion::Logging::Settings.default[:extended]
+      end
+
+      def component_settings
+        local = local_settings_hash
+        return local if local.is_a?(Hash)
+
+        legion_component_settings
+      end
+
+      def local_settings_hash
+        return unless respond_to?(:settings, true)
+
+        source = settings
+        source if source.is_a?(Hash)
+      rescue StandardError
+        nil
+      end
+
+      def legion_component_settings
+        return unless defined?(Legion::Settings)
+        return unless Legion::Settings.respond_to?(:loaded?) ? Legion::Settings.loaded? : true
+
+        key = derive_component_settings_key
+        return unless key
+
+        top_level = Legion::Settings[key]
+        return top_level if top_level.is_a?(Hash)
+
+        extension_settings = Legion::Settings.dig(:extensions, key)
+        extension_settings if extension_settings.is_a?(Hash)
+      rescue StandardError
+        nil
+      end
+
+      def derive_component_settings_key
+        base = log_name
+        return unless base
+
+        base.to_s.tr('-', '_').to_sym
+      rescue StandardError
+        nil
+      end
+
+      def global_log_level
+        runtime_level = if defined?(Legion::Logging) &&
+                           Legion::Logging.respond_to?(:current_settings)
+                          settings_value(Legion::Logging.current_settings, :level)
+                        end
+        return runtime_level if present_log_level?(runtime_level)
+
+        return unless defined?(Legion::Settings)
+        return unless Legion::Settings.respond_to?(:loaded?) ? Legion::Settings.loaded? : true
+
+        settings_value(Legion::Settings[:logging], :level) || Legion::Settings[:level]
+      rescue StandardError
+        nil
+      end
+
+      def component_logger_option(key)
+        source = component_settings
+        return unless source.is_a?(Hash)
+
+        return settings_value(source, key) if settings_key?(source, key)
+        return settings_value(source, :logger, key) if settings_key?(source, :logger, key)
+
+        nil
+      end
+
+      def global_logger_option(key)
+        runtime_value = if defined?(Legion::Logging) &&
+                           Legion::Logging.respond_to?(:current_settings)
+                          settings_value(Legion::Logging.current_settings, key)
+                        end
+        return runtime_value unless runtime_value.nil?
+
+        return unless defined?(Legion::Settings)
+        return unless Legion::Settings.respond_to?(:loaded?) ? Legion::Settings.loaded? : true
+
+        settings_value(Legion::Settings[:logging], key)
+      rescue StandardError
+        nil
+      end
+
+      def settings_value(source, *keys)
+        missing = Object.new
+        current = source
+        keys.each do |key|
+          current =
+            if current.is_a?(Hash) && current.key?(key)
+              current[key]
+            elsif current.is_a?(Hash) && current.key?(key.to_s)
+              current[key.to_s]
+            else
+              missing
+            end
+
+          break if current.equal?(missing)
+        end
+
+        current.equal?(missing) ? nil : current
+      end
+
+      def settings_key?(source, *keys)
+        current = source
+        keys.each do |key|
+          return false unless current.is_a?(Hash)
+
+          next_key = if current.key?(key)
+                       key
+                     elsif current.key?(key.to_s)
+                       key.to_s
+                     else
+                       return false
+                     end
+          current = current[next_key]
+        end
+
+        true
+      end
+
+      def present_log_level?(value)
+        !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
       end
 
       # -- Exception stdout/file output --
@@ -193,9 +461,14 @@ module Legion
 
         message = format_exception_output(exception, event)
         message = Legion::Logging::Redactor.redact_string(message) if defined?(Legion::Logging::Redactor) && redaction_enabled?
-        message = colorize_exception(message, level) if Legion::Logging.color
+        message = colorize_exception(message, level) if Legion::Logging.respond_to?(:color) && Legion::Logging.color
 
-        Legion::Logging.log.public_send(level, message)
+        logger = Legion::Logging.respond_to?(:log) ? Legion::Logging.log : nil
+        if logger.respond_to?(level)
+          logger.public_send(level, message)
+        elsif Legion::Logging.respond_to?(level)
+          Legion::Logging.public_send(level, message)
+        end
       ensure
         Thread.current[:legion_log_segments] = prev_segs
       end
@@ -251,6 +524,8 @@ module Legion
       # -- Exception structured publish --
 
       def publish_exception(event, level)
+        return unless structured_exception_support?
+
         lex_name = event[:lex] || 'core'
         comp = event[:component_type] || :unknown
         routing_key = "legion.logging.exception.#{level}.#{lex_name}.#{comp}"
@@ -260,7 +535,12 @@ module Legion
 
         Legion::Logging.exception_writer.call(event, routing_key: routing_key, headers: headers, properties: properties)
       rescue StandardError => e
-        Legion::Logging.warn("Failed to publish exception event: #{e.class}: #{e.message}")
+        Legion::Logging.warn("Failed to publish exception event: #{e.class}: #{e.message}") if Legion::Logging.respond_to?(:warn)
+      end
+
+      def structured_exception_support?
+        defined?(Legion::Logging::EventBuilder) &&
+          Legion::Logging.respond_to?(:exception_writer)
       end
 
       def build_exception_headers(event, comp, level)

data/lib/legion/logging/methods.rb

@@ -30,78 +30,36 @@ module Legion
         return unless log.level < 1
 
         message = yield if message.nil? && block_given?
-        message = maybe_redact(message)
-        message = Rainbow(message).blue if @color
-        writer = @async_writer
-        if writer&.alive?
-          writer.push(AsyncWriter::LogEntry.new(
-                        level: :debug, message: message, writer_context: nil,
-                        segments: Thread.current[:legion_log_segments],
-                        method_ctx: Thread.current[:legion_log_method]
-                      ))
-        else
-          log.debug(message)
-        end
+        raw = maybe_redact(message)
+        formatted = format_message_for_level(:debug, raw)
+        write_async_or_sync(:debug, formatted, raw)
       end
 
       def info(message = nil)
         return unless log.level < 2
 
         message = yield if message.nil? && block_given?
-        message = maybe_redact(message)
-        message = Rainbow(message).green if @color
-        writer = @async_writer
-        if writer&.alive?
-          writer.push(AsyncWriter::LogEntry.new(
-                        level: :info, message: message, writer_context: nil,
-                        segments: Thread.current[:legion_log_segments],
-                        method_ctx: Thread.current[:legion_log_method]
-                      ))
-        else
-          log.info(message)
-        end
+        raw = maybe_redact(message)
+        formatted = format_message_for_level(:info, raw)
+        write_async_or_sync(:info, formatted, raw)
       end
 
       def warn(message = nil)
         return unless log.level < 3
 
         message = yield if message.nil? && block_given?
-        message = maybe_redact(message)
-        raw = message
-        message = Rainbow(message).yellow if @color
-        writer = @async_writer
-        if writer&.alive?
-          ctx = build_writer_context(:warn, raw)
-          writer.push(AsyncWriter::LogEntry.new(
-                        level: :warn, message: message, writer_context: ctx,
-                        segments: Thread.current[:legion_log_segments],
-                        method_ctx: Thread.current[:legion_log_method]
-                      ))
-        else
-          log.warn(message)
-          fire_log_writer(:warn, raw)
-        end
+        raw = maybe_redact(message)
+        formatted = format_message_for_level(:warn, raw)
+        write_async_or_sync(:warn, formatted, raw, writer_context: build_writer_context(:warn, raw))
       end
 
       def error(message = nil)
         return unless log.level < 4
 
         message = yield if message.nil? && block_given?
-        message = maybe_redact(message)
-        raw = message
-        message = Rainbow(message).red if @color
-        writer = @async_writer
-        if writer&.alive?
-          ctx = build_writer_context(:error, raw)
-          writer.push(AsyncWriter::LogEntry.new(
-                        level: :error, message: message, writer_context: ctx,
-                        segments: Thread.current[:legion_log_segments],
-                        method_ctx: Thread.current[:legion_log_method]
-                      ))
-        else
-          log.error(message)
-          fire_log_writer(:error, raw)
-        end
+        raw = maybe_redact(message)
+        formatted = format_message_for_level(:error, raw)
+        write_async_or_sync(:error, formatted, raw, writer_context: build_writer_context(:error, raw))
       end
 
       def fatal(message = nil)
@@ -117,17 +75,22 @@ module Legion
 
       def unknown(message = nil)
         message = yield if message.nil? && block_given?
-        message = maybe_redact(message)
-        message = Rainbow(message).purple if @color
-        writer = @async_writer
-        if writer&.alive?
-          writer.push(AsyncWriter::LogEntry.new(
-                        level: :unknown, message: message, writer_context: nil,
-                        segments: Thread.current[:legion_log_segments],
-                        method_ctx: Thread.current[:legion_log_method]
-                      ))
-        else
-          log.unknown(message)
+        raw = maybe_redact(message)
+        formatted = format_message_for_level(:unknown, raw)
+        write_async_or_sync(:unknown, formatted, raw)
+      end
+
+      def emit_tagged(level, message = nil, segments: nil, method_ctx: nil)
+        level = level.to_sym
+        message = yield if message.nil? && block_given?
+        return if message.nil?
+
+        raw = maybe_redact(message)
+        formatted = format_message_for_level(level, raw)
+
+        with_tagged_context(segments, method_ctx) do
+          write_forced(level, formatted)
+          fire_log_writer(level, raw) if %i[warn error fatal].include?(level)
         end
       end
 
@@ -143,6 +106,7 @@ module Legion
         level = level.to_sym if level.respond_to?(:to_sym)
         # 1. Log human-readable line to stdout/file (bypass writer callbacks)
         msg = exception.respond_to?(:message) ? exception.message : exception.to_s
+        msg = maybe_redact(msg)
         log.public_send(level, msg) if respond_to?(:log) && log.respond_to?(level)
 
         # 2. Build rich exception event
@@ -195,6 +159,81 @@ module Legion
         message
       end
 
+      def format_message_for_level(level, message)
+        return Rainbow(message).blue if level == :debug && @color
+        return Rainbow(message).green if level == :info && @color
+        return Rainbow(message).yellow if level == :warn && @color
+        return Rainbow(message).red if level == :error && @color
+        return Rainbow(message).darkred if level == :fatal && @color
+        return Rainbow(message).purple if level == :unknown && @color
+
+        message
+      end
+
+      def with_tagged_context(segments, method_ctx)
+        prev_segments = Thread.current[:legion_log_segments]
+        prev_method_ctx = Thread.current[:legion_log_method]
+
+        Thread.current[:legion_log_segments] = segments unless segments.nil?
+        Thread.current[:legion_log_method] = method_ctx unless method_ctx.nil?
+        yield
+      ensure
+        Thread.current[:legion_log_segments] = prev_segments
+        Thread.current[:legion_log_method] = prev_method_ctx
+      end
+
+      def write_forced(level, message)
+        logger = log
+        formatter = logger.formatter || ::Logger::Formatter.new
+        rendered = formatter.call(severity_label_for(level), Time.now, nil, message)
+
+        log_device = logger.instance_variable_get(:@logdev)
+        if log_device.respond_to?(:write)
+          log_device.write(rendered)
+        else
+          $stdout.write(rendered)
+        end
+      end
+
+      def severity_label_for(level)
+        return 'ANY' if level == :unknown
+
+        level.to_s.upcase
+      end
+
+      def write_async_or_sync(level, formatted_message, raw_message, writer_context: nil)
+        writer = @async_writer
+        caller_trace = capture_runner_trace_for_async
+        if writer&.alive?
+          queued = writer.push(AsyncWriter::LogEntry.new(
+                                 level:          level,
+                                 message:        formatted_message,
+                                 writer_context: writer_context,
+                                 segments:       Thread.current[:legion_log_segments],
+                                 method_ctx:     Thread.current[:legion_log_method],
+                                 caller_trace:   caller_trace
+                               ))
+          return if queued
+        end
+
+        with_caller_trace(caller_trace) do
+          log.public_send(level, formatted_message)
+          fire_log_writer(level, raw_message) if writer_context
+        end
+      end
+
+      def capture_runner_trace_for_async
+        build_runner_trace(caller_locations(4, 1)&.first)
+      end
+
+      def with_caller_trace(caller_trace)
+        prev_caller_trace = Thread.current[:legion_log_caller]
+        Thread.current[:legion_log_caller] = caller_trace
+        yield
+      ensure
+        Thread.current[:legion_log_caller] = prev_caller_trace
+      end
+
       def redaction_enabled?
         return false unless defined?(Legion::Settings)
 

data/lib/legion/logging/multi_io.rb

@@ -10,7 +10,6 @@ module Legion
       def write(message)
         @targets.each do |t|
           t.write(message)
-          t.flush if t.respond_to?(:flush)
         end
       end
 

data/lib/legion/logging/redactor.rb

@@ -18,7 +18,18 @@ module Legion
         bearer_token:   %r{Bearer\s+[A-Za-z0-9._~+/=-]{20,}}i
       }.freeze
 
-      SENSITIVE_FIELDS = %w[password secret token api_key authorization].freeze
+      SENSITIVE_FIELDS = %w[
+        password
+        secret
+        token
+        api_key
+        access_key
+        private_key
+        public_key
+        authorization
+      ].freeze
+      SENSITIVE_SUFFIXES = %w[token secret password passphrase credential credentials].freeze
+      SAFE_KEY_FIELDS = %w[primary_key foreign_key sort_key partition_key routing_key].freeze
 
       REDACTED = '[REDACTED]'
 
@@ -49,7 +60,17 @@ module Legion
         private
 
         def sensitive_field?(key)
-          SENSITIVE_FIELDS.include?(key.to_s.downcase)
+          normalized = normalize_key(key)
+          return false if SAFE_KEY_FIELDS.include?(normalized)
+          return true if SENSITIVE_FIELDS.include?(normalized)
+          return true if normalized.include?('authorization')
+          return true if normalized.start_with?('auth_') || normalized.end_with?('_auth')
+          return true if normalized.start_with?('bearer_') || normalized.end_with?('_bearer')
+          return true if SENSITIVE_SUFFIXES.any? { |suffix| normalized.end_with?("_#{suffix}") }
+
+          %w[api access client private public auth secret signing session].any? do |prefix|
+            normalized == "#{prefix}_key"
+          end
         end
 
         def all_patterns
@@ -79,6 +100,16 @@ module Legion
         def reset_pattern_cache!
           @all_patterns = nil
         end
+
+        def refresh_patterns!
+          reset_pattern_cache!
+        end
+
+        public :refresh_patterns!
+
+        def normalize_key(key)
+          key.to_s.downcase.gsub(/[^a-z0-9]+/, '_').gsub(/\A_+|_+\z/, '')
+        end
       end
     end
   end

data/lib/legion/logging/settings.rb

@@ -6,9 +6,9 @@ module Legion
       def self.default
         {
           level:      :info,
-          trace:      false,
+          trace:      true,
           trace_size: 4,
-          extended:   false
+          extended:   true
         }
       end
     end

data/lib/legion/logging/shipper/file_transport.rb

@@ -11,10 +11,18 @@ module Legion
 
         class << self
           def ship(event)
+            ship_batch([event])
+          end
+
+          def ship_batch(events)
+            batch = Array(events)
+            return true if batch.empty?
+
             path = resolve_path
             FileUtils.mkdir_p(File.dirname(path))
             File.open(path, 'a') do |f|
-              f.puts(::JSON.generate(event))
+              f.write(batch.map { |event| ::JSON.generate(event) }.join("\n"))
+              f.write("\n")
             end
             true
           rescue StandardError => e

data/lib/legion/logging/shipper/http_transport.rb

@@ -10,6 +10,10 @@ module Legion
       module HttpTransport
         class << self
           def ship(events)
+            ship_batch(events)
+          end
+
+          def ship_batch(events)
             endpoint = resolve_endpoint
             return false unless endpoint
 

data/lib/legion/logging/shipper.rb

@@ -30,21 +30,25 @@ module Legion
           transport = TRANSPORTS[transport_type]
           return unless transport
 
-          batch = nil
-          @mutex.synchronize do
-            batch = @buffer.dup
-            @buffer.clear
+          @flush_mutex ||= Mutex.new
+          @flush_mutex.synchronize do
+            batch = nil
+            @mutex.synchronize { batch = @buffer.dup }
+            return if batch.empty?
+
+            delivered = deliver(transport, batch)
+            @mutex.synchronize { @buffer.shift(batch.size) if delivered }
+            delivered
           end
-
-          deliver(transport, batch)
         end
 
         def start
           return unless enabled?
           return if @flush_thread&.alive?
 
-          @buffer = []
-          @mutex  = Mutex.new
+          @buffer ||= []
+          @mutex  ||= Mutex.new
+          @flush_mutex ||= Mutex.new
           interval = flush_interval
           @flush_thread = Thread.new do
             loop do
@@ -83,14 +87,14 @@ module Legion
         end
 
         def deliver(transport, batch)
-          if transport.method(:ship).arity == 1
-            # HttpTransport accepts a batch array
-            transport.ship(batch)
+          if transport.respond_to?(:ship_batch)
+            transport.ship_batch(batch)
           else
-            batch.each { |e| transport.ship(e) }
+            batch.all? { |event| transport.ship(event) }
           end
         rescue StandardError => e
           Legion::Logging.error("Shipper deliver failed: #{e.message}") if defined?(Legion::Logging)
+          false
         end
 
         def shippable_level?(level)

data/lib/legion/logging/tagged_logger.rb

@@ -7,13 +7,21 @@ module Legion
 
       attr_reader :segments, :trace_enabled, :extended
 
-      def initialize(segments:, level: :info, trace: false, trace_size: 4, extended: false, **_opts)
+      def initialize(
+        segments:,
+        level: Legion::Logging::Settings.default[:level],
+        trace: Legion::Logging::Settings.default[:trace],
+        trace_size: Legion::Logging::Settings.default[:trace_size],
+        extended: Legion::Logging::Settings.default[:extended],
+        **_opts
+      )
         @segments = segments
         @level_value =
           if level.is_a?(Integer)
             level
           else
-            LEVELS.fetch(level.to_s.downcase.to_sym, LEVELS[:info])
+            default_level = Legion::Logging::Settings.default[:level].to_s.downcase.to_sym
+            LEVELS.fetch(level.to_s.downcase.to_sym, LEVELS.fetch(default_level, LEVELS[:info]))
           end
         @trace_enabled = trace
         @trace_size = trace_size
@@ -28,40 +36,40 @@ module Legion
         return unless @level_value < 1
 
         message = yield if message.nil? && block_given?
-        with_segments { Legion::Logging.debug(message) }
+        with_segments { dispatch(:debug, message) }
       end
 
       def info(message = nil)
         return unless @level_value < 2
 
         message = yield if message.nil? && block_given?
-        with_segments { Legion::Logging.info(message) }
+        with_segments { dispatch(:info, message) }
       end
 
       def warn(message = nil)
         return unless @level_value < 3
 
         message = yield if message.nil? && block_given?
-        with_segments { Legion::Logging.warn(message) }
+        with_segments { dispatch(:warn, message) }
       end
 
       def error(message = nil)
         return unless @level_value < 4
 
         message = yield if message.nil? && block_given?
-        with_segments { Legion::Logging.error(message) }
+        with_segments { dispatch(:error, message) }
       end
 
       def fatal(message = nil)
         return unless @level_value < 5
 
         message = yield if message.nil? && block_given?
-        with_segments { Legion::Logging.fatal(message) }
+        with_segments { dispatch(:fatal, message) }
       end
 
       def unknown(message = nil)
         message = yield if message.nil? && block_given?
-        with_segments { Legion::Logging.unknown(message) }
+        with_segments { dispatch(:unknown, message) }
       end
 
       def trace(raw_message = nil, size: @trace_size, log_caller: true)
@@ -86,6 +94,29 @@ module Legion
 
       private
 
+      def dispatch(level, message)
+        return unless defined?(Legion::Logging)
+
+        if Legion::Logging.respond_to?(:emit_tagged)
+          Legion::Logging.emit_tagged(level, message, segments: @segments)
+          return
+        end
+
+        if Legion::Logging.respond_to?(level)
+          Legion::Logging.public_send(level, message)
+          return
+        end
+
+        fallback = fallback_level(level)
+        Legion::Logging.public_send(fallback, message) if fallback && Legion::Logging.respond_to?(fallback)
+      end
+
+      def fallback_level(level)
+        return :debug if level == :unknown
+
+        nil
+      end
+
       def with_segments
         prev = Thread.current[:legion_log_segments]
         Thread.current[:legion_log_segments] = @segments

data/lib/legion/logging/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Logging
-    VERSION = '1.4.3'
+    VERSION = '1.5.0'
   end
 end

data/lib/legion/logging.rb

@@ -36,6 +36,14 @@ module Legion
         @exception_writer || DEFAULT_EXCEPTION_WRITER
       end
 
+      def current_settings
+        (@current_settings || {}).dup
+      end
+
+      def configuration_generation
+        @configuration_generation || 0
+      end
+
       def register_category(name, description: nil, expected_fields: [])
         CategoryRegistry.register_category(name, description: description, expected_fields: expected_fields)
       end
@@ -68,18 +76,33 @@ module Legion
         Hooks.clear_hooks!
       end
 
-      def setup(level: 'info', format: :text, async: true, **options)
+      def setup(level: 'debug', format: :text, async: true, **options)
         output(**options)
         log_level(level)
         log_format(format: format, **options)
         @color = options[:color]
         @color = format != :json && (options[:color] || (options[:color].nil? && options[:log_file].nil?))
+        @current_settings = {
+          level:       level,
+          format:      format.to_sym,
+          async:       async,
+          trace:       options.fetch(:trace, true),
+          trace_size:  options.fetch(:trace_size, 4),
+          extended:    options.fetch(:extended, true),
+          log_file:    options[:log_file],
+          log_stdout:  options[:log_stdout],
+          include_pid: options.fetch(:include_pid, false),
+          color:       @color
+        }.freeze
+        @configuration_generation = configuration_generation + 1
+        Legion::Logging::Redactor.refresh_patterns! if defined?(Legion::Logging::Redactor)
         if async
-          buffer = if defined?(Legion::Settings)
-                     Legion::Settings.dig(:logging, :async, :buffer_size) || 10_000
-                   else
-                     10_000
+          buffer = if defined?(Legion::Settings) && Legion::Settings.respond_to?(:[])
+                     logging_settings = Legion::Settings[:logging]
+                     async_settings = logging_settings[:async] if logging_settings.is_a?(Hash)
+                     async_settings[:buffer_size] if async_settings.is_a?(Hash)
                    end
+          buffer ||= 10_000
           start_async_writer(buffer_size: buffer)
         else
           stop_async_writer

metadata

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