legion-logging 1.5.5 → 1.5.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd5e1bffbdc433aedb24653ea515080063cb456de0c5a0fd5a57cdbff91d371d
-  data.tar.gz: 0b015f1b0c5d12511f231bfa32325e2ebcc41ca902b92d8293bdcf6359d8a7ac
+  metadata.gz: '037790df316dd01a4f090a1d02a4b07fab65feac2d0c70a501d949d57fd45276'
+  data.tar.gz: af6fda1d1af5fe004fe8e4b76c225aa997f4075aed19b8d557f4090cec9e7770
 SHA512:
-  metadata.gz: 0bad8e3a31fb86de2b1a2749457b506e7042606e7e060813a0adcaf81f2d0afdf8998e3ba57692fabe5814ab7efcb3dcadfb9c8e985a77b6f3c4e44aedcccf35
-  data.tar.gz: 83475ff76aae03a25c24e1b464695f68ef6b4514309e6290485e513066f3d9f4ff9367e2b87e087f89dd1f1b6b3fafa4176ca5fcae226224859356d23189a80f
+  metadata.gz: 659f1952bc1c331c74528153276b9a593eb1d775c67fbd57797434e78f1f016612ca2a2e0322ab6ad041f7101efede0a94e803c388dedf96608727431b5c303c
+  data.tar.gz: 9f4150366ac4f64da3b1c14a429058820de2cb639dd810974f6448a5ca78fa7e32d5c13f23100eb0d21802143091df232b0ffd89263313f00b7df1355341b547

data/CHANGELOG.md

@@ -1,5 +1,99 @@
 # Legion::Logging Changelog
 
+## [1.5.19] - 2026-10-29
+
+### Changed
+- Document the complete async contract: bounded backpressure, producer snapshots, worker-side preparation, lifecycle deadlines, reentrant logging, and explicit synchronous boundaries (#22).
+- Correct writer callback signatures and describe delivery acknowledgement limits, retained Shipper retries, and raw Logger compatibility (#22).
+
+## [1.5.18] - 2026-10-29
+
+### Fixed
+- Preserve producer-side raw Logger admission and message/progname normalization: accepted `with_level` records are not filtered again, and a block's nil result reaches the formatter unchanged (#22).
+- Pass captured producer time to raw Logger formatters instead of the later worker dispatch time (#22).
+
+## [1.5.17] - 2026-10-29
+
+### Fixed
+- Make async regression cleanup nil-safe so setup failures are not replaced by secondary errors while releasing worker gates (#22; PR #23 review feedback).
+
+## [1.5.16] - 2026-10-29
+
+### Fixed
+- Preserve producer timestamps in text/JSON output and producer thread IDs in JSON, including queued standard Logger calls (#22).
+- Snapshot mutable raw Logger messages and context before enqueueing so later caller mutation cannot change accepted output.
+
+## [1.5.15] - 2026-10-29
+
+### Changed
+- Move normal log and both exception APIs' formatting, redaction, event enrichment, fingerprinting, and envelope preparation onto the async worker (#22).
+- Capture producer call sites, timestamps, thread/session context, and shallow input snapshots before enqueueing; preserve component-level overrides during worker output.
+- Honor configurable forwarding levels at `logging.transport.log_levels`, retaining warn/error/fatal by default and avoiding duplicate synchronous event construction.
+
+### Fixed
+- Avoid implicitly loading Settings from logging and shipping; early redaction defaults no longer hide custom patterns loaded later.
+
+## [1.5.14] - 2026-10-29
+
+### Fixed
+- Serialize logger-owned lifecycle transitions so concurrent startup cannot orphan a writer and discard its accepted backlog (#22).
+- Reject contending lifecycle calls without blocking callbacks behind their own shutdown join.
+- Retry retained shipping batches on a subsequent shutdown call after a previous delivery failure.
+
+## [1.5.13] - 2026-10-29
+
+### Fixed
+- Keep startup and shutdown draining on the writer, including accepted work without a running consumer; apply shutdown deadlines without synchronous fallback (#22).
+- Retain timed-out workers and queues, reject writes after shutdown, and avoid joining the writer from its own callback.
+- Stop the existing writer before reconfiguring outputs; a failed shutdown leaves the configuration intact instead of opening a synchronous bypass.
+
+## [1.5.12] - 2026-10-29
+
+### Fixed
+- Route opt-in MethodTracer output through configured async logging instead of direct producer-thread stdout writes (#22).
+- Keep failed shipping diagnostics out of the forwarding pipeline to avoid logging-to-shipper feedback loops, and add explicit HTTP write timeouts.
+- Clarify that direct transport/export APIs, MultiIO, and hook dispatch are synchronous primitives; their async callers own scheduling.
+
+## [1.5.11] - 2026-10-29
+
+### Fixed
+- Move threshold-triggered and explicit Shipper delivery onto one background worker; `flush(timeout:)` waits for delivery without performing sink IO on its caller (#22).
+- Bound accepted and in-flight shipping events with `logging.shipper.buffer_size` (default 10,000), preserve failed batches for retry, and wake the worker for flush/shutdown instead of sleeping through requests.
+
+## [1.5.10] - 2026-10-29
+
+### Fixed
+- Prevent writer callbacks and hooks from waiting on their own full queue: nested messages are written locally on the writer without recursively forwarding them (#22).
+- Preserve nested exception events as local JSON lines and bypass recursive formatting when necessary, without growing an overflow queue or dropping nested messages.
+
+## [1.5.9] - 2026-10-29
+
+### Fixed
+- Keep the standard Ruby Logger interface returned by `log`, including `add`, `log`, and raw append, on the configured async writer; preserve producer context for Sinatra/APM consumers (#22).
+- Route instance tracing through async logging and raise `ClosedQueueError` for rejected async writes instead of silently performing producer-thread IO.
+
+## [1.5.8] - 2026-10-29
+
+### Fixed
+- Queue structured exception publication for both `log_exception` and Helper `handle_exception`, keeping exception-writer callbacks off producer threads when async logging is enabled (#22).
+- Preserve captured exception metadata and callback envelopes while retaining synchronous publication for explicit synchronous logging.
+
+## [1.5.7] - 2026-10-29
+
+### Changed
+- Document bounded, lossless-in-process queue backpressure as the intentional async saturation policy: producers wait rather than silently dropping logs or growing the queue without a bound (#22).
+- Correct async fatal routing and the buffer-size configuration example.
+
+## [1.5.6] - 2026-06-01
+
+### Added
+- `task_id:`, `conv_id:`, `request_id:` optional kwargs on all log level methods (`.debug`, `.info`, `.warn`, `.error`, `.fatal`, `.unknown`) in both `Methods` and `TaggedLogger`
+- Text formatter appends context ID (`conv_id` or `task_id` fallback) as `{conv_12345}` after the method segment in the prefix
+- Text formatter inserts `request_id=<value>` between severity and message when present
+- JSON formatter includes `conversation_id` and `request_id` fields when present
+- `AsyncWriter::LogEntry` carries `conv_id` and `request_id` for correct propagation to the writer thread
+- Thread-local `legion_log_conv_id` and `legion_log_request_id` for block-scoped context without per-call kwargs
+
 ## [1.5.5] - 2026-05-27
 
 ### Fixed

data/CLAUDE.md

@@ -2,45 +2,53 @@
 
 Structured logging framework for LegionIO. Provides colorized console output (Rainbow), structured JSON logging, and a consistent interface across all Legion gems and extensions.
 
-**GitHub**: https://github.com/LegionIO/legion-logging
-**Version**: 1.5.3
-
 ## Architecture
 
 ```
 Legion::Logging (singleton module)
 ├── Methods           # debug, info, warn, error, fatal, unknown; log_exception
 ├── Builder           # Output destination, log level, formatter, async: keyword
-├── AsyncWriter       # Non-blocking SizedQueue-backed writer thread
+├── AsyncWriter       # Bounded, backpressured SizedQueue-backed writer thread
+├── OutputLogger      # Queues standard Logger add/log/<< calls
 ├── Hooks             # Callback registry for fatal/error/warn events
 ├── EventBuilder      # Structured event payload + fingerprint for dedup
 ├── Helper            # Injectable log mixin for LEX extensions
 ├── TaggedLogger      # Prepends structured tags to each message
 ├── CategoryRegistry  # Named log categories with expected_fields
 ├── SIEMExporter      # PHI-redacting SIEM export (Splunk HEC, ELK)
-├── Shipper           # Buffered forwarding (FileTransport, HttpTransport)
+├── Shipper           # Bounded batch-delivery worker (file/HTTP transports)
 ├── Redactor          # PII/PHI + secret pattern redaction (opt-in)
-└── MultiIO           # Write to multiple destinations simultaneously
+└── MultiIO           # Synchronous, sequential writes to multiple destinations
 
 # Module-level writer lambdas (pluggable forwarding slots)
-Legion::Logging.log_writer       # ->(event, routing_key:) {}
+Legion::Logging.log_writer       # ->(event, routing_key:, headers:, properties:) {}
 Legion::Logging.exception_writer # ->(event, routing_key:, headers:, properties:) {}
 ```
 
 ## Key Patterns
 
 - **Singleton module** — `class << self`; called directly: `Legion::Logging.info("msg")`
-- **Async by default** — `setup` enables async logging; fatal bypasses queue. Buffer size via `Settings[:logging][:async][:buffer_size]` (default 10,000). Back-pressure blocks callers when full.
+- **Async by default** — `setup` queues all levels, including fatal, plus structured exception publication and raw Logger calls. Buffer size via `Settings[:logging][:async][:buffer_size]` (default 10,000 entries, not bytes). Saturation blocks producers rather than dropping logs or growing the queue without bound.
 - **Structured JSON** — `format: :json` outputs machine-parseable JSON lines (disables color)
+- **Producer/worker boundary** — Producers evaluate message blocks and capture caller/context plus shallow snapshots. Formatting, event enrichment, fingerprinting, and publication run on the worker. Nested payload objects are not deep-copied. Built-in output retains producer time/thread; raw Logger output retains admission, normalized payload, and formatter time.
+- **Lifecycle** — `stop_async_writer(timeout: 2)` closes admission and drains on the worker; timeout or lifecycle contention returns false. No caller-thread drain or synchronous rejection fallback. Stopped async loggers raise `ClosedQueueError` until restart or explicit `setup(async: false)`. Setup file operations remain synchronous.
+- **Delivery semantics** — Successful shutdown means processing finished, not durable delivery or external acknowledgement. AsyncWriter diagnoses failures locally without retry; Shipper retains failed batches for retry.
 - **Helper mixin** — `Legion::Logging::Helper` injects into LEX extensions; derives tags from `segments`, `lex_filename`, or class name
 - **Writer lambdas** — `log_writer` and `exception_writer` are module-level lambda slots for forwarding to external systems (AMQP, etc.). Default no-ops.
 - **Redactor** — Opt-in (`logging.redaction.enabled: true`). Patterns: SSN, phone, MRN, DOB, Vault tokens, JWTs, bearer tokens, lease IDs. Guards against Settings recursive init.
 - **Hook callbacks** — `on_fatal`, `on_error`, `on_warn` register procs; gated by `enable_hooks!`/`disable_hooks!`; fire on async writer thread
+- **Reentrant logging** — Callback/hook logs stay local on the worker without recursively forwarding or waiting on its own queue. Nested exception events and recursive formatter diagnostics use local JSON lines.
+- **Forwarding levels** — `logging.transport.log_levels` accepts strings/symbols; absent or empty lists default to warn/error/fatal. Settings guards use defaults while Settings is unloaded rather than initializing it.
+- **Synchronous APIs** — `MultiIO`, direct transport delivery, SIEM export, and direct hook dispatch remain synchronous. Shipper filtering/redaction run on its caller; bounded batch delivery runs on its worker.
 - **EventBuilder** — Structured event hashes from log context (caller, exception, lex identity). `fingerprint` produces MD5 for dedup.
 
 ## Role in LegionIO
 
 Foundational gem — dependency of `legion-cache`, `legion-data`, and `LegionIO`. First module initialized during `Legion::Service` startup.
 
----
-**Maintained By**: Matthew Iverson (@Esity)
+## Backtrace Limit
+
+- `settings[:logging][:backtrace_limit]` — `nil` = full trace, `0` = suppress entirely, `N` = cap at N frames
+- Per-call override: `log_exception(err, backtrace_limit: 5)`
+- Read at runtime via `Legion::Settings.dig(:logging, :backtrace_limit)` after checking Settings is loaded; otherwise use the default without triggering initialization.
+

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.5.2
+**Version**: 1.5.19
 
 ## Installation
 
@@ -33,7 +33,7 @@ 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.
+By default, `setup` enables async logging: log calls enqueue output for a background writer, including fatal messages. Async does not mean wait-free. The queue holds at most 10,000 entries by default, and producers wait for capacity when it fills.
 
 ```ruby
 # Async is on by default
@@ -43,10 +43,30 @@ Legion::Logging.setup(level: 'info')
 Legion::Logging.setup(level: 'info', async: false)
 
 # Configure buffer size via Legion::Settings
-# Legion::Settings[:logging, :async, :buffer_size] = 20_000
+# 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.
+Bounded backpressure is intentional: saturation blocks callers rather than dropping logs or allowing unbounded memory growth. A stalled destination can therefore stall producers once the queue fills. Buffer capacity limits queued entries, not their total byte size, and does not guarantee delivery across process termination.
+
+Use `Legion::Logging.stop_async_writer(timeout: 2)` during shutdown. It closes admission and asks the worker to drain accepted entries, returning `true` only after that worker exits. A deadline expiry returns `false` without killing the worker or draining on the caller; release the blocked destination and retry shutdown. Calling shutdown from a writer callback requests closure but returns `false` rather than joining itself.
+
+A successful stop means queued entries have been processed, not that a sink durably stored them or an external service acknowledged them. AsyncWriter reports sink/callback failures locally and does not automatically retry them. The Shipper's retained-batch retry behavior is separate.
+
+Stopped async loggers reject new writes until explicitly restarted or configured with `setup(async: false)`. Reconfiguration stops the previous worker before replacing its output. `setup(shutdown_timeout: 2, ...)` returns `false` if that drain times out and does not change the existing output; it does not silently enter synchronous mode.
+
+Lifecycle transitions are serialized per logger. A competing setup/start/stop returns `false` instead of creating overlapping workers or blocking a callback behind its own shutdown. Retry the control operation after the active transition completes.
+
+Configuration is a synchronous control path: opening or closing owned log files can still block in `setup`. Shutdown deadlines bound worker drain/join, not every filesystem operation.
+
+Producers evaluate message blocks and capture caller/context plus shallow snapshots of strings, arrays, hashes, and exceptions. The worker performs formatting, redaction, structured-event enrichment, fingerprinting, and envelope construction. Nested payload objects are not deep-copied. Explicit caller tracing and application-provided message/settings methods can still perform producer-side work.
+
+Text and JSON timestamps represent enqueue time, not time spent waiting for a destination. JSON thread IDs identify the producer. Standard Logger calls use the same shallow snapshot policy for messages and context; custom raw Logger formatters receive the producer timestamp. The worker preserves producer-side `with_level` admission and already-resolved message/progname values, including a block's nil result.
+
+Forwarding defaults to warn/error/fatal. Set `logging.transport.log_levels` to an array of strings or symbols to change which locally emitted levels reach `log_writer` and Hooks; absent or empty lists retain the defaults. Library-owned Settings lookups use defaults while Settings is unloaded rather than triggering initialization.
+
+The standard Ruby Logger interface returned by `Legion::Logging.log` also queues output in async mode, including `add`, `log`, and `<<`. Instance tracing uses the same async path. If an async writer is unavailable or rejects an entry during shutdown, logging raises `ClosedQueueError` rather than falling back to synchronous IO. Explicit synchronous mode retains direct output.
+
+Logs generated by a writer callback or hook are written locally on that worker rather than queued behind themselves or forwarded recursively. Nested exception events and recursive formatter diagnostics use local JSON lines. This keeps bounded backpressure for producers without allowing the sole consumer to deadlock on its own queue.
 
 ### Structured JSON Output
 
@@ -60,12 +80,26 @@ This is useful for log aggregation pipelines (Elasticsearch, Splunk, etc.).
 
 ### Multi-Output IO
 
-`Legion::Logging::MultiIO` writes to multiple destinations simultaneously — for example, stdout and a file at the same time. Used internally by the Builder when `log_file` is set alongside console output.
+`Legion::Logging::MultiIO` writes to destinations sequentially—for example, stdout followed by a file. It is a synchronous IO primitive used by the async writer, not a parallel executor. A slow destination delays that worker and can eventually cause queue backpressure.
+
+Opt-in `MethodTracer` output uses the configured logging queue rather than writing directly to the traced application's stdout. Hook dispatch is synchronous on its invoking thread; normal async logging invokes hooks on the writer, not on producers.
+
+### Buffered Shipping
+
+Explicitly require `legion/logging/shipper` and enable `logging.shipper.enabled` to use the file or HTTP batch shipper. `Shipper.ship(event)` starts its worker automatically and never performs threshold-triggered delivery on the producer. Filtering and redaction still run on the calling thread; batch delivery runs on the worker. Set `logging.shipper.transport` to `file` or `http`.
+
+Defaults: `batch_size: 100`, `flush_interval: 5` seconds, and `buffer_size: 10_000`. The capacity includes in-flight events; producers wait when it is full. Failed batches remain queued in order for retry.
+
+`Shipper.flush(timeout: 5)` requests worker delivery and waits up to the supplied deadline; it returns `false` on timeout or delivery failure. `Shipper.stop(timeout: 5)` wakes and joins the worker without moving delivery onto the caller. A timeout retains the worker and accepted events; check the return value before assuming delivery completed. If shutdown exits after a delivery failure, retrying `stop` starts a drainer for the retained batch.
+
+`FileTransport.ship_batch` and `HttpTransport.ship_batch` are intentionally synchronous delivery primitives; use `Shipper.ship` for producer-side asynchronous shipping. Sink failures are reported locally to stderr instead of being forwarded back into the failing shipper.
 
 ### SIEM Export
 
 `Legion::Logging::SIEMExporter` provides PHI-redacting export helpers for security event pipelines:
 
+`export_to_splunk` is an explicitly synchronous request/response API. Use the HTTP Shipper for asynchronous delivery. Both HTTP implementations configure 5-second connection and 10-second read/write timeouts; these are phase timeouts, not a total request deadline.
+
 ```ruby
 # Redact PHI patterns (SSN, phone, MRN, DOB) from a string
 clean = Legion::Logging::SIEMExporter.redact_phi(raw_message)
@@ -96,7 +130,7 @@ end
 
 ### Exception Logging
 
-`log_exception` provides a single call for complete exception logging with component context. It writes a human-readable exception line through the configured logger and publishes a structured exception event when an `exception_writer` is configured.
+`log_exception` provides a single call for complete exception logging with component context. It writes a human-readable exception line and publishes a structured exception event when an `exception_writer` is configured. With async logging enabled, both output and exception publication run on the writer thread; Helper `handle_exception` uses the same publication path. Bounded queue backpressure still applies.
 
 ```ruby
 begin
@@ -112,7 +146,7 @@ rescue StandardError => e
 end
 ```
 
-The synchronous log line includes the full Ruby backtrace. Legion does not truncate it to a fixed frame count or replace the tail with `... N more`, because the missing frames are often the useful part of production failures.
+The human-readable log line includes the full Ruby backtrace unless `backtrace_limit` is configured. Legion does not replace the tail with `... N more`.
 
 Structured exception events include:
 
@@ -126,15 +160,15 @@ Structured exception events include:
 
 ### Writer Lambdas
 
-`log_writer` and `exception_writer` are pluggable lambda slots that replace the old Hooks system. Assign them to forward events to external systems:
+`log_writer` and `exception_writer` are pluggable lambda slots for forwarding events to external systems. They coexist with Hooks; normal async logging invokes both on the writer thread:
 
 ```ruby
 Legion::Logging.exception_writer = lambda do |payload, routing_key:, headers:, properties:|
   publish_to_amqp(payload, routing_key:, headers:, properties:)
 end
 
-Legion::Logging.log_writer = lambda do |context, routing_key:|
-  publish_log(context, routing_key:)
+Legion::Logging.log_writer = lambda do |context, routing_key:, headers:, properties:|
+  publish_log(context, routing_key:, headers:, properties:)
 end
 ```
 

data/lib/legion/logging/async_writer.rb

@@ -1,15 +1,32 @@
 # frozen_string_literal: true
 
+require 'json'
 require_relative 'methods'
 
 module Legion
   module Logging
     class AsyncWriter
-      LogEntry = ::Data.define(:level, :message, :writer_context, :segments, :method_ctx, :caller_trace)
-      SHUTDOWN = :shutdown
+      LogEntry = ::Data.define(:level, :message, :writer_context, :segments, :method_ctx, :caller_trace,
+                               :conv_id, :request_id, :exchange_id, :chain_id, :force)
+      EventEntry = ::Data.define(:callback, :event, :options)
+      CallEntry = ::Data.define(:receiver, :method_name, :arguments, :keywords, :context)
+      OutputEntry = ::Data.define(:severity, :message, :progname, :segments, :method_ctx, :caller_trace,
+                                  :conv_id, :request_id, :exchange_id, :chain_id, :origin)
+      THREAD_KEYS = %i[
+        legion_log_segments legion_log_method legion_log_caller
+        legion_log_conv_id legion_log_request_id legion_log_exchange_id legion_log_chain_id
+      ].freeze
+      CALL_THREAD_KEYS = (THREAD_KEYS + %i[legion_context legion_session_context legion_log_origin]).freeze
 
       attr_reader :logger
 
+      def self.snapshot_value(value:)
+        return value if value.nil? || value.frozen?
+        return value unless value.is_a?(String) || value.is_a?(Array) || value.is_a?(Hash) || value.is_a?(Exception)
+
+        value.dup.freeze
+      end
+
       def initialize(logger, buffer_size: 10_000)
         @logger = logger
         @buffer_size = buffer_size
@@ -19,36 +36,55 @@ module Legion
         @accepting = true
       end
 
+      # rubocop:disable Naming/PredicateMethod
       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
+        @state_mutex.synchronize do
+          return @accepting if @thread&.alive?
+
+          if @queue.closed?
+            queue = SizedQueue.new(@buffer_size)
+            queue << @queue.pop(true) until @queue.empty?
+            @queue = queue
+          end
+          @accepting = true
+          @thread = Thread.new { consume(queue: @state_mutex.synchronize { @queue }) }
+          @thread.name = 'legion-log-writer'
+          @thread.abort_on_exception = false
+        end
+        true
       end
 
-      # rubocop:disable Naming/PredicateMethod
       def stop(timeout: 2)
-        @state_mutex.synchronize { @accepting = false }
-
-        unless @thread&.alive?
-          drain
-          @thread = nil
-          return true
+        deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + timeout if timeout
+        thread = @state_mutex.synchronize do
+          @accepting = false
+          @queue.close
+          if !@thread&.alive? && !@queue.empty?
+            @thread = Thread.new { consume(queue: @state_mutex.synchronize { @queue }) }
+            @thread.name = 'legion-log-writer'
+            @thread.abort_on_exception = false
+          end
+          @thread
         end
+        return true unless thread
+        return false if Thread.current.equal?(thread)
 
-        @queue.close
-        timeout ? @thread.join(timeout) : @thread.join
-        return false if @thread&.alive?
+        remaining = [deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC), 0].max if deadline
+        thread.join(remaining)
+        return false if thread.alive?
 
-        @thread = nil
+        @state_mutex.synchronize { @thread = nil if @thread.equal?(thread) }
         true
       end
 
       def push(entry)
+        if current_thread?
+          return write_reentrant_entry(entry) unless @preparing
+
+          write_entry(entry)
+          return true
+        end
+
         return false unless accepting?
 
         @queue.push(entry)
@@ -62,41 +98,101 @@ module Legion
         @thread&.alive? || false
       end
 
+      def current_thread?
+        Thread.current.equal?(@thread)
+      end
+
       private
 
-      def consume
+      def consume(queue:)
         loop do
-          entry = @queue.pop
-          break if entry.nil? || entry == SHUTDOWN
+          entry = queue.pop
+          break if entry.nil?
 
           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
+      def write_entry(entry, forward: true)
+        previous_preparing = @preparing
+        @preparing = entry.is_a?(CallEntry)
+        if @preparing
+          write_call_entry(entry)
+          return
+        end
+
+        if entry.is_a?(EventEntry)
+          callback_origin = Thread.current[:legion_log_origin]
+          Thread.current[:legion_log_origin] = nil
+          entry.callback.call(entry.event, **entry.options)
+          return
+        end
+
+        with_entry_context(entry) do
+          if entry.is_a?(OutputEntry)
+            write_output_entry(entry)
+          else
+            if entry.force
+              formatter = @logger.formatter || ::Logger::Formatter.new
+              severity = entry.level == :unknown ? 'ANY' : entry.level.to_s.upcase
+              @logger << formatter.call(severity, Time.now, nil, entry.message)
+            else
+              @logger.send(entry.level, entry.message)
+            end
+            fire_writer(entry) if forward && entry.writer_context
+          end
+        end
       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
+        @preparing = previous_preparing
+        Thread.current[:legion_log_origin] = callback_origin if entry.is_a?(EventEntry)
       end
 
-      def drain
-        until @queue.empty?
-          entry = @queue.pop(true)
-          write_entry(entry) unless entry == SHUTDOWN
+      def write_output_entry(entry)
+        return @logger << entry.message if entry.severity.nil?
+
+        severity = @logger.send(:format_severity, entry.severity)
+        @logger << @logger.send(:format_message, severity, entry.origin[:timestamp].getlocal, entry.progname, entry.message)
+      end
+
+      def write_reentrant_entry(entry)
+        previous = @reentrant_write
+        @reentrant_write = true
+        if previous || entry.is_a?(EventEntry)
+          event = entry.is_a?(EventEntry) ? entry.event : { message: entry.message.to_s }
+          @logger << "#{::JSON.generate(event)}\n"
+        else
+          write_entry(entry, forward: false)
         end
-      rescue ThreadError
-        nil
+        true
+      ensure
+        @reentrant_write = previous
+      end
+
+      def write_call_entry(entry)
+        previous = entry.context.map { |key, _| [key, Thread.current[key]] }
+        entry.context.each { |key, value| Thread.current[key] = value }
+        entry.receiver.public_send(entry.method_name, *entry.arguments, **entry.keywords)
+      ensure
+        previous&.each { |key, value| Thread.current[key] = value }
+      end
+
+      def with_entry_context(entry)
+        prev = THREAD_KEYS.map { |k| [k, Thread.current[k]] }
+        previous_origin = Thread.current[:legion_log_origin]
+        Thread.current[:legion_log_origin] = entry.origin if entry.is_a?(OutputEntry)
+        Thread.current[:legion_log_segments]    = entry.segments
+        Thread.current[:legion_log_method]      = entry.method_ctx
+        Thread.current[:legion_log_caller]      = entry.caller_trace
+        Thread.current[:legion_log_conv_id]     = entry.conv_id
+        Thread.current[:legion_log_request_id]  = entry.request_id
+        Thread.current[:legion_log_exchange_id] = entry.exchange_id
+        Thread.current[:legion_log_chain_id]    = entry.chain_id
+        yield
+      ensure
+        prev&.each { |k, v| Thread.current[k] = v }
+        Thread.current[:legion_log_origin] = previous_origin
       end
 
       def accepting?
@@ -104,6 +200,7 @@ module Legion
       end
 
       def fire_writer(entry)
+        previous_origin = Thread.current[:legion_log_origin]
         ctx = entry.writer_context
         event = ctx[:event]
         level = ctx[:level]
@@ -112,10 +209,13 @@ module Legion
         routing_key = "legion.logging.log.#{level}.#{lex_name}.#{component}"
         headers    = Legion::Logging.send(:build_log_headers, event, component, level)
         properties = Legion::Logging.send(:build_log_properties, level)
+        Thread.current[:legion_log_origin] = nil
         Legion::Logging.log_writer.call(event, routing_key: routing_key, headers: headers, properties: properties)
         Legion::Logging::Hooks.fire(level, entry.message, event) if defined?(Legion::Logging::Hooks)
       rescue StandardError => e
         warn("legion-log-writer writer error: #{e.message}")
+      ensure
+        Thread.current[:legion_log_origin] = previous_origin
       end
     end
   end