legion-logging 1.4.2 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31ec07f7a93713fb708102528d4e61525a4c3b4fa39de510d29a454726b49436
-  data.tar.gz: 62a67fc723d1e865ef3e632d1987b6ce73c2fe9aa033686df5fe3b2fb89bc14c
+  metadata.gz: 62c3c14ff8e6f67a11941a869f4f4ea2b682686c85c41bb1568368b448f23d0c
+  data.tar.gz: af9c1588f601a09f6b986d9dc47cc07b1c8e9b966e482b45d1a7242342e8d500
 SHA512:
-  metadata.gz: 5e0b2171b6ca1b1acbb3ad0f40cbd23a77bf5824a3b2f37a5c9b3484f7edf2cf9cf1a8dc23a9f0ed0acd426e139fb0d7ce13ac0a3ae2a77b3113dd0569cc6d53
-  data.tar.gz: e4e599809e26c6b7a0f9c1a81f05e390175cad0568b6b99f26888b675590972ff9148e27bc53f36461e1d6f09f83fcf7a818b01bd793098c5809910affabb0a2
+  metadata.gz: 66a26f844b44432886b1d703d93dbb9547134ede3542610861e123e240b8ec89746d7bdc522ae8e831c93e212f9e1a9bff5fc9b2fa19a78dfb47007373c5e0ab
+  data.tar.gz: add0a140cbe3c101dc83dcfb4b1c3eef385e4c778a4b6957be6d71b2ec95a9316c3b36d7b687906867046d482b2246ad0a44e8fd4cc98472ad1157994207146a

data/.github/workflows/ci.yml

@@ -3,13 +3,31 @@ on:
   push:
     branches: [main]
   pull_request:
+  schedule:
+    - cron: '0 9 * * 1'
 
 jobs:
   ci:
     uses: LegionIO/.github/.github/workflows/ci.yml@main
 
+  lint:
+    uses: LegionIO/.github/.github/workflows/lint-patterns.yml@main
+
+  security:
+    uses: LegionIO/.github/.github/workflows/security-scan.yml@main
+
+  version-changelog:
+    uses: LegionIO/.github/.github/workflows/version-changelog.yml@main
+
+  dependency-review:
+    uses: LegionIO/.github/.github/workflows/dependency-review.yml@main
+
+  stale:
+    if: github.event_name == 'schedule'
+    uses: LegionIO/.github/.github/workflows/stale.yml@main
+
   release:
-    needs: ci
+    needs: [ci, lint]
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     uses: LegionIO/.github/.github/workflows/release.yml@main
     secrets:

data/CHANGELOG.md

@@ -1,5 +1,66 @@
 # 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
+- `TaggedLogger` lightweight proxy: delegates to singleton for shared stdout/file/async output
+- `Helper#derive_log_segments` with class-level `SEGMENT_CACHE` — auto-derives `[llm][router]` from namespace
+- `Helper#with_log_context` for block-scoped method name thread-locals (`{dispatch}` in log output)
+- `Helper#handle_exception` with direct EventBuilder calls, per-line Rainbow coloring, structured AMQP publish
+- `Helper.current_log_method`, `.current_log_segments`, `.current_context` thread-local readers
+- `Legion::Logging::Settings` module with logger defaults
+- `COMPONENT_MAP` with 18 component types (runners, actors, hooks, absorbers, tools, adapters, middleware, etc.)
+- `EXCEPTION_COLORS` map for per-level exception coloring (bold first line, faint backtrace)
+- `Thread.current[:legion_context]` support for wire protocol fields (task_id, conversation_id, chain_id)
+- Redaction applied to exception stdout output when redaction is enabled
+- Method context (`legion_log_method`) included in structured exception events
+- `AsyncWriter::LogEntry` carries `segments` and `method_ctx` for thread-local propagation to writer thread
+- `Builder#resolve_lex_tag` and `#build_runner_trace` extracted from `text_format`
+
+### Changed
+- `Helper#log` returns `TaggedLogger` instead of `Logger.new` (shared output, one async thread)
+- `Helper#log_name`/`gem_name`/`gem_spec` replace `log_lex_name`/`lex_gem_name`/`gem_spec_for_lex` with multi-prefix resolution
+- `gem_name` and `gem_spec` memoized per instance
+- `COMPONENT_REGEX` in Methods expanded from 5 to 18 component types
+- `build_writer_context` reads `Thread.current[:legion_log_segments]` instead of stale `@lex_segments` ivar
+- `Builder#output` delegates to `set_log` (was parallel implementation)
+- `Builder#caller_locations` allocates single frame instead of full stack
+- Unknown log level strings default to INFO instead of DEBUG
+- `EventBuilder#legion_versions` and `#resolve_gem_spec` memoized
+- `EXCEPTION_PRIORITY` extracted to frozen constant in Methods (was inline hash allocation per call)
+- `text_format` and `json_format` in Builder read thread-locals for segments and method context
+
+### Fixed
+- `fire_log_writer` rescue no longer references undefined `routing_key` variable
+- Splunk auth header in `http_transport` — `apply_auth` receives actual URI instead of always evaluating against `URI('/')`
+- `TaggedLogger#initialize` accepts `**_opts` splat for unexpected settings keys
+- `TaggedLogger#trace` guards nil `size` to prevent `TypeError` on `caller_locations`
+
+### Removed
+- `TaggedLogger#runner_exception` (runner business logic, not logging concern)
+- `TaggedLogger#log_exception` (use `Helper#handle_exception` instead)
+- `Builder#log_level` no-op `@log = log` self-assignment
+
 ## [1.4.2] - 2026-03-28
 
 ### Added
@@ -135,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/Gemfile

@@ -11,5 +11,6 @@ group :test do
   gem 'rspec'
   gem 'rspec_junit_formatter'
   gem 'rubocop'
+  gem 'rubocop-legion'
   gem 'simplecov'
 end

data/lib/legion/logging/async_writer.rb

@@ -1,42 +1,62 @@
 # frozen_string_literal: true
 
+require_relative 'methods'
+
 module Legion
   module Logging
     class AsyncWriter
-      LogEntry = ::Data.define(:level, :message, :writer_context)
+      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
@@ -47,17 +67,27 @@ module Legion
       def consume
         loop do
           entry = @queue.pop
-          break if entry == SHUTDOWN
+          break if entry.nil? || entry == SHUTDOWN
 
           write_entry(entry)
         end
       end
 
       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
         warn("legion-log-writer error: #{e.message} (#{e.backtrace&.first})")
+      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
@@ -69,14 +99,19 @@ module Legion
         nil
       end
 
+      def accepting?
+        @state_mutex.synchronize { @accepting }
+      end
+
       def fire_writer(entry)
         ctx = entry.writer_context
         event = ctx[:event]
         level = ctx[:level]
         lex_name = event[:lex] || 'core'
-        component = event.dig(:caller, :file).to_s[%r{/(runners|actors|transport|helpers|builders)/}, 1] || 'unknown'
+        component = event.dig(:caller, :file).to_s[Legion::Logging::Methods::COMPONENT_REGEX, 1] || 'unknown'
         routing_key = "legion.logging.log.#{level}.#{lex_name}.#{component}"
         Legion::Logging.log_writer.call(event, routing_key: routing_key)
+        Legion::Logging::Hooks.fire(level, entry.message, event) if defined?(Legion::Logging::Hooks)
       rescue StandardError => e
         warn("legion-log-writer writer error: #{e.message}")
       end

data/lib/legion/logging/builder.rb

@@ -27,6 +27,10 @@ module Legion
             thread:    Thread.current.object_id
           }
           entry[:pid] = ::Process.pid if include_pid
+          segments = Thread.current[:legion_log_segments]
+          entry[:segments] = segments if segments
+          method_ctx = Thread.current[:legion_log_method]
+          entry[:method] = method_ctx if method_ctx
           "#{::JSON.generate(entry)}\n"
         rescue StandardError => e
           warn("Legion::Logging::Builder#json_format formatter failed: #{e.message}")
@@ -36,24 +40,12 @@ module Legion
 
       def text_format(include_pid: false, **options)
         log.formatter = proc do |severity, datetime, _progname, msg|
-          options[:lex_name] = if options.key?(:lex_segments)
-                                 options[:lex_segments].map { |s| "[#{s}]" }.join
-                               elsif options.key?(:lex) && !options[:lex].nil?
-                                 "[#{options[:lex]}]"
-                               end
-          unless options[:lex_name].nil?
-            loc  = caller_locations[4]
-            path = loc.to_s.split('/').last(2)
-            runner_trace = {
-              type:        path[0],
-              file:        File.basename(loc.path, '.*'),
-              function:    loc.base_label,
-              line_number: loc.lineno
-            }
-          end
+          lex_name = resolve_lex_tag(options)
+          runner_trace = Thread.current[:legion_log_caller] || build_runner_trace if lex_name
+
           string = "[#{datetime}]"
           string.concat("[#{::Process.pid}]") if include_pid
-          string.concat(options[:lex_name]) unless options[:lex_name].nil?
+          string.concat(lex_name) if lex_name
           if runner_trace.is_a?(Hash) && (options[:extended] || severity == 'debug')
             string.concat("[#{runner_trace[:type]}:#{runner_trace[:file]}:#{runner_trace[:function]}:#{runner_trace[:line_number]}]")
           end
@@ -62,17 +54,35 @@ module Legion
         end
       end
 
+      def resolve_lex_tag(options)
+        segments = Thread.current[:legion_log_segments]
+        tag = if segments
+                segments.map { |s| "[#{s}]" }.join
+              elsif options.key?(:lex_segments)
+                options[:lex_segments].map { |s| "[#{s}]" }.join
+              elsif options.key?(:lex) && !options[:lex].nil?
+                "[#{options[:lex]}]"
+              end
+
+        method_ctx = Thread.current[:legion_log_method]
+        tag = "#{tag}{#{method_ctx}}" if tag && method_ctx
+        tag
+      end
+
+      def build_runner_trace(loc = caller_locations(6, 1)&.first)
+        return unless loc
+
+        path = loc.to_s.split('/').last(2)
+        {
+          type:        path[0],
+          file:        File.basename(loc.path, '.*'),
+          function:    loc.base_label,
+          line_number: loc.lineno
+        }
+      end
+
       def output(**options)
-        if options[:log_file] && options[:log_stdout] != false
-          path = prepare_log_path(options[:log_file])
-          require_relative 'multi_io'
-          io = MultiIO.new($stdout, File.open(path, 'a'))
-          @log = ::Logger.new(io)
-        elsif options[:log_file]
-          @log = ::Logger.new(prepare_log_path(options[:log_file]))
-        else
-          @log = ::Logger.new($stdout)
-        end
+        set_log(logfile: options[:log_file], log_stdout: options[:log_stdout])
       end
 
       def log
@@ -80,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)
@@ -102,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
@@ -120,29 +139,50 @@ module Legion
                       if level.is_a? Integer
                         level
                       else
-                        0
+                        1
                       end
                     end
-        @log = log
       end
 
       def async?
         (@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,32 @@ 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
 
       class << self
         def build(level:, message:, lex: nil, lex_segments: nil, context: nil, category: nil, caller_offset: 2)
@@ -187,12 +213,18 @@ module Legion
         end
 
         def resolve_gem_spec(name)
-          [name, "lex-#{name}", "legion-#{name}"].each do |candidate|
-            return Gem::Specification.find_by_name(candidate)
+          cache = (@gem_spec_cache ||= {})
+          return cache[name] if cache.key?(name)
+
+          spec = nil
+          ["lex-#{name}", "legion-#{name}", name].each do |candidate|
+            spec = Gem::Specification.find_by_name(candidate)
+            break
           rescue Gem::MissingSpecError
             next
           end
-          nil
+
+          GEM_SPEC_CACHE_MUTEX.synchronize { cache[name] = spec }
         end
 
         def strip_ansi(str)
@@ -254,9 +286,13 @@ module Legion
         end
 
         def legion_versions
-          Gem::Specification
-            .select { |s| s.name.start_with?('legion-', 'lex-') }
-            .to_h { |s| [s.name, s.version.to_s] }
+          @legion_versions ||= Gem::Specification
+                               .select { |s| s.name.start_with?('legion-', 'lex-') }
+                               .to_h do |s|
+            [s.name,
+             s.version.to_s]
+          end
+                               .freeze
         end
 
         def truncate_bytes(str, max)
@@ -297,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