legion-logging 1.2.6 → 1.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4a463a1d341069c5c5ed0f15e98dfc25a3572e440bbba3f09d63ffc825c7f0f
-  data.tar.gz: 5e6a1dbbec201fb5fcd4e4c6d000ecba84f53bf78a5f25f74e5b75145ff11683
+  metadata.gz: e397ca81de1cb74f71dc9f220e59406a8f8e6cbf2d9aae6092918f428588bc60
+  data.tar.gz: e41480464a27679090cc3bbff835c9a9c5c5f2c52fb60edd1096d1c8e7a43031
 SHA512:
-  metadata.gz: dae39ad0842e8fdf132993d465a9ff6bedab0e6174bf42c9f9ab4ffad98377d3352b6ecc3aca218480fb2c6be9eb36c9efb80c0230e0c95a2dbe2011da6461ad
-  data.tar.gz: 07c5e18d680c68e83bd03a3d20f64a2cf9ab62c513a00773d5a55a58e9f7c3fcf0f98268b8b3a63de8e18509fe0a237922e4eec6de64132a815e970da96d2a33
+  metadata.gz: 355eaf1cfe6d31c27360aadc06bdd6a81b6fa07c380ca68c5fd645089fe8ba81521ffd7971c078ed5f124c9e28e73babcbb390fcffcca46f5648ad3ee2839d24
+  data.tar.gz: c062f3e91ccc3a322cbbf8a539321207505c7e663623027e7d59354c63ac3eb692b93389ced67be17c7614b1578021e07dc7956ad0f1469e6cd4adb57d262629

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Legion::Logging Changelog
 
+## [Unreleased]
+
+## v1.2.7
+
+### Added
+- `Legion::Logging::Hooks`: callback registry for fatal/error/warn log events
+- `Legion::Logging::EventBuilder`: structured event payload builder with caller, exception, lex, and gem metadata
+- `on_fatal`, `on_error`, `on_warn` registration methods on `Legion::Logging`
+- `enable_hooks!`, `disable_hooks!`, `clear_hooks!` control methods
+- Hook dispatch wired into `fatal`, `error`, `warn` methods in `Methods` module
+
 ## v1.2.6
 
 ### Added

data/CLAUDE.md

@@ -17,10 +17,14 @@ 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
+├── Hooks           # Callback registry for fatal/error/warn events (on_fatal, on_error, on_warn)
+├── EventBuilder    # Structured event payload builder (caller, exception, lex, gem metadata)
 ├── Logger          # Core logger configuration and setup
 ├── MultiIO         # Write to multiple destinations simultaneously
 ├── SIEMExporter    # PHI-redacting SIEM export (Splunk HEC, ELK/OpenSearch)
-└── Version         # VERSION constant (1.2.5)
+├── Shipper         # Buffered log event forwarding (file/http transports)
+├── Redactor        # PII/PHI pattern redaction
+└── Version         # VERSION constant
 ```
 
 ### Key Design Patterns
@@ -32,6 +36,8 @@ Legion::Logging (singleton module)
 - **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.
+- **EventBuilder**: Builds structured event hashes from log context (caller location, exception info, lex identity, gem metadata). All from in-memory data, zero IO.
 
 ## Dependencies
 
@@ -49,6 +55,8 @@ Legion::Logging (singleton module)
 | `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) |
+| `lib/legion/logging/hooks.rb` | Callback registry (fatal/error/warn hook arrays, enable/disable/clear) |
+| `lib/legion/logging/event_builder.rb` | Structured event payload builder |
 | `lib/legion/logging/version.rb` | VERSION constant |
 
 ## Role in LegionIO

data/lib/legion/logging/event_builder.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    module EventBuilder
+      class << self
+        def build(level:, message:, lex: nil, lex_segments: nil, context: nil, caller_offset: 2) # rubocop:disable Metrics/ParameterLists
+          event = base_fields(level, message)
+          event[:lex] = derive_lex_source(lex, lex_segments)
+          add_node(event)
+          add_caller_info(event, caller_offset)
+          add_exception_info(event, message)
+          add_gem_info(event, event[:lex])
+          event[:context] = context if context
+          event.compact
+        end
+
+        private
+
+        def base_fields(level, message)
+          {
+            timestamp: Time.now.utc.iso8601(3),
+            level:     level,
+            message:   message.is_a?(Exception) ? message.message : strip_ansi(message.to_s),
+            pid:       ::Process.pid,
+            thread:    Thread.current.object_id
+          }
+        end
+
+        def derive_lex_source(lex, lex_segments)
+          if lex_segments.is_a?(Array) && !lex_segments.empty?
+            "lex-#{lex_segments.join('-')}"
+          elsif lex && !lex.to_s.empty?
+            "lex-#{lex}"
+          end
+        end
+
+        def add_node(event)
+          return unless defined?(Legion::Settings)
+
+          name = begin
+            Legion::Settings[:client][:name]
+          rescue StandardError
+            nil
+          end
+          event[:node] = name if name
+        end
+
+        def add_caller_info(event, offset)
+          loc = caller_locations(offset + 1, 1)&.first
+          return unless loc
+
+          event[:caller] = {
+            file:     loc.absolute_path || loc.path,
+            function: loc.base_label,
+            line:     loc.lineno
+          }
+        end
+
+        def add_exception_info(event, message)
+          return unless message.is_a?(Exception)
+
+          event[:exception] = {
+            class:   message.class.name,
+            message: message.message
+          }
+          event[:backtrace] = message.backtrace if message.backtrace
+        end
+
+        def add_gem_info(event, lex_source)
+          return unless lex_source
+
+          spec = Gem::Specification.find_by_name(lex_source)
+          event[:gem] = {
+            name:            spec.name,
+            version:         spec.version.to_s,
+            source_code_uri: spec.metadata['source_code_uri'],
+            homepage:        spec.metadata['homepage_uri'] || spec.homepage,
+            path:            spec.full_gem_path
+          }.compact
+        rescue Gem::MissingSpecError, ArgumentError
+          nil
+        end
+
+        def strip_ansi(str)
+          str.gsub(/\e\[[0-9;]*m/, '')
+        end
+      end
+    end
+  end
+end

data/lib/legion/logging/hooks.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    module Hooks
+      @hooks = { fatal: [], error: [], warn: [] }
+      @enabled = false
+
+      class << self
+        attr_reader :hooks
+
+        def enabled?
+          @enabled
+        end
+
+        def enable!
+          @enabled = true
+        end
+
+        def disable!
+          @enabled = false
+        end
+
+        def clear!
+          @hooks.each_value(&:clear)
+        end
+
+        def register(level, &block)
+          @hooks[level] << block
+        end
+
+        def fire(level, event)
+          return unless @enabled
+          return if @hooks[level].empty?
+
+          @hooks[level].each do |hook|
+            hook.call(event)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/logging/logger.rb

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

data/lib/legion/logging/methods.rb

@@ -37,24 +37,30 @@ module Legion
         return unless log.level < 3
 
         message = yield if message.nil? && block_given?
+        raw = message
         message = Rainbow(message).yellow if @color
         log.warn(message)
+        fire_hooks(:warn, raw)
       end
 
       def error(message = nil)
         return unless log.level < 4
 
         message = yield if message.nil? && block_given?
+        raw = message
         message = Rainbow(message).red if @color
         log.error(message)
+        fire_hooks(:error, raw)
       end
 
       def fatal(message = nil)
         return unless log.level < 5
 
         message = yield if message.nil? && block_given?
+        raw = message
         message = Rainbow(message).darkred if @color
         log.fatal(message)
+        fire_hooks(:fatal, raw)
       end
 
       def unknown(message = nil)
@@ -77,6 +83,25 @@ module Legion
           Thread.current.object_id.to_s
         end
       end
+
+      private
+
+      def fire_hooks(level, message)
+        return unless Legion::Logging::Hooks.enabled?
+        return if Legion::Logging::Hooks.hooks[level].empty?
+
+        lex_val  = instance_variable_defined?(:@lex) ? @lex : nil
+        lex_segs = instance_variable_defined?(:@lex_segments) ? @lex_segments : nil
+
+        event = Legion::Logging::EventBuilder.build(
+          level:         level,
+          message:       message,
+          lex:           lex_val,
+          lex_segments:  lex_segs,
+          caller_offset: 4
+        )
+        Legion::Logging::Hooks.fire(level, event)
+      end
     end
   end
 end

data/lib/legion/logging/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Logging
-    VERSION = '1.2.6'
+    VERSION = '1.2.7'
   end
 end

data/lib/legion/logging.rb

@@ -4,6 +4,8 @@ require 'legion/logging/version'
 require 'legion/logging/logger'
 require 'legion/logging/methods'
 require 'legion/logging/builder'
+require 'legion/logging/hooks'
+require 'legion/logging/event_builder'
 
 require 'json'
 require 'logger'
@@ -15,6 +17,13 @@ module Legion
       include Legion::Logging::Methods
       include Legion::Logging::Builder
 
+      def on_fatal(&)  = Hooks.register(:fatal, &)
+      def on_error(&)  = Hooks.register(:error, &)
+      def on_warn(&)   = Hooks.register(:warn, &)
+      def enable_hooks!     = Hooks.enable!
+      def disable_hooks!    = Hooks.disable!
+      def clear_hooks!      = Hooks.clear!
+
       attr_reader :color
 
       def setup(level: 'info', format: :text, **options)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-logging
 version: !ruby/object:Gem::Version
-  version: 1.2.6
+  version: 1.2.7
 platform: ruby
 authors:
 - Esity
@@ -58,6 +58,8 @@ files:
 - legion-logging.gemspec
 - lib/legion/logging.rb
 - lib/legion/logging/builder.rb
+- lib/legion/logging/event_builder.rb
+- lib/legion/logging/hooks.rb
 - lib/legion/logging/logger.rb
 - lib/legion/logging/methods.rb
 - lib/legion/logging/multi_io.rb