legion-logging 1.5.6 → 1.5.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff7f461a7f614eb2480b2ef960992d463c7e26ee8cae0283d9f381e859e28c8d
-  data.tar.gz: a5bc8f5e7fd81d72ef8cc4ae98225e677645581340611103ac99807bb2f6c691
+  metadata.gz: c94ba448ab05d8309fd27afcd2672364c2d843ed277036f640cf798715fe97af
+  data.tar.gz: 146fa61ef555986daadc1e94996e53e936b34c47a71b8647fdad3c240808e107
 SHA512:
-  metadata.gz: 006d30ed434deec409edd42ca5b5ac9245a4657dc8fc6280fc8b982c704d9ef1b1aee299bf6f905698a382f84cbc5ca3205adfd4691f2010d6aec0dea818a986
-  data.tar.gz: f6288442156789fd8bbb9858910a3deb01fffea277341c2c0e5b8288ee3cab7150b07b4c348faad78b3645f808823f536a856140fc1c5ce4935b4b805d13caea
+  metadata.gz: 4391e8e771c4d747469af379d33b1b3f397f60426e6b750dbdc1a6de16e3fa88085abefe9a36760d058aed2ffef559f473e94a37f5bf1a1eb006f058fc3ac1db
+  data.tar.gz: e2d141523b19fe6f0c300d97b62fc28d6aeced3e9db8a8c276564cfd0fef5acdb0398aa1eac1542803df34ca12de171326103224739b1c3f500fda7e8dfe5a53

data/CHANGELOG.md

@@ -1,5 +1,119 @@
 # Legion::Logging Changelog
 
+## [1.5.21] - 2026-10-30
+
+### Changed
+- Enforce a hard retained-byte cap for managed log files: split oversized writes before the per-file limit, trim existing oversized files to their newest bytes, and immediately prune excess archives.
+- Capture eligible inherited stdout/stderr through bounded kernel pipes, including raw descriptor and child-process writes; full pipes backpressure producers instead of allocating an unbounded byte queue.
+- Coordinate same-path file writers with persistent zero-byte lock sidecars and close regular data descriptors between operations so idle devices cannot pin deleted archives.
+- Fail closed on rotation or drain errors rather than append beyond the cap. The bound covers managed file contents, not filesystem metadata, snapshots, external writers, hardlink aliases, or externally retained descriptors.
+
+### Fixed
+- Include downstream raw-stdio drains in `stop_async_writer` deadlines, including synchronous and file-only module logging.
+- Preserve capture after pre-drain timeouts; wait for worker cleanup before reporting successful disable, and prevent inherited children from controlling parent workers or silently changing their retention policy.
+- Preserve existing instance loggers across process-capture disable/re-enable and close destinations if fail-closed descriptor reattachment itself fails.
+
+## [1.5.20] - 2026-10-29
+
+### Added
+- Size-based log rotation, on by default (100 MiB x 5 archives), configurable via `logging.rotation`
+  (`enabled`, `max_size_mb`, `max_files`, `stdio`) or `setup(rotation: {...})`; `rotation: false` disables it
+- `Legion::Logging::RotatingFile`: self-rotating append-mode device used for `log_file:`; reopens if another
+  process rotated the path
+- `Legion::Logging::StdioRotator`: rotates the file behind stdout/stderr when a supervisor (launchd
+  `StandardOutPath`, systemd `append:`) redirected them to an append-mode regular file, using `IO#reopen` so
+  raw stderr output follows the new file. Checks are logger-write-driven, not a hard disk quota.
+
+### Fixed
+- Preserve current async OutputLogger routing, lifecycle locks, shutdown deadlines, and forwarding settings while integrating rotation (PR #21).
+- Honor instance logger rotation overrides and opt-out; rotate distinct stderr files independently, including when stdout is a pipe.
+- Preserve nested Settings lookup guards, normalize invalid limits, and reopen remembered paths after external rotation.
+- Keep non-regular devices untouched and report rotation failures without discarding the incoming message.
+
+## [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

data/CLAUDE.md

@@ -2,45 +2,55 @@
 
 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
+└── Rotation          # RotatingFile (log_file) + shared StdioRotator (redirected stdout/stderr)
 
 # 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.
+- **Rotation** — Hard managed-content cap: 100 MiB per file plus five archives (600 MiB/path). `RotatingFile` splits writes, trims oversized existing files, prunes excess archives, and coordinates same-path/same-policy writers through a persistent zero-byte `.lock`. Regular data FDs close between operations. Eligible append-mode inherited stdout/stderr become bounded pipes drained by dedicated capped sinks, including raw-only and child writes; saturation blocks, errors fail closed. `stop_async_writer` drains both layers under one deadline, including sync/file-only module logging; call it after final raw writes. Capture is process-wide; disable only with quiescent producers. Pre-drain timeout keeps capture active; final cleanup failure/timeout requires restart. Instance loggers survive disable/re-enable. Forked children cannot control parent workers or change their policy. File contents are bounded, not filesystem metadata/snapshots, external writers/aliases, or externally held/inherited descriptors; a volume-level guarantee needs an OS quota.
 
 ## 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.21
 
 ## Installation
 
@@ -31,9 +31,74 @@ Legion::Logging.error('something went wrong')
 Legion::Logging.fatal('critical failure')
 ```
 
+### Log Rotation
+
+Managed file contents have a hard byte bound: **100 MiB per file with five archives** by
+default (`legion.log`, `legion.log.1` through `legion.log.5`), or **600 MiB per managed path**.
+The bound is `max_bytes * (max_files + 1)`, where `max_bytes` is `max_size_mb * 1024 * 1024`,
+rounded down to a positive byte count. Separate stdout, stderr, and configured log paths
+each have their own retention budget.
+
+This covers `log_file:` and eligible stdout/stderr files inherited from launchd, systemd
+`append:`, or shell `>>` redirects. Only append-mode regular inherited files qualify;
+pipes, terminals, and non-append redirects (`>`) remain unchanged. Eligible stderr is captured
+independently even when stdout is a pipe. The actual descriptors become bounded kernel pipes,
+so raw writes and inherited child-process writes also pass through the capped sinks without
+needing a logger call. Full pipes block producers; there is no unbounded Ruby byte queue.
+Raw syscall callers must handle short writes, as with any pipe.
+
+Writes are split before a file exceeds its limit. Oversized records can cross archive,
+line, and UTF-8 character boundaries; concatenate archives oldest-first followed by the active
+file to read the retained byte stream. Enabling or tightening rotation trims each oversized
+existing file in place to its newest bytes and deletes archives beyond `max_files`.
+Rotation/drain failures do not fall back to uncapped appends; drain/control APIs surface errors.
+
+File writes use a stable, zero-byte `<path>.lock` sidecar to coordinate devices and processes.
+All cooperating writers must use the same canonical path and limits; do not delete the lock
+while writers are alive. Regular data descriptors close between operations so idle devices
+cannot retain deleted archives. External replacement is followed on the next write.
+
+This is a bound on **Legion-managed file contents**, not an OS/filesystem quota. Filesystem
+allocation overhead, snapshots, external writers, hardlink aliases, and descriptors retained
+outside these devices are outside the bound. A fork without exec during an in-flight file
+operation can inherit such a descriptor; close inherited descriptors or exec before leaving
+the child idle. A strict volume-level disk-space guarantee requires a filesystem quota.
+
+```json
+{
+  "logging": {
+    "rotation": { "enabled": true, "max_size_mb": 100, "max_files": 5, "stdio": true }
+  }
+}
+```
+
+```ruby
+Legion::Logging.setup(log_file: './legion.log', rotation: { max_size_mb: 50, max_files: 3 })
+Legion::Logging.setup(log_file: './legion.log', rotation: false) # disable
+Legion::Logging.setup(rotation: { stdio: false }) # leave inherited stdout/stderr alone
+logger = Legion::Logging::Logger.new(log_file: './extension.log', rotation: { max_size_mb: 25 })
+```
+
+Omitting `rotation:` reads `logging.rotation` from already-loaded Settings, otherwise uses the
+defaults above. Instance loggers honor the same overrides, including `rotation: false`.
+
+Inherited-stream capture is process-wide. Instance opt-out does not detach capture owned by
+another logger; module-level `setup(rotation: false)` or `setup(rotation: { stdio: false })`
+explicitly disables it. Quiesce raw producers, including children, before disabling capture.
+Pre-drain timeout leaves capture active; a failure or timeout during final handle cleanup
+leaves it fail-closed rather than restoring an uncapped fallback and requires process restart.
+Forked children may write through the inherited pipes but cannot drain/reset parent workers
+or request a different capture policy. Fork-without-exec children also retain pipe read ends,
+which can delay `EPIPE` after a parent drain failure until those children close them or exit.
+
+Captured stdio is asynchronous even with `async: false`: call `stop_async_writer(timeout: 2)`
+**after the final raw stdout/stderr writes** to drain both layers before exit. This does not
+detach capture, and abrupt process termination is not a delivery guarantee. Setup, explicit
+rotation, and retention changes remain synchronous control operations.
+
 ### 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 +108,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, after the final raw stdio writes. It closes async admission and returns `true` only after the writer exits and relevant captured-stdio sinks finish their drain, within one shared deadline. It also drains captured stdio when async logging is disabled. A drain deadline returns `false` without killing workers or draining on the caller; release the blocked destination and retry. 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 +145,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 +195,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 +211,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 +225,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,20 +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,
-                               :conv_id, :request_id, :exchange_id, :chain_id)
-      SHUTDOWN = :shutdown
+                               :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
@@ -24,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)
@@ -67,28 +98,90 @@ 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)
+      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
-          @logger.send(entry.level, entry.message)
-          fire_writer(entry) if entry.writer_context
+          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
+        @preparing = previous_preparing
+        Thread.current[:legion_log_origin] = callback_origin if entry.is_a?(EventEntry)
+      end
+
+      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
+        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
@@ -99,15 +192,7 @@ module Legion
         yield
       ensure
         prev&.each { |k, v| Thread.current[k] = v }
-      end
-
-      def drain
-        until @queue.empty?
-          entry = @queue.pop(true)
-          write_entry(entry) unless entry == SHUTDOWN
-        end
-      rescue ThreadError
-        nil
+        Thread.current[:legion_log_origin] = previous_origin
       end
 
       def accepting?
@@ -115,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]
@@ -123,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