legion-logging 1.5.6 → 1.5.21

data/lib/legion/logging/methods.rb

@@ -13,6 +13,7 @@ module Legion
         exchanges|queues|messages|data|builders|tools|adapters|engines|
         formatters|parsers|middleware)/
       }x
+      LOGGING_PATH = __dir__
 
       def trace(raw_message = nil, size: @trace_size, log_caller: true)
         return unless @trace_enabled
@@ -25,18 +26,24 @@ module Legion
         elsif log_caller
           message.concat Rainbow(caller_locations[0..size]).cyan.underline
         end
-        log.unknown(message)
+        unknown(message)
       end
 
       def debug(message = nil, task_id: nil, conv_id: nil, request_id: nil, exchange_id: nil, chain_id: nil, **_ctx)
         return unless log.level < 1
 
         message = yield if message.nil? && block_given?
+        if async_producer?
+          return defer_log_call(receiver: self, method_name: :debug, arguments: [message],
+                                keywords: { task_id: task_id, conv_id: conv_id, request_id: request_id,
+                                            exchange_id: exchange_id, chain_id: chain_id })
+        end
+
         raw = maybe_redact(message)
         formatted = format_message_for_level(:debug, raw)
         with_context_ids(task_id: task_id, conv_id: conv_id, request_id: request_id,
                          exchange_id: exchange_id, chain_id: chain_id) do
-          write_async_or_sync(:debug, formatted, raw)
+          write_async_or_sync(:debug, formatted, raw, writer_context: build_writer_context(:debug, raw))
         end
       end
 
@@ -44,11 +51,17 @@ module Legion
         return unless log.level < 2
 
         message = yield if message.nil? && block_given?
+        if async_producer?
+          return defer_log_call(receiver: self, method_name: :info, arguments: [message],
+                                keywords: { task_id: task_id, conv_id: conv_id, request_id: request_id,
+                                            exchange_id: exchange_id, chain_id: chain_id })
+        end
+
         raw = maybe_redact(message)
         formatted = format_message_for_level(:info, raw)
         with_context_ids(task_id: task_id, conv_id: conv_id, request_id: request_id,
                          exchange_id: exchange_id, chain_id: chain_id) do
-          write_async_or_sync(:info, formatted, raw)
+          write_async_or_sync(:info, formatted, raw, writer_context: build_writer_context(:info, raw))
         end
       end
 
@@ -56,6 +69,12 @@ module Legion
         return unless log.level < 3
 
         message = yield if message.nil? && block_given?
+        if async_producer?
+          return defer_log_call(receiver: self, method_name: :warn, arguments: [message],
+                                keywords: { task_id: task_id, conv_id: conv_id, request_id: request_id,
+                                            exchange_id: exchange_id, chain_id: chain_id })
+        end
+
         raw = maybe_redact(message)
         formatted = format_message_for_level(:warn, raw)
         with_context_ids(task_id: task_id, conv_id: conv_id, request_id: request_id,
@@ -68,6 +87,12 @@ module Legion
         return unless log.level < 4
 
         message = yield if message.nil? && block_given?
+        if async_producer?
+          return defer_log_call(receiver: self, method_name: :error, arguments: [message],
+                                keywords: { task_id: task_id, conv_id: conv_id, request_id: request_id,
+                                            exchange_id: exchange_id, chain_id: chain_id })
+        end
+
         raw = maybe_redact(message)
         formatted = format_message_for_level(:error, raw)
         with_context_ids(task_id: task_id, conv_id: conv_id, request_id: request_id,
@@ -80,6 +105,12 @@ module Legion
         return unless log.level < 5
 
         message = yield if message.nil? && block_given?
+        if async_producer?
+          return defer_log_call(receiver: self, method_name: :fatal, arguments: [message],
+                                keywords: { task_id: task_id, conv_id: conv_id, request_id: request_id,
+                                            exchange_id: exchange_id, chain_id: chain_id })
+        end
+
         raw = maybe_redact(message)
         formatted = format_message_for_level(:fatal, raw)
         with_context_ids(task_id: task_id, conv_id: conv_id, request_id: request_id,
@@ -90,11 +121,17 @@ module Legion
 
       def unknown(message = nil, task_id: nil, conv_id: nil, request_id: nil, exchange_id: nil, chain_id: nil, **_ctx)
         message = yield if message.nil? && block_given?
+        if async_producer?
+          return defer_log_call(receiver: self, method_name: :unknown, arguments: [message],
+                                keywords: { task_id: task_id, conv_id: conv_id, request_id: request_id,
+                                            exchange_id: exchange_id, chain_id: chain_id })
+        end
+
         raw = maybe_redact(message)
         formatted = format_message_for_level(:unknown, raw)
         with_context_ids(task_id: task_id, conv_id: conv_id, request_id: request_id,
                          exchange_id: exchange_id, chain_id: chain_id) do
-          write_async_or_sync(:unknown, formatted, raw)
+          write_async_or_sync(:unknown, formatted, raw, writer_context: build_writer_context(:unknown, raw))
         end
       end
 
@@ -103,6 +140,11 @@ module Legion
         level = level.to_sym
         message = yield if message.nil? && block_given?
         return if message.nil?
+        if async_producer?
+          return defer_log_call(receiver: self, method_name: :emit_tagged, arguments: [level, message],
+                                keywords: { segments: segments, method_ctx: method_ctx, task_id: task_id, conv_id: conv_id,
+                                            request_id: request_id, exchange_id: exchange_id, chain_id: chain_id })
+        end
 
         raw = maybe_redact(message)
         formatted = format_message_for_level(level, raw)
@@ -110,23 +152,21 @@ module Legion
         with_tagged_context(segments, method_ctx) do
           with_context_ids(task_id: task_id, conv_id: conv_id, request_id: request_id,
                            exchange_id: exchange_id, chain_id: chain_id) do
-            ctx = %i[warn error fatal].include?(level) ? build_writer_context(level, raw) : nil
+            ctx = build_writer_context(level, raw)
             writer = @async_writer
             caller_trace = capture_runner_trace_for_async
-            if writer&.alive?
-              writer.push(AsyncWriter::LogEntry.new(
-                            level: level, message: formatted, writer_context: ctx,
-                            segments: Thread.current[:legion_log_segments],
-                            method_ctx: Thread.current[:legion_log_method],
-                            caller_trace: caller_trace,
-                            conv_id: Thread.current[:legion_log_conv_id],
-                            request_id: Thread.current[:legion_log_request_id],
-                            exchange_id: Thread.current[:legion_log_exchange_id],
-                            chain_id: Thread.current[:legion_log_chain_id]
-                          ))
+            if @async || writer
+              push_async_entry(entry: AsyncWriter::LogEntry.new(force: true, level: level, message: formatted, writer_context: ctx,
+                                                                segments: Thread.current[:legion_log_segments],
+                                                                method_ctx: Thread.current[:legion_log_method],
+                                                                caller_trace: caller_trace,
+                                                                conv_id: Thread.current[:legion_log_conv_id],
+                                                                request_id: Thread.current[:legion_log_request_id],
+                                                                exchange_id: Thread.current[:legion_log_exchange_id],
+                                                                chain_id: Thread.current[:legion_log_chain_id]))
             else
               with_caller_trace(caller_trace) { write_forced(level, formatted) }
-              fire_log_writer(level, raw) if ctx
+              fire_log_writer(level, raw, event: ctx[:event]) if ctx
             end
           end
         end
@@ -141,6 +181,14 @@ module Legion
                         gem_name: nil, lex_version: nil, gem_path: nil,
                         source_code_uri: nil, handled: false, payload_summary: nil,
                         task_id: nil, backtrace_limit: nil, **extra)
+        if async_producer?
+          return defer_log_call(receiver: self, method_name: :log_exception, arguments: [exception],
+                                keywords: { level: level, lex: lex, component_type: component_type, gem_name: gem_name,
+                                            lex_version: lex_version, gem_path: gem_path, source_code_uri: source_code_uri,
+                                            handled: handled, payload_summary: payload_summary, task_id: task_id,
+                                            backtrace_limit: backtrace_limit, **extra })
+        end
+
         level = level.to_sym if level.respond_to?(:to_sym)
         # 1. Log human-readable line + backtrace via async writer
         msg = exception.respond_to?(:message) ? exception.message : exception.to_s
@@ -170,7 +218,7 @@ module Legion
         event = Legion::Logging::Redactor.redact(event) if defined?(Legion::Logging::Redactor)
 
         # 4. Publish rich event via exception_writer
-        publish_exception_event(event, level)
+        publish_exception(event: event, level: level)
       rescue StandardError => e
         if respond_to?(:log) && log.respond_to?(:warn)
           log.warn("Failed to publish structured exception event: #{e.class}: #{e.message}")
@@ -179,6 +227,45 @@ module Legion
         end
       end
 
+      def publish_exception(event:, level:)
+        lex_name = event[:lex] || 'core'
+        component = event[:component_type] || :unknown
+        options = {
+          routing_key: "legion.logging.exception.#{level}.#{lex_name}.#{component}",
+          headers:     build_exception_headers(event, component, level),
+          properties:  build_exception_properties(event, level)
+        }
+        callback = Legion::Logging.exception_writer
+        writer = @async_writer
+        return push_async_entry(entry: AsyncWriter::EventEntry.new(callback: callback, event: event, options: options)) if @async || writer
+
+        callback.call(event, **options)
+      end
+
+      def async_producer?
+        (@async == true || !@async_writer.nil?) && !@async_writer&.current_thread?
+      end
+
+      def defer_log_call(receiver:, method_name:, arguments:, keywords:)
+        return false unless async_producer?
+        raise ClosedQueueError, 'async logging writer is unavailable' unless @async_writer&.alive?
+
+        context = Legion::Logging::AsyncWriter::CALL_THREAD_KEYS.to_h do |key|
+          [key, Legion::Logging::AsyncWriter.snapshot_value(value: Thread.current[key])]
+        end
+        location = caller_locations(1, 16).find do |frame|
+          path = frame.absolute_path || frame.path
+          !path.start_with?(LOGGING_PATH)
+        end
+        context[:legion_log_origin] = { location: location, timestamp: Time.now.utc, thread: Thread.current.object_id }
+        push_async_entry(entry: Legion::Logging::AsyncWriter::CallEntry.new(
+          receiver: receiver, method_name: method_name,
+          arguments: arguments.map { |value| Legion::Logging::AsyncWriter.snapshot_value(value: value) },
+          keywords: keywords.transform_values { |value| Legion::Logging::AsyncWriter.snapshot_value(value: value) },
+          context: context
+        ))
+      end
+
       def thread(kvl: false, **_opts)
         if kvl
           "thread=#{Thread.current.object_id}"
@@ -192,8 +279,9 @@ module Legion
       def resolve_backtrace_limit(explicit_limit)
         return explicit_limit unless explicit_limit.nil?
         return nil unless defined?(Legion::Settings)
+        return nil unless Legion::Settings.respond_to?(:loaded?) ? Legion::Settings.loaded? : true
 
-        Legion::Settings[:logging][:backtrace_limit]
+        Legion::Settings.dig(:logging, :backtrace_limit)
       end
 
       def build_exception_log_message(exception, msg, backtrace_limit)
@@ -291,30 +379,35 @@ module Legion
       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,
-                                 conv_id:        Thread.current[:legion_log_conv_id],
-                                 request_id:     Thread.current[:legion_log_request_id],
-                                 exchange_id:    Thread.current[:legion_log_exchange_id],
-                                 chain_id:       Thread.current[:legion_log_chain_id]
-                               ))
-          return if queued
+        if @async || writer
+          return push_async_entry(entry: AsyncWriter::LogEntry.new(force: false, 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,
+                                                                   conv_id:        Thread.current[:legion_log_conv_id],
+                                                                   request_id:     Thread.current[:legion_log_request_id],
+                                                                   exchange_id:    Thread.current[:legion_log_exchange_id],
+                                                                   chain_id:       Thread.current[:legion_log_chain_id]))
         end
 
         with_caller_trace(caller_trace) do
           log.public_send(level, formatted_message)
-          fire_log_writer(level, raw_message) if writer_context
+          fire_log_writer(level, raw_message, event: writer_context[:event]) if writer_context
         end
       end
 
+      def push_async_entry(entry:) # rubocop:disable Naming/PredicateMethod
+        writer = @async_writer
+        raise ClosedQueueError, 'async logging writer is unavailable' unless writer&.alive? && writer.push(entry)
+
+        true
+      end
+
       def capture_runner_trace_for_async
-        build_runner_trace(caller_locations(5, 1)&.first)
+        location = Thread.current[:legion_log_origin]&.[](:location) || caller_locations(5, 1)&.first
+        build_runner_trace(location)
       end
 
       def with_caller_trace(caller_trace)
@@ -350,19 +443,35 @@ module Legion
         }
       end
 
-      def publish_exception_event(event, level)
-        lex_name = event[:lex] || 'core'
-        comp     = event[:component_type] || :unknown
-        routing_key = "legion.logging.exception.#{level}.#{lex_name}.#{comp}"
-        headers     = build_exception_headers(event, comp, level)
-        properties  = build_exception_properties(event, level)
-        Legion::Logging.exception_writer.call(event, routing_key: routing_key, headers: headers, properties: properties)
+      def forward_level?(level)
+        forwardable_log_levels.include?(level.to_sym)
+      end
+
+      # Levels whose logs build a structured event for the transport bus / Hooks.
+      # Runtime override: logging.transport.log_levels (Array of level names).
+      # Falls back to Settings.default[:forward_log_levels] (warn/error/fatal).
+      def forwardable_log_levels
+        default = Legion::Logging::Settings::DEFAULT_FORWARD_LOG_LEVELS
+        return default unless defined?(Legion::Settings)
+        return default unless Legion::Settings.respond_to?(:loaded?) ? Legion::Settings.loaded? : true
+
+        configured = Legion::Settings.dig(:logging, :transport, :log_levels)
+        return default unless configured.is_a?(Array) && !configured.empty?
+
+        configured.map { |lvl| lvl.to_s.to_sym }
+      rescue StandardError => e
+        Kernel.warn("Legion::Logging forwarding configuration failed: #{e.message}")
+        default
       end
 
       def build_writer_context(level, message)
+        # Cheap ivar/flag checks first: when nothing consumes forwarded events
+        # (the common case) we return before touching Settings, keeping the
+        # hot debug/info path allocation- and lookup-free.
         has_writer = !Legion::Logging.instance_variable_get(:@log_writer).nil?
         has_hooks = defined?(Legion::Logging::Hooks) && Legion::Logging::Hooks.enabled?
         return nil unless has_writer || has_hooks
+        return nil unless forward_level?(level)
 
         lex_val  = instance_variable_defined?(:@lex) ? @lex : nil
         lex_segs = Thread.current[:legion_log_segments] || (instance_variable_defined?(:@lex_segments) ? @lex_segments : nil)
@@ -377,17 +486,7 @@ module Legion
         { level: level, event: event }
       end
 
-      def fire_log_writer(level, message)
-        lex_val  = instance_variable_defined?(:@lex) ? @lex : nil
-        lex_segs = Thread.current[:legion_log_segments] || (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
-        )
+      def fire_log_writer(level, message, event:)
         lex_name = event[:lex] || 'core'
         component = event.dig(:caller, :file).to_s[COMPONENT_REGEX, 1] || 'unknown'
         routing_key = "legion.logging.log.#{level}.#{lex_name}.#{component}"

data/lib/legion/logging/multi_io.rb

@@ -3,8 +3,10 @@
 module Legion
   module Logging
     class MultiIO
+      attr_reader :targets
+
       def initialize(*targets)
-        @targets = targets.flatten
+        @targets = targets.flatten.freeze
       end
 
       def write(message)

data/lib/legion/logging/output_logger.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Legion
+  module Logging
+    # Keeps the standard Logger interface used by Sinatra/APM on the async queue.
+    class OutputLogger < ::Logger
+      attr_accessor :async_writer
+
+      def add(severity, message = nil, progname = nil)
+        writer = @async_writer
+        return super unless writer && !writer.current_thread?
+
+        severity ||= UNKNOWN
+        return true if @logdev.nil? || severity < level
+
+        progname ||= @progname
+        if message.nil?
+          if block_given?
+            message = yield
+          else
+            message = progname
+            progname = @progname
+          end
+        end
+        enqueue_output(severity: severity, message: message, progname: progname)
+      end
+      alias log add
+
+      def <<(message)
+        writer = @async_writer
+        return super unless writer && !writer.current_thread?
+
+        enqueue_output(severity: nil, message: message, progname: nil)
+      end
+
+      private
+
+      def enqueue_output(severity:, message:, progname:) # rubocop:disable Naming/PredicateMethod
+        entry = Legion::Logging::AsyncWriter::OutputEntry.new(
+          severity:     severity,
+          message:      Legion::Logging::AsyncWriter.snapshot_value(value: message),
+          progname:     Legion::Logging::AsyncWriter.snapshot_value(value: progname),
+          segments:     Legion::Logging::AsyncWriter.snapshot_value(value: Thread.current[:legion_log_segments]),
+          method_ctx:   Legion::Logging::AsyncWriter.snapshot_value(value: Thread.current[:legion_log_method]),
+          caller_trace: Legion::Logging::AsyncWriter.snapshot_value(value: Thread.current[:legion_log_caller]),
+          conv_id:      Legion::Logging::AsyncWriter.snapshot_value(value: Thread.current[:legion_log_conv_id]),
+          request_id:   Legion::Logging::AsyncWriter.snapshot_value(value: Thread.current[:legion_log_request_id]),
+          exchange_id:  Legion::Logging::AsyncWriter.snapshot_value(value: Thread.current[:legion_log_exchange_id]),
+          chain_id:     Legion::Logging::AsyncWriter.snapshot_value(value: Thread.current[:legion_log_chain_id]),
+          origin:       { timestamp: Time.now.utc, thread: Thread.current.object_id }
+        )
+        raise ClosedQueueError, 'async logging writer is unavailable' unless @async_writer.alive? && @async_writer.push(entry)
+
+        true
+      end
+    end
+  end
+end

data/lib/legion/logging/redactor.rb

@@ -74,6 +74,9 @@ module Legion
         end
 
         def all_patterns
+          return PATTERNS unless defined?(Legion::Settings)
+          return PATTERNS unless Legion::Settings.respond_to?(:loaded?) ? Legion::Settings.loaded? : true
+
           @all_patterns ||= build_patterns
         end
 
@@ -85,8 +88,6 @@ module Legion
         end
 
         def custom_patterns
-          return {} unless defined?(Legion::Settings)
-
           raw = Legion::Settings.dig(:logging, :redactor, :custom_patterns)
           return {} unless raw.is_a?(Hash)
 

data/lib/legion/logging/rotating_file.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    # Every cooperating writer for a path must use the same limits. The stable
+    # lock file coordinates separate devices/processes and must not be removed.
+    class RotatingFile
+      BUFFER_BYTES = 64 * 1024
+
+      attr_reader :file_path, :max_bytes, :max_files
+
+      def initialize(path:, max_bytes:, max_files:)
+        unless max_bytes.is_a?(Integer) && max_bytes.positive? && max_files.is_a?(Integer) && max_files.positive?
+          raise ArgumentError, 'max_bytes and max_files must be positive integers'
+        end
+
+        @file_path = File.expand_path(path)
+        @max_bytes = max_bytes
+        @max_files = max_files
+        @mutex = Mutex.new
+        @archive_pattern = /\A#{Regexp.escape(File.basename(@file_path))}\.([1-9]\d*)\z/
+        @needs_normalization = true
+        @closed = false
+        synchronize_path { normalize_locked }
+      rescue StandardError
+        begin
+          @io&.close
+        ensure
+          @lock_io&.close
+        end
+        raise
+      end
+
+      def write(*messages)
+        raise ArgumentError, 'wrong number of arguments (given 0, expected 1+)' if messages.empty?
+
+        synchronize_path do
+          normalize_locked if @needs_normalization
+          next @io.write(*messages) unless @regular
+
+          trim_file(path: @file_path) if @io.size > @max_bytes
+          messages.sum { |message| write_message(message: message.to_s) }
+        end
+      end
+
+      def flush
+        @mutex.synchronize do
+          raise IOError, 'closed stream' if @closed
+
+          @io&.flush
+        end
+        self
+      end
+
+      def sync = true # rubocop:disable Naming/PredicateMethod -- IO#sync interface
+
+      def sync=(_value); end
+
+      def close
+        @mutex.synchronize do
+          return if @closed
+
+          @closed = true
+          begin
+            @io&.close
+          ensure
+            @lock_io.close if @lock_io && !@lock_io.closed?
+          end
+        end
+      end
+
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
+      def size
+        synchronize_path { @io.size }
+      end
+
+      def rotate!
+        synchronize_path do
+          normalize_locked if @needs_normalization
+          rotate_locked!
+        end
+      end
+
+      def configure(max_bytes:, max_files:)
+        unless max_bytes.is_a?(Integer) && max_bytes.positive? && max_files.is_a?(Integer) && max_files.positive?
+          raise ArgumentError, 'max_bytes and max_files must be positive integers'
+        end
+
+        synchronize_path do
+          @max_bytes = max_bytes
+          @max_files = max_files
+          @needs_normalization = true
+          normalize_locked
+        end
+        self
+      end
+
+      private
+
+      def open_file
+        file = File.new(@file_path, 'ab')
+        file.sync = true
+        file
+      end
+
+      def synchronize_path
+        @mutex.synchronize do
+          raise IOError, 'closed stream' if @closed
+
+          lock_path if @lock_io || File.file?(@file_path) || !File.exist?(@file_path)
+          begin
+            reopen_if_replaced
+            if @regular && !@lock_io
+              @io.close
+              @io = nil
+              lock_path
+              reopen_if_replaced
+            end
+            yield
+          ensure
+            begin
+              # Idle devices must not pin archives after another writer unlinks
+              # them. Release every regular data-file FD before the path lock.
+              if @regular && @io
+                @io.close
+                @io = nil
+              end
+            ensure
+              @lock_io&.flock(File::LOCK_UN)
+            end
+          end
+        end
+      end
+
+      def lock_path
+        # flock locks are inherited across fork with the open file description.
+        # Reopen in the child so its lock competes with its parent's lock.
+        if @lock_io && @lock_pid != ::Process.pid
+          @lock_io.close
+          @lock_io = nil
+        end
+        @lock_io ||= File.open("#{@file_path}.lock", File::RDWR | File::CREAT, 0o600)
+        @lock_pid = ::Process.pid
+        raise IOError, 'could not acquire log rotation lock' unless @lock_io.flock(File::LOCK_EX)
+      end
+
+      def reopen_if_replaced
+        if @io
+          current = @io.stat
+          target = File.stat(@file_path) if File.exist?(@file_path)
+          return if target && current.dev == target.dev && current.ino == target.ino
+        end
+
+        replace_io
+      end
+
+      def replace_io
+        previous = @io
+        @io = open_file
+        current = @io.stat
+        @regular = current.file?
+        @needs_normalization ||= @file_dev != current.dev || @file_ino != current.ino
+        @file_dev = current.dev
+        @file_ino = current.ino
+        previous&.close
+      end
+
+      def normalize_locked
+        if @regular
+          trim_file(path: @file_path)
+          directory = File.dirname(@file_path)
+          Dir.each_child(directory) do |name|
+            match = @archive_pattern.match(name)
+            next unless match
+
+            archive = File.join(directory, name)
+            if match[1].to_i > @max_files
+              File.unlink(archive)
+            else
+              trim_file(path: archive)
+            end
+          end
+        end
+        @needs_normalization = false
+      end
+
+      def trim_file(path:)
+        stat = File.stat(path)
+        return unless stat.file? && stat.size > @max_bytes
+
+        # Move the retained tail toward the beginning without a temporary file
+        # or a full-file allocation. Forward copies cannot overwrite unread data.
+        File.open(path, 'r+b') do |file|
+          source_offset = file.size - @max_bytes
+          offset = 0
+          buffer = +''.b
+          while offset < @max_bytes
+            file.seek(source_offset + offset)
+            chunk = file.read([BUFFER_BYTES, @max_bytes - offset].min, buffer)
+            raise IOError, 'log file changed while trimming its retained tail' if chunk.nil? || chunk.empty?
+
+            file.seek(offset)
+            offset += file.write(chunk)
+          end
+          file.truncate(@max_bytes)
+        end
+      end
+
+      def write_message(message:)
+        offset = 0
+        available = @max_bytes - @io.size
+        while offset < message.bytesize
+          unless available.positive?
+            rotate_locked!
+            available = @max_bytes
+          end
+          length = [message.bytesize - offset, available, BUFFER_BYTES].min
+          chunk = offset.zero? && length == message.bytesize ? message : message.byteslice(offset, length)
+          written = @io.write(chunk)
+          offset += written
+          available -= written
+        end
+        offset
+      end
+
+      def rotate_locked! # rubocop:disable Naming/PredicateMethod -- Renames files; false means a nonregular destination.
+        return false unless @regular
+
+        Rotation.shift_files(path: @file_path, max_files: @max_files)
+        replace_io
+        @needs_normalization = false
+        true
+      end
+    end
+  end
+end