legion-logging 1.2.8 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 518026f9d08e58ddd2a6c1f0727a92be011321202d5cd788db339678e65338af
-  data.tar.gz: 0d08f35ebdc02e31399e5ab4579c9e71a7aa1691bb549cd79eeda355715f45c8
+  metadata.gz: b61c337aaf2f09bc9cf2ae34db008430f232d7d585044fa4cf813162f1db6b69
+  data.tar.gz: 453b54b4571861800273a345dd1c7142b742daaddb05a3a30e8b48d21c5c7575
 SHA512:
-  metadata.gz: 7dd496ca2596dfd8a5a4e35093752f88c1e37924ce1595e5c53c4c7c8ab4c53f3e872104dcc9fd35fb1c3fa268ed72d1619c38ed0878336bc6a2fadfa76e08be
-  data.tar.gz: d39e9736a4738b87bb07204008d7c46b21a504022421b4612e480fcd7b74998fe946e10748f0cc9653e60d77c56a6d9fadef811d11e51fc9c4852d3b2a9beeee
+  metadata.gz: a819edf335d1c5c38bb431ac5368af501ffefed138c31a32f55bde4eb2ce155b98c26ef9973c798b98ced32330e48e887be3a711d86db6c011651c5ff7c485af
+  data.tar.gz: d1bf28077c9fc1de289cbf936ce0cea292ea6ca380dc4d6ee2294d8db0a30fac22ef571794b9c1881d8f743b32dae783ffc772114250d50dfaf2e54afa046d3b

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-03-22
+
+### Added
+- `Legion::Logging::AsyncWriter`: non-blocking log writer using `SizedQueue` and a dedicated background thread
+- Async mode enabled by default on `setup(async: true)` — log calls return immediately
+- Configurable buffer size via `Legion::Settings[:logging, :async, :buffer_size]` (default: 10,000)
+- Back-pressure: callers block when buffer is full (preserves log completeness)
+- `fatal` calls always bypass the async queue (synchronous write)
+- `async?`, `start_async_writer`, `stop_async_writer` methods on both singleton and Logger instances
+- Hook callbacks (`on_error`, `on_warn`) fire on the writer thread; event context captured on caller thread
+
+### Changed
+- `setup` method now accepts `async:` keyword (default: `true`)
+- `Logger.new` now accepts `async:` keyword (default: `false` for backward compatibility)
+
 ## [1.2.8] - 2026-03-22
 
 ### Changed

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.2.5
+**Version**: 1.3.0
 
 ## Installation
 
@@ -31,6 +31,23 @@ Legion::Logging.error('something went wrong')
 Legion::Logging.fatal('critical failure')
 ```
 
+### Async Logging
+
+By default, `setup` enables async logging — log calls push to a background writer thread and return immediately. Fatal calls always bypass the queue and write synchronously.
+
+```ruby
+# Async is on by default
+Legion::Logging.setup(level: 'info')
+
+# Disable async (synchronous mode)
+Legion::Logging.setup(level: 'info', async: false)
+
+# Configure buffer size via Legion::Settings
+# Legion::Settings[:logging, :async, :buffer_size] = 20_000
+```
+
+When the buffer is full, callers block until the writer drains — this preserves log completeness. Use `Legion::Logging.stop_async_writer` during shutdown to flush and stop the writer thread.
+
 ### Structured JSON Output
 
 Pass `format: :json` to disable colorization and emit machine-parseable JSON log lines:

data/lib/legion/logging/async_writer.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    class AsyncWriter
+      LogEntry = ::Data.define(:level, :message, :hook_context)
+      SHUTDOWN = :shutdown
+
+      def initialize(logger, buffer_size: 10_000)
+        @logger = logger
+        @queue  = SizedQueue.new(buffer_size)
+        @thread = nil
+      end
+
+      def start
+        return if @thread&.alive?
+
+        drain
+        @thread = Thread.new { consume }
+        @thread.name = 'legion-log-writer'
+        @thread.abort_on_exception = false
+      end
+
+      def stop(timeout: 2)
+        return unless @thread&.alive?
+
+        begin
+          @queue.push(SHUTDOWN, true)
+        rescue ThreadError
+          # Queue full — fall through to join/kill + drain
+        end
+        @thread.join(timeout)
+        @thread.kill if @thread&.alive?
+        drain
+      end
+
+      def push(entry)
+        @queue.push(entry)
+      end
+
+      def alive?
+        @thread&.alive? || false
+      end
+
+      private
+
+      def consume
+        loop do
+          entry = @queue.pop
+          break if entry == SHUTDOWN
+
+          write_entry(entry)
+        end
+      end
+
+      def write_entry(entry)
+        @logger.send(entry.level, entry.message)
+        fire_hooks(entry) if entry.hook_context
+      rescue StandardError => e
+        warn("legion-log-writer error: #{e.message} (#{e.backtrace&.first})")
+      end
+
+      def drain
+        until @queue.empty?
+          entry = @queue.pop(true)
+          write_entry(entry) unless entry == SHUTDOWN
+        end
+      rescue ThreadError
+        nil
+      end
+
+      def fire_hooks(entry)
+        ctx = entry.hook_context
+        Legion::Logging::Hooks.fire(ctx[:level], ctx[:event])
+      rescue StandardError => e
+        warn("legion-log-writer hook error: #{e.message}")
+      end
+    end
+  end
+end

data/lib/legion/logging/builder.rb

@@ -125,6 +125,25 @@ module Legion
                     end
         @log = log
       end
+
+      def async?
+        (@async == true && @async_writer&.alive?) || false
+      end
+
+      def start_async_writer(buffer_size: 10_000)
+        require_relative 'async_writer'
+        stop_async_writer if @async_writer&.alive?
+        @async_writer = AsyncWriter.new(log, buffer_size: buffer_size)
+        @async_writer.start
+        @async = true
+      end
+
+      def stop_async_writer
+        writer = @async_writer
+        @async_writer = nil
+        @async = false
+        writer&.stop
+      end
     end
   end
 end

data/lib/legion/logging/logger.rb

@@ -11,7 +11,7 @@ module Legion
       include Legion::Logging::Methods
       include Legion::Logging::Builder
 
-      def initialize(level: 'info', log_file: nil, log_stdout: nil, lex: nil, trace: false, extended: false, trace_size: 4, format: :text, **opts) # rubocop:disable Metrics/ParameterLists
+      def initialize(level: 'info', log_file: nil, log_stdout: nil, lex: nil, trace: false, extended: false, trace_size: 4, format: :text, async: false, **opts) # rubocop:disable Metrics/ParameterLists
         @lex = lex
         set_log(logfile: log_file, log_stdout: log_stdout)
         log_level(level)
@@ -21,6 +21,7 @@ module Legion
         @trace_enabled = trace
         @trace_size = trace_size
         @extended = extended
+        start_async_writer if async
       end
     end
   end

data/lib/legion/logging/methods.rb

@@ -22,7 +22,12 @@ module Legion
 
         message = yield if message.nil? && block_given?
         message = Rainbow(message).blue if @color
-        log.debug(message)
+        writer = @async_writer
+        if writer&.alive?
+          writer.push(AsyncWriter::LogEntry.new(level: :debug, message: message, hook_context: nil))
+        else
+          log.debug(message)
+        end
       end
 
       def info(message = nil)
@@ -30,7 +35,12 @@ module Legion
 
         message = yield if message.nil? && block_given?
         message = Rainbow(message).green if @color
-        log.info(message)
+        writer = @async_writer
+        if writer&.alive?
+          writer.push(AsyncWriter::LogEntry.new(level: :info, message: message, hook_context: nil))
+        else
+          log.info(message)
+        end
       end
 
       def warn(message = nil)
@@ -39,8 +49,14 @@ module Legion
         message = yield if message.nil? && block_given?
         raw = message
         message = Rainbow(message).yellow if @color
-        log.warn(message)
-        fire_hooks(:warn, raw)
+        writer = @async_writer
+        if writer&.alive?
+          ctx = build_hook_context(:warn, raw)
+          writer.push(AsyncWriter::LogEntry.new(level: :warn, message: message, hook_context: ctx))
+        else
+          log.warn(message)
+          fire_hooks(:warn, raw)
+        end
       end
 
       def error(message = nil)
@@ -49,8 +65,14 @@ module Legion
         message = yield if message.nil? && block_given?
         raw = message
         message = Rainbow(message).red if @color
-        log.error(message)
-        fire_hooks(:error, raw)
+        writer = @async_writer
+        if writer&.alive?
+          ctx = build_hook_context(:error, raw)
+          writer.push(AsyncWriter::LogEntry.new(level: :error, message: message, hook_context: ctx))
+        else
+          log.error(message)
+          fire_hooks(:error, raw)
+        end
       end
 
       def fatal(message = nil)
@@ -66,7 +88,12 @@ module Legion
       def unknown(message = nil)
         message = yield if message.nil? && block_given?
         message = Rainbow(message).purple if @color
-        log.unknown(message)
+        writer = @async_writer
+        if writer&.alive?
+          writer.push(AsyncWriter::LogEntry.new(level: :unknown, message: message, hook_context: nil))
+        else
+          log.unknown(message)
+        end
       end
 
       def runner_exception(exc, **opts)
@@ -86,6 +113,23 @@ module Legion
 
       private
 
+      def build_hook_context(level, message)
+        return nil unless Legion::Logging::Hooks.enabled?
+        return nil if Legion::Logging::Hooks.hooks[level].empty?
+
+        lex_val  = instance_variable_defined?(:@lex) ? @lex : nil
+        lex_segs = instance_variable_defined?(:@lex_segments) ? @lex_segments : nil
+
+        event = Legion::Logging::EventBuilder.build(
+          level:         level,
+          message:       message,
+          lex:           lex_val,
+          lex_segments:  lex_segs,
+          caller_offset: 4
+        )
+        { level: level, event: event }
+      end
+
       def fire_hooks(level, message)
         return unless Legion::Logging::Hooks.enabled?
         return if Legion::Logging::Hooks.hooks[level].empty?

data/lib/legion/logging/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Logging
-    VERSION = '1.2.8'
+    VERSION = '1.3.0'
   end
 end

data/lib/legion/logging.rb

@@ -6,6 +6,7 @@ require 'legion/logging/methods'
 require 'legion/logging/builder'
 require 'legion/logging/hooks'
 require 'legion/logging/event_builder'
+require 'legion/logging/async_writer'
 
 require 'json'
 require 'logger'
@@ -26,12 +27,22 @@ module Legion
 
       attr_reader :color
 
-      def setup(level: 'info', format: :text, **options)
+      def setup(level: 'info', 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?))
+        if async
+          buffer = if defined?(Legion::Settings)
+                     Legion::Settings[:logging, :async, :buffer_size] || 10_000
+                   else
+                     10_000
+                   end
+          start_async_writer(buffer_size: buffer)
+        else
+          stop_async_writer
+        end
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-logging
 version: !ruby/object:Gem::Version
-  version: 1.2.8
+  version: 1.3.0
 platform: ruby
 authors:
 - Esity
@@ -57,6 +57,7 @@ files:
 - README.md
 - legion-logging.gemspec
 - lib/legion/logging.rb
+- lib/legion/logging/async_writer.rb
 - lib/legion/logging/builder.rb
 - lib/legion/logging/event_builder.rb
 - lib/legion/logging/hooks.rb