legion-logging 1.3.5 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a197403f8e3949ef6680892655b47cdfec6052dffcf32732c8d9d277c5eecc93
-  data.tar.gz: 3baa080b906527dc521b1f326f014469d2802cac0e16682cc3eb3b2354079894
+  metadata.gz: 31ec07f7a93713fb708102528d4e61525a4c3b4fa39de510d29a454726b49436
+  data.tar.gz: 62a67fc723d1e865ef3e632d1987b6ce73c2fe9aa033686df5fe3b2fb89bc14c
 SHA512:
-  metadata.gz: c63d0b3a21a3822f0f6e8226455b6d1f65a743094acd6d8669f4f8cda2a63e988503026b53c25084f9cd4c1bda0b87fcc94a6bc9afbe057736a713e7d4f1a31c
-  data.tar.gz: 1e76100161836d8e258fcb11a266f542bfc4e2df323a2830b3a54b649b2b0ea128613282f2fbebe8a0d5668200411fbfadcc92a152cd0fe1e3b0fea675a8de7d
+  metadata.gz: 5e0b2171b6ca1b1acbb3ad0f40cbd23a77bf5824a3b2f37a5c9b3484f7edf2cf9cf1a8dc23a9f0ed0acd426e139fb0d7ce13ac0a3ae2a77b3113dd0569cc6d53
+  data.tar.gz: e4e599809e26c6b7a0f9c1a81f05e390175cad0568b6b99f26888b675590972ff9148e27bc53f36461e1d6f09f83fcf7a818b01bd793098c5809910affabb0a2

data/.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# Auto-generated from team-config.yml
+# Team: core
+#
+# To apply: scripts/apply-codeowners.sh legion-logging
+
+* @LegionIO/maintainers
+* @LegionIO/core

data/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: bundler
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - "type:dependencies"
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - "type:dependencies"

data/.rubocop.yml

@@ -16,6 +16,9 @@ Layout/HashAlignment:
 Metrics/MethodLength:
   Max: 50
 
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
 Metrics/ClassLength:
   Max: 1500
 

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Legion::Logging Changelog
 
+## [1.4.2] - 2026-03-28
+
+### Added
+- `Legion::Logging::CategoryRegistry` module: extension-defined event category registration with `register_category`, `registered_categories`, `category_registered?`, and `category_info` methods
+- `Legion::Logging.register_category` and `Legion::Logging.registered_categories` delegate methods on the top-level module
+- `category:` keyword argument on `EventBuilder.build` — emits `category` field in structured log events when provided
+- `SIEMExporter.format_for_elk` now includes `category` field when the event hash carries `:category` or `"category"`
+
+## [1.4.1] - 2026-03-27
+
+### Fixed
+- `require 'time'` added to `event_builder.rb` so `Time#iso8601` is always available in minimal Ruby environments
+- `log_writer` / `exception_writer` accessors no longer memoize the no-op default via `||=`; `@log_writer` stays `nil` until a real writer is assigned, which allows `build_writer_context` to correctly short-circuit event building when no writer is configured
+- README writer lambda examples updated to show correct keyword argument signatures matching actual call sites
+
+## [1.4.0] - 2026-03-27
+
+### Added
+- `log_exception` method in `Methods` — single call for complete structured exception events
+- `EventBuilder.build_exception` — builds rich exception payloads with fingerprint, versions, flat caller keys
+- `EventBuilder.fingerprint` — MD5 fingerprint of stable error fields for dedup
+- `log_writer` / `exception_writer` pluggable lambda slots on `Legion::Logging`
+- Size enforcement: 4KB message cap, 8KB payload_summary cap, 64KB total cap
+- Vault token, JWT, lease ID, and URI patterns added to Redactor
+
+### Removed
+- `Legion::Logging::Hooks` module (`on_fatal`, `on_error`, `on_warn`, `enable_hooks!`, `disable_hooks!`, `clear_hooks!`)
+- Hooks replaced by `log_writer` and `exception_writer` lambdas
+
+### Changed
+- `AsyncWriter::LogEntry` uses `writer_context` field instead of `hook_context`
+- `runner_exception` now delegates to `log_exception` internally
+
 ## [1.3.5] - 2026-03-24
 
 ### Added

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.2
+**Version**: 1.4.1
 
 ## Installation
 
@@ -94,6 +94,35 @@ class MyRunner
 end
 ```
 
+### Exception Logging
+
+`log_exception` provides a single call for complete structured exception events with component context:
+
+```ruby
+Legion::Logging.log_exception(exception,
+  handled: true,
+  component_type: :runner,
+  lex: 'my_extension',
+  task_id: 'abc-123')
+```
+
+### 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:
+
+```ruby
+Legion::Logging.exception_writer = ->(payload, routing_key:, headers:, properties:) { publish_to_amqp(payload) }
+Legion::Logging.log_writer = ->(context, routing_key:) { publish_log(context) }
+```
+
+### EventBuilder
+
+`EventBuilder.build_exception` constructs rich structured exception payloads including caller location, lex identity, and gem metadata. `EventBuilder.fingerprint` produces an MD5 fingerprint of stable error fields for deduplication in log aggregation pipelines.
+
+### Redactor
+
+`Legion::Logging::Redactor` redacts PII/PHI patterns (SSN, phone, MRN, DOB) plus Vault tokens, JWTs, bearer tokens, and lease IDs from log messages. Redaction is opt-in: load the module (for example via `require 'legion/logging/redactor'`) and enable it with `logging.redaction.enabled: true`. When loaded and enabled, it is wired into all log methods in the write path.
+
 ## Requirements
 
 - Ruby >= 3.4

data/lib/legion/logging/async_writer.rb

@@ -3,7 +3,7 @@
 module Legion
   module Logging
     class AsyncWriter
-      LogEntry = ::Data.define(:level, :message, :hook_context)
+      LogEntry = ::Data.define(:level, :message, :writer_context)
       SHUTDOWN = :shutdown
 
       def initialize(logger, buffer_size: 10_000)
@@ -55,7 +55,7 @@ module Legion
 
       def write_entry(entry)
         @logger.send(entry.level, entry.message)
-        fire_hooks(entry) if entry.hook_context
+        fire_writer(entry) if entry.writer_context
       rescue StandardError => e
         warn("legion-log-writer error: #{e.message} (#{e.backtrace&.first})")
       end
@@ -69,11 +69,16 @@ module Legion
         nil
       end
 
-      def fire_hooks(entry)
-        ctx = entry.hook_context
-        Legion::Logging::Hooks.fire(ctx[:level], ctx[:event])
+      def fire_writer(entry)
+        ctx = entry.writer_context
+        event = ctx[:event]
+        level = ctx[:level]
+        lex_name = event[:lex] || 'core'
+        component = event.dig(:caller, :file).to_s[%r{/(runners|actors|transport|helpers|builders)/}, 1] || 'unknown'
+        routing_key = "legion.logging.log.#{level}.#{lex_name}.#{component}"
+        Legion::Logging.log_writer.call(event, routing_key: routing_key)
       rescue StandardError => e
-        warn("legion-log-writer hook error: #{e.message}")
+        warn("legion-log-writer writer error: #{e.message}")
       end
     end
   end

data/lib/legion/logging/category_registry.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    module CategoryRegistry
+      VALID_NAME_PATTERN = /\A[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*\z/
+
+      class << self
+        def register_category(name, description: nil, expected_fields: [])
+          name = name.to_s
+          raise ArgumentError, "invalid category name: #{name.inspect}" unless name.match?(VALID_NAME_PATTERN)
+
+          registry[name] = {
+            name:            name,
+            description:     description,
+            expected_fields: Array(expected_fields)
+          }.freeze
+          name
+        end
+
+        def registered_categories
+          registry.dup.freeze
+        end
+
+        def category_registered?(name)
+          registry.key?(name.to_s)
+        end
+
+        def category_info(name)
+          registry[name.to_s]
+        end
+
+        def clear!
+          registry.clear
+        end
+
+        private
+
+        def registry
+          @registry ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/legion/logging/event_builder.rb

@@ -1,10 +1,19 @@
 # frozen_string_literal: true
 
+require 'digest'
+require 'json'
+require 'time'
+
 module Legion
   module Logging
     module EventBuilder
+      MAX_MESSAGE_BYTES        = 4096
+      MAX_PAYLOAD_BYTES        = 8192
+      MAX_TOTAL_BYTES          = 65_536
+      BACKTRACE_FALLBACK_FRAMES = 20
+
       class << self
-        def build(level:, message:, lex: nil, lex_segments: nil, context: nil, caller_offset: 2) # rubocop:disable Metrics/ParameterLists
+        def build(level:, message:, lex: nil, lex_segments: nil, context: nil, category: nil, caller_offset: 2)
           event = base_fields(level, message)
           event[:lex] = derive_lex_source(lex, lex_segments)
           add_node(event)
@@ -12,9 +21,103 @@ module Legion
           add_exception_info(event, message)
           add_gem_info(event, event[:lex])
           event[:context] = context if context
+          event[:category] = category.to_s if category
+          event.compact
+        end
+
+        def build_exception(
+          exception:,
+          level:,
+          lex: nil,
+          component_type: nil,
+          gem_name: nil,
+          lex_version: nil,
+          gem_path: nil,
+          source_code_uri: nil,
+          handled: false,
+          payload_summary: nil,
+          task_id: nil,
+          caller_offset: 2,
+          **extra
+        )
+          bt = Array(exception.backtrace)
+          cf_file, cf_line, cf_func = parse_backtrace_location(bt.first) ||
+                                      caller_location(caller_offset)
+
+          event = {
+            timestamp:       Time.now.utc.iso8601(3),
+            level:           level,
+            exception_class: exception.class.name,
+            message:         truncate_bytes(exception.message.to_s, MAX_MESSAGE_BYTES),
+            backtrace:       bt,
+            caller_file:     cf_file,
+            caller_line:     cf_line,
+            caller_function: cf_func,
+            lex:             lex,
+            component_type:  component_type,
+            gem_name:        gem_name,
+            lex_version:     lex_version,
+            gem_path:        gem_path,
+            source_code_uri: source_code_uri,
+            legion_versions: legion_versions,
+            ruby_version:    "#{RUBY_VERSION} #{RUBY_PLATFORM}",
+            handled:         handled,
+            pid:             ::Process.pid,
+            thread:          Thread.current.object_id
+          }
+
+          event[:task_id] = task_id if task_id
+          event[:payload_summary] = truncate_payload(payload_summary) if payload_summary
+
+          add_node(event)
+          add_user(event)
+          add_session_context(event)
+
+          event[:error_fingerprint] = fingerprint(
+            exception_class: exception.class.name,
+            message:         event[:message],
+            caller_file:     cf_file.to_s,
+            caller_line:     cf_line.to_i,
+            caller_function: cf_func.to_s,
+            gem_name:        gem_name.to_s,
+            component_type:  component_type.to_s,
+            backtrace:       bt
+          )
+
+          extra.each { |k, v| event[k] = v unless event.key?(k) }
+
+          enforce_total_size!(event)
           event.compact
         end
 
+        def fingerprint(
+          exception_class:,
+          message:,
+          caller_file:,
+          caller_line:,
+          caller_function:,
+          gem_name:,
+          component_type:,
+          backtrace:
+        )
+          norm_msg = normalize_message(message.to_s)
+          norm_file = normalize_path(caller_file.to_s)
+          norm_bt = Array(backtrace).first(5).map { |l| normalize_path(l.to_s) }.join('|')
+
+          raw = [
+            exception_class.to_s,
+            norm_msg,
+            norm_file,
+            caller_line.to_s,
+            caller_function.to_s,
+            gem_name.to_s,
+            component_type.to_s,
+            norm_bt
+          ].join(':')
+
+          Digest::MD5.hexdigest(raw)
+        end
+
         private
 
         def base_fields(level, message)
@@ -95,6 +198,106 @@ module Legion
         def strip_ansi(str)
           str.gsub(/\e\[[0-9;]*m/, '')
         end
+
+        # New private helpers for build_exception
+
+        def add_user(event)
+          identity = if defined?(Legion::Extensions::Helpers::Secret) &&
+                        Legion::Extensions::Helpers::Secret.respond_to?(:resolved_identity)
+                       Legion::Extensions::Helpers::Secret.resolved_identity
+                     else
+                       ENV.fetch('USER', nil)
+                     end
+          event[:user] = identity
+        end
+
+        def add_session_context(event)
+          return unless defined?(Legion::Context)
+
+          session = begin
+            Legion::Context.current_session
+          rescue StandardError
+            nil
+          end
+          return unless session
+
+          event[:conversation_id] = session.session_id
+        end
+
+        def parse_backtrace_location(frame)
+          return nil unless frame.is_a?(String)
+
+          # Format: /path/to/file.rb:42:in `method_name`
+          if (m = frame.match(/\A(.+):(\d+):in `([^`]+)`\z/))
+            [m[1], m[2].to_i, m[3]]
+          elsif (m = frame.match(/\A(.+):(\d+)\z/))
+            [m[1], m[2].to_i, nil]
+          end
+        end
+
+        def caller_location(offset)
+          loc = caller_locations(offset + 2, 1)&.first
+          return [nil, nil, nil] unless loc
+
+          [loc.absolute_path || loc.path, loc.lineno, loc.base_label]
+        end
+
+        def normalize_message(msg)
+          msg
+            .gsub(/0x[0-9a-f]+/i, '0xXXX')
+            .gsub(/#<[A-Z][A-Za-z:]*:0xXXX>/, '#<Class:0xXXX>')
+            .gsub(/\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/, 'X.X.X.X')
+        end
+
+        def normalize_path(path)
+          path.gsub(/-\d+\.\d+[\d.]*/, '')
+        end
+
+        def legion_versions
+          Gem::Specification
+            .select { |s| s.name.start_with?('legion-', 'lex-') }
+            .to_h { |s| [s.name, s.version.to_s] }
+        end
+
+        def truncate_bytes(str, max)
+          return str if str.bytesize <= max
+
+          str.byteslice(0, max).scrub
+        end
+
+        def safe_json_bytesize(object)
+          ::JSON.generate(object).bytesize
+        rescue ::JSON::GeneratorError, TypeError
+          object.to_s.bytesize
+        end
+
+        def truncate_payload(payload)
+          return nil unless payload
+
+          str = if payload.is_a?(String)
+                  payload
+                else
+                  begin
+                    ::JSON.generate(payload)
+                  rescue ::JSON::GeneratorError, TypeError
+                    payload.to_s
+                  end
+                end
+          truncate_bytes(str, MAX_PAYLOAD_BYTES)
+        end
+
+        def enforce_total_size!(event)
+          return if safe_json_bytesize(event) <= MAX_TOTAL_BYTES
+
+          event.delete(:payload_summary)
+          return if safe_json_bytesize(event) <= MAX_TOTAL_BYTES
+
+          bt = event[:backtrace]
+          event[:backtrace] = bt.first(BACKTRACE_FALLBACK_FRAMES) if bt.is_a?(Array)
+          return if safe_json_bytesize(event) <= MAX_TOTAL_BYTES
+
+          event[:message] = truncate_bytes(event[:message].to_s, 1024)
+        end
       end
     end
   end

data/lib/legion/logging/logger.rb

@@ -11,7 +11,7 @@ module Legion
       include Legion::Logging::Methods
       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, async: false, **opts) # rubocop:disable Metrics/ParameterLists
+      def initialize(level: 'info', log_file: nil, log_stdout: nil, lex: nil, trace: false, extended: false, trace_size: 4, format: :text, async: false, **opts)
         @lex = lex
         set_log(logfile: log_file, log_stdout: log_stdout)
         log_level(level)

data/lib/legion/logging/methods.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module Legion
   module Logging
     module Methods
@@ -25,7 +27,7 @@ module Legion
         message = Rainbow(message).blue if @color
         writer = @async_writer
         if writer&.alive?
-          writer.push(AsyncWriter::LogEntry.new(level: :debug, message: message, hook_context: nil))
+          writer.push(AsyncWriter::LogEntry.new(level: :debug, message: message, writer_context: nil))
         else
           log.debug(message)
         end
@@ -39,7 +41,7 @@ module Legion
         message = Rainbow(message).green if @color
         writer = @async_writer
         if writer&.alive?
-          writer.push(AsyncWriter::LogEntry.new(level: :info, message: message, hook_context: nil))
+          writer.push(AsyncWriter::LogEntry.new(level: :info, message: message, writer_context: nil))
         else
           log.info(message)
         end
@@ -54,11 +56,11 @@ module Legion
         message = Rainbow(message).yellow if @color
         writer = @async_writer
         if writer&.alive?
-          ctx = build_hook_context(:warn, raw)
-          writer.push(AsyncWriter::LogEntry.new(level: :warn, message: message, hook_context: ctx))
+          ctx = build_writer_context(:warn, raw)
+          writer.push(AsyncWriter::LogEntry.new(level: :warn, message: message, writer_context: ctx))
         else
           log.warn(message)
-          fire_hooks(:warn, raw)
+          fire_log_writer(:warn, raw)
         end
       end
 
@@ -71,11 +73,11 @@ module Legion
         message = Rainbow(message).red if @color
         writer = @async_writer
         if writer&.alive?
-          ctx = build_hook_context(:error, raw)
-          writer.push(AsyncWriter::LogEntry.new(level: :error, message: message, hook_context: ctx))
+          ctx = build_writer_context(:error, raw)
+          writer.push(AsyncWriter::LogEntry.new(level: :error, message: message, writer_context: ctx))
         else
           log.error(message)
-          fire_hooks(:error, raw)
+          fire_log_writer(:error, raw)
         end
       end
 
@@ -87,7 +89,7 @@ module Legion
         raw = message
         message = Rainbow(message).darkred if @color
         log.fatal(message)
-        fire_hooks(:fatal, raw)
+        fire_log_writer(:fatal, raw)
       end
 
       def unknown(message = nil)
@@ -96,19 +98,56 @@ module Legion
         message = Rainbow(message).purple if @color
         writer = @async_writer
         if writer&.alive?
-          writer.push(AsyncWriter::LogEntry.new(level: :unknown, message: message, hook_context: nil))
+          writer.push(AsyncWriter::LogEntry.new(level: :unknown, message: message, writer_context: nil))
         else
           log.unknown(message)
         end
       end
 
       def runner_exception(exc, **opts)
-        Legion::Logging.error exc.message
-        Legion::Logging.error exc.backtrace
-        Legion::Logging.error opts
+        log_exception(exc, handled: true, **opts)
         { success: false, message: exc.message, backtrace: exc.backtrace }.merge(opts)
       end
 
+      def log_exception(exception, level: :error, lex: nil, component_type: nil,
+                        gem_name: nil, lex_version: nil, gem_path: nil,
+                        source_code_uri: nil, handled: false, payload_summary: nil,
+                        task_id: nil, **extra)
+        level = level.to_sym if level.respond_to?(:to_sym)
+        # 1. Log human-readable line to stdout/file (bypass writer callbacks)
+        msg = exception.respond_to?(:message) ? exception.message : exception.to_s
+        log.public_send(level, msg) if respond_to?(:log) && log.respond_to?(level)
+
+        # 2. Build rich exception event
+        event = Legion::Logging::EventBuilder.build_exception(
+          exception:       exception,
+          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,
+          caller_offset:   3,
+          **extra
+        )
+
+        # 3. Redact secrets before publishing
+        event = Legion::Logging::Redactor.redact(event) if defined?(Legion::Logging::Redactor)
+
+        # 4. Publish rich event via exception_writer
+        publish_exception_event(event, level)
+      rescue StandardError => e
+        if respond_to?(:log) && log.respond_to?(:warn)
+          log.warn("Failed to publish structured exception event: #{e.class}: #{e.message}")
+        else
+          warn("Failed to publish structured exception event: #{e.class}: #{e.message}")
+        end
+      end
+
       def thread(kvl: false, **_opts)
         if kvl
           "thread=#{Thread.current.object_id}"
@@ -140,9 +179,53 @@ module Legion
         false
       end
 
-      def build_hook_context(level, message)
-        return nil unless Legion::Logging::Hooks.enabled?
-        return nil if Legion::Logging::Hooks.hooks[level].empty?
+      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)
+      end
+
+      def build_exception_headers(event, comp, level)
+        headers = {
+          'x-error-fingerprint' => event[:error_fingerprint],
+          'x-exception-class'   => event[:exception_class],
+          'x-handled'           => event[:handled].to_s,
+          'x-gem-name'          => event[:gem_name].to_s,
+          'x-lex-version'       => event[:lex_version].to_s,
+          'x-component-type'    => comp.to_s,
+          'x-level'             => level.to_s
+        }
+        append_optional_header(headers, 'x-task-id', event[:task_id])
+        append_optional_header(headers, 'x-conversation-id', event[:conversation_id])
+        append_optional_header(headers, 'x-user', event[:user])
+        headers
+      end
+
+      def append_optional_header(headers, key, value)
+        return if value.nil?
+        return if value.respond_to?(:empty?) && value.empty?
+
+        headers[key] = value.to_s
+      end
+
+      def build_exception_properties(event, level)
+        {
+          content_type:   'application/json',
+          message_id:     SecureRandom.uuid,
+          correlation_id: event[:error_fingerprint],
+          timestamp:      Time.now.to_i,
+          app_id:         'legionio',
+          type:           'exception_event',
+          priority:       { warn: 0, error: 5, fatal: 9 }[level] || 5,
+          delivery_mode:  2
+        }
+      end
+
+      def build_writer_context(level, message)
+        return nil if Legion::Logging.instance_variable_get(:@log_writer).nil?
 
         lex_val  = instance_variable_defined?(:@lex) ? @lex : nil
         lex_segs = instance_variable_defined?(:@lex_segments) ? @lex_segments : nil
@@ -157,10 +240,7 @@ module Legion
         { level: level, event: event }
       end
 
-      def fire_hooks(level, message)
-        return unless Legion::Logging::Hooks.enabled?
-        return if Legion::Logging::Hooks.hooks[level].empty?
-
+      def fire_log_writer(level, message)
         lex_val  = instance_variable_defined?(:@lex) ? @lex : nil
         lex_segs = instance_variable_defined?(:@lex_segments) ? @lex_segments : nil
 
@@ -171,7 +251,14 @@ module Legion
           lex_segments:  lex_segs,
           caller_offset: 4
         )
-        Legion::Logging::Hooks.fire(level, event)
+        lex_name = event[:lex] || 'core'
+        component = event.dig(:caller, :file).to_s[%r{/(runners|actors|transport|helpers|builders)/}, 1] || 'unknown'
+        routing_key = "legion.logging.log.#{level}.#{lex_name}.#{component}"
+        Legion::Logging.log_writer.call(event, routing_key: routing_key)
+      rescue StandardError => e
+        if respond_to?(:log) && log.respond_to?(:warn)
+          log.warn("fire_log_writer failed for level=#{level}, routing_key=#{routing_key}: #{e.class}: #{e.message}")
+        end
       end
     end
   end

data/lib/legion/logging/redactor.rb

@@ -4,12 +4,18 @@ module Legion
   module Logging
     module Redactor
       PATTERNS = {
-        ssn:         /\b\d{3}-\d{2}-\d{4}\b/,
-        email:       /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/,
-        phone:       /\b(?:\+1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/,
-        mrn:         /\bMRN[:\s]*\d{6,10}\b/i,
-        dob:         %r{\bDOB[:\s]*\d{1,2}[/-]\d{1,2}[/-]\d{2,4}\b}i,
-        credit_card: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/
+        ssn:            /\b\d{3}-\d{2}-\d{4}\b/,
+        email:          /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/,
+        phone:          /\b(?:\+1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/,
+        mrn:            /\bMRN[:\s]*\d{6,10}\b/i,
+        dob:            %r{\bDOB[:\s]*\d{1,2}[/-]\d{1,2}[/-]\d{2,4}\b}i,
+        credit_card:    /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/,
+        vault_token:    /\bhvs\.[A-Za-z0-9_-]{20,}\b/,
+        vault_lease_id: %r{\b[a-z_-]+/creds/[a-z_-]+/[A-Za-z0-9-]{36}\b},
+        jwt:            /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/,
+        vault_uri:      %r{vault://[^"',\]\x7d\s]+},
+        lease_uri:      %r{lease://[^"',\]\x7d\s]+},
+        bearer_token:   %r{Bearer\s+[A-Za-z0-9._~+/=-]{20,}}i
       }.freeze
 
       SENSITIVE_FIELDS = %w[password secret token api_key authorization].freeze

data/lib/legion/logging/siem_exporter.rb

@@ -37,12 +37,17 @@ module Legion
         end
 
         def format_for_elk(event, index: 'legion')
-          {
+          result = {
             '@timestamp' => Time.now.utc.iso8601,
             'index'      => index,
             'message'    => redact_phi(event.to_s),
             'source'     => 'legion'
           }
+          if event.is_a?(Hash)
+            category = event[:category] || event['category']
+            result['category'] = category.to_s if category
+          end
+          result
         end
       end
     end

data/lib/legion/logging/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Logging
-    VERSION = '1.3.5'
+    VERSION = '1.4.2'
   end
 end

data/lib/legion/logging.rb

@@ -4,10 +4,10 @@ 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 'legion/logging/async_writer'
 require 'legion/logging/helper'
+require 'legion/logging/category_registry'
 
 require 'json'
 require 'logger'
@@ -19,14 +19,27 @@ 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
+      attr_writer :log_writer, :exception_writer
+
+      DEFAULT_LOG_WRITER       = ->(_event, routing_key:) {}
+      DEFAULT_EXCEPTION_WRITER = ->(_event, routing_key:, headers:, properties:) {}
+
+      def log_writer
+        @log_writer || DEFAULT_LOG_WRITER
+      end
+
+      def exception_writer
+        @exception_writer || DEFAULT_EXCEPTION_WRITER
+      end
+
+      def register_category(name, description: nil, expected_fields: [])
+        CategoryRegistry.register_category(name, description: description, expected_fields: expected_fields)
+      end
+
+      def registered_categories
+        CategoryRegistry.registered_categories
+      end
 
       def setup(level: 'info', format: :text, async: true, **options)
         output(**options)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-logging
 version: !ruby/object:Gem::Version
-  version: 1.3.5
+  version: 1.4.2
 platform: ruby
 authors:
 - Esity
@@ -47,6 +47,8 @@ extra_rdoc_files:
 - LICENSE
 - README.md
 files:
+- ".github/CODEOWNERS"
+- ".github/dependabot.yml"
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rubocop.yml"
@@ -59,9 +61,9 @@ files:
 - lib/legion/logging.rb
 - lib/legion/logging/async_writer.rb
 - lib/legion/logging/builder.rb
+- lib/legion/logging/category_registry.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
 - lib/legion/logging/multi_io.rb

data/lib/legion/logging/hooks.rb

@@ -1,46 +0,0 @@
-# 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 => e
-            warn("Legion::Logging::Hooks#fire hook failed at level=#{level}: #{e.message}")
-            nil
-          end
-        end
-      end
-    end
-  end
-end