legion-logging 1.3.1 → 1.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54638d1c2311825640cda666c7900b1bdd091ab5d8c7a322fdf72a22f7c1ec2a
-  data.tar.gz: 3ed84565ebc83f04d7d785b2581efadcb4e99a64138f0c1e37920ee4fb78bc94
+  metadata.gz: 3d376fafb0c34211ae2d198730af9c5b257301242c92f18525eb9afa04c570de
+  data.tar.gz: 865d58843c8bd43e9564f62dd4efebfd7b5ed5745102f5b43a6fb5e048500ee2
 SHA512:
-  metadata.gz: 45c750d7a564b0ce713abf50e985fd3749d271c86136600738f3648921d375db75564a0809fe861fb80fb3653a92ec2e1e3120858dd019261d1b9da26de9cee4
-  data.tar.gz: c28935a6b7992cc8db82df7b2fa75e008ee60b520a3bc82752c5d6caaaa6a407a19e0ac944d2c366b84167a9f2032bad489c3f1bec3636feef171ebffac1b1cf
+  metadata.gz: 912e1ec7877ef76adb3f27b07eaf6283a05decfa27d325d953caf76acb295608f67a976cc56a600853a8ecf2e0a2aa247e77f100d3a65872061b6c5033e95b89
+  data.tar.gz: 8503664f4b1fef55b319d026bb7ccc0d13ac6a46773d234b5d8ab7aa2d56e2af61f2b4b4ff7340702012c4db3a54515a35537c8d66c6872b3affca3697cd7de7

data/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Legion::Logging Changelog
 
-## [Unreleased]
+## [1.3.3] - 2026-03-24
+
+### Changed
+- Reindex docs: update CLAUDE.md and README with AsyncWriter and Helper module docs
+
+## [1.3.2] - 2026-03-22
+
+### Added
+- `Legion::Logging::Helper` module: injectable `log` mixin for LEX extensions
+- Derives logger tags from `segments`, `lex_filename`, or class name (in priority order)
+- Passes through `settings[:logger]` config when available
+- Allows LEX gems to use `legion-logging` directly instead of requiring the full LegionIO framework
 
 ## [1.3.1] - 2026-03-22
 

data/CLAUDE.md

@@ -8,7 +8,7 @@
 Ruby logging class for the LegionIO framework. Provides colorized console output via Rainbow, structured JSON logging (`format: :json`), and a consistent logging interface across all Legion gems and extensions.
 
 **GitHub**: https://github.com/LegionIO/legion-logging
-**Version**: 1.2.5
+**Version**: 1.3.2
 **License**: Apache-2.0
 
 ## Architecture
@@ -16,9 +16,11 @@ Ruby logging class for the LegionIO framework. Provides colorized console output
 ```
 Legion::Logging (singleton module)
 ├── Methods         # Log level methods: debug, info, warn, error, fatal, unknown
-├── Builder         # Output destination (stdout/file), log level, formatter
+├── Builder         # Output destination (stdout/file), log level, formatter, async: keyword
+├── AsyncWriter     # Non-blocking SizedQueue-backed writer thread; fatal calls bypass queue
 ├── Hooks           # Callback registry for fatal/error/warn events (on_fatal, on_error, on_warn)
 ├── EventBuilder    # Structured event payload builder (caller, exception, lex, gem metadata)
+├── Helper          # Injectable log mixin for LEX extensions (derives logger tags from segments/class)
 ├── Logger          # Core logger configuration and setup
 ├── MultiIO         # Write to multiple destinations simultaneously
 ├── SIEMExporter    # PHI-redacting SIEM export (Splunk HEC, ELK/OpenSearch)
@@ -31,13 +33,15 @@ Legion::Logging (singleton module)
 
 - **Singleton Module**: `Legion::Logging` uses `class << self` - called directly: `Legion::Logging.info("msg")`
 - **Rainbow Colorization**: Console output uses Rainbow gem for colored terminal output
-- **Setup Method**: `Legion::Logging.setup(log_file:, level:)` configures output destination and level
+- **Setup Method**: `Legion::Logging.setup(log_file:, level:, async: true)` configures output destination, level, and async mode
+- **Async by Default**: `setup` enables async logging — calls return immediately. Fatal calls always bypass the queue. `stop_async_writer` flushes and stops on shutdown. Buffer size configurable via `Legion::Settings.dig(:logging, :async, :buffer_size)` (default 10,000). Back-pressure: callers block when buffer is full.
 - **Structured JSON**: `format: :json` in settings outputs machine-parseable JSON log lines
 - **Shared Interface**: Same method signature (`info`, `warn`, `error`, etc.) across all Legion components
 - **MultiIO**: Splits writes to stdout and a log file simultaneously (used by Builder when `log_file` is set)
 - **SIEMExporter**: PHI redaction (SSN, phone, MRN, DOB patterns), `export_to_splunk` (HEC), `format_for_elk`
-- **Hook Callbacks**: `on_fatal`, `on_error`, `on_warn` register procs called after each log at those levels. Hooks are gated by `enable_hooks!`/`disable_hooks!`. Hook failures are silently rescued — never impact the logger.
+- **Hook Callbacks**: `on_fatal`, `on_error`, `on_warn` register procs called after each log at those levels. Hooks are gated by `enable_hooks!`/`disable_hooks!`. Hook failures are silently rescued — never impact the logger. Hooks fire on the async writer thread; event context captured on caller thread.
 - **EventBuilder**: Builds structured event hashes from log context (caller location, exception info, lex identity, gem metadata). All from in-memory data, zero IO.
+- **Helper mixin**: `Legion::Logging::Helper` is injectable into LEX extensions. Derives logger tags from `segments`, `lex_filename`, or class name. Passes through `settings[:logger]` config when available.
 
 ## Dependencies
 
@@ -51,7 +55,9 @@ Legion::Logging (singleton module)
 |------|---------|
 | `lib/legion/logging.rb` | Module entry point |
 | `lib/legion/logging/methods.rb` | Log level methods |
-| `lib/legion/logging/builder.rb` | Output config and formatter |
+| `lib/legion/logging/builder.rb` | Output config and formatter (async: keyword) |
+| `lib/legion/logging/async_writer.rb` | Non-blocking SizedQueue-backed writer thread with back-pressure |
+| `lib/legion/logging/helper.rb` | Injectable log mixin for LEX extensions |
 | `lib/legion/logging/logger.rb` | Core logger setup |
 | `lib/legion/logging/multi_io.rb` | Multi-output IO (write to multiple destinations simultaneously) |
 | `lib/legion/logging/siem_exporter.rb` | PHI-redacting SIEM export helpers (Splunk HEC, ELK format) |

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.3.0
+**Version**: 1.3.2
 
 ## Installation
 
@@ -79,6 +79,21 @@ Legion::Logging::SIEMExporter.format_for_elk(event, index: 'legion')
 
 PHI patterns redacted: SSN (`###-##-####`), phone (`###-###-####`), MRN (`XX#######`), DOB (`##/##/####`).
 
+### Helper Mixin
+
+`Legion::Logging::Helper` is an injectable mixin for LEX extensions. It derives logger tags from `segments`, `lex_filename`, or class name automatically, and passes through `settings[:logger]` config when available. Allows LEX gems to use `legion-logging` directly without requiring the full LegionIO framework.
+
+```ruby
+class MyRunner
+  include Legion::Logging::Helper
+
+  def run
+    log.info("starting")
+    log.debug("details")
+  end
+end
+```
+
 ## Requirements
 
 - Ruby >= 3.4

data/lib/legion/logging/helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    module Helper
+      def log
+        return @log unless @log.nil?
+
+        logger_hash = if respond_to?(:segments)
+                        { lex_segments: Array(segments) }
+                      else
+                        { lex: derive_log_tag }
+                      end
+
+        if respond_to?(:settings) && settings.is_a?(Hash) && settings.key?(:logger)
+          ls = settings[:logger]
+          logger_hash[:level] = ls[:level] if ls.key?(:level)
+          logger_hash[:log_file] = ls[:log_file] if ls.key?(:log_file)
+          logger_hash[:trace] = ls[:trace] if ls.key?(:trace)
+          logger_hash[:extended] = ls[:extended] if ls.key?(:extended)
+        end
+
+        @log = Legion::Logging::Logger.new(**logger_hash)
+      end
+
+      private
+
+      def derive_log_tag
+        if respond_to?(:lex_filename)
+          fname = lex_filename
+          return fname.is_a?(Array) ? fname.first : fname
+        end
+
+        name = respond_to?(:ancestors) ? ancestors.first.to_s : self.class.to_s
+        parts = name.split('::')
+        ext_idx = parts.index('Extensions')
+        target = if ext_idx && parts[ext_idx + 1]
+                   parts[ext_idx + 1]
+                 else
+                   parts.last
+                 end
+        target.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+              .downcase
+      end
+    end
+  end
+end

data/lib/legion/logging/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Logging
-    VERSION = '1.3.1'
+    VERSION = '1.3.3'
   end
 end

data/lib/legion/logging.rb

@@ -7,6 +7,7 @@ require 'legion/logging/builder'
 require 'legion/logging/hooks'
 require 'legion/logging/event_builder'
 require 'legion/logging/async_writer'
+require 'legion/logging/helper'
 
 require 'json'
 require 'logger'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-logging
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.3.3
 platform: ruby
 authors:
 - Esity
@@ -60,6 +60,7 @@ files:
 - lib/legion/logging/async_writer.rb
 - lib/legion/logging/builder.rb
 - lib/legion/logging/event_builder.rb
+- lib/legion/logging/helper.rb
 - lib/legion/logging/hooks.rb
 - lib/legion/logging/logger.rb
 - lib/legion/logging/methods.rb