legion-logging 1.5.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62c3c14ff8e6f67a11941a869f4f4ea2b682686c85c41bb1568368b448f23d0c
-  data.tar.gz: af9c1588f601a09f6b986d9dc47cc07b1c8e9b966e482b45d1a7242342e8d500
+  metadata.gz: 46129a3dbab733493155c3883562e0b8f867959f9749b0ead2c55096eaaa91f0
+  data.tar.gz: e5de12a36bdaa85ceca97cf8936312257ad607393b56fa3663ac0f827d850315
 SHA512:
-  metadata.gz: 66a26f844b44432886b1d703d93dbb9547134ede3542610861e123e240b8ec89746d7bdc522ae8e831c93e212f9e1a9bff5fc9b2fa19a78dfb47007373c5e0ab
-  data.tar.gz: add0a140cbe3c101dc83dcfb4b1c3eef385e4c778a4b6957be6d71b2ec95a9316c3b36d7b687906867046d482b2246ad0a44e8fd4cc98472ad1157994207146a
+  metadata.gz: cbedead38cab56af14b780484b110f6f9a8bb6fbc28934478f203d02dea738208fe9fbc63e3c7bdb8d8cc90a33b3328ba39e5059cff85a0ab8be7e83a7068c7f
+  data.tar.gz: 337d49c5e424fc9cf487cec98295e4fd80a71da2882a5892c2b478d896cf05e52f6f10632719737df4072abbc555193c1475ae7b01d0e9f51d88ac5df3cc62fc

data/CHANGELOG.md

@@ -1,8 +1,11 @@
 # Legion::Logging Changelog
 
-## [1.5.0] - 2026-04-02
+## [1.5.1] - 2026-04-08
 
 ### Added
+- `Legion::Logging::MethodTracer` module: opt-in TracePoint-based method call tracing with indent-aware call/return output and parameter formatting
+- `Helper.included` / `Helper.extended` hooks auto-attach `MethodTracer` when `MethodTracer::ENABLED` is true
+- `log_exception` now formats backtrace (up to 10 frames + overflow count) inline in the stdout/file log line
 - `Legion::Logging.current_settings` and `.configuration_generation` so helper mixins can refresh memoized tagged loggers after runtime reconfiguration
 - Component logger overrides from local `settings`, top-level `Legion::Settings[component]`, and `Legion::Settings.dig(:extensions, component)` for `log_level`, `trace`, `trace_size`, and `extended`
 - `Methods#emit_tagged` / `TaggedLogger#dispatch` path so component-level loggers can emit with their own level while preserving tagged context

data/CLAUDE.md

@@ -8,40 +8,50 @@
 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.3.2
+**Version**: 1.5.0
 **License**: Apache-2.0
 
 ## Architecture
 
 ```
 Legion::Logging (singleton module)
-├── Methods         # Log level methods: debug, info, warn, error, fatal, unknown
-├── 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)
-├── Shipper         # Buffered log event forwarding (file/http transports)
-├── Redactor        # PII/PHI pattern redaction
-└── Version         # VERSION constant
+├── Methods           # Log level methods: debug, info, warn, error, fatal, unknown; log_exception helper
+├── 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); fingerprint for dedup
+├── 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
+├── TaggedLogger      # Logger wrapper that prepends structured tags to each message
+├── CategoryRegistry  # Registry of named log categories with description and expected_fields
+├── MethodTracer      # Tracing module for instrumenting method calls (call/return, formatted args)
+├── SIEMExporter      # PHI-redacting SIEM export (Splunk HEC, ELK/OpenSearch)
+├── Shipper           # Buffered log event forwarding; sub-transports: FileTransport, HttpTransport
+├── Redactor          # PII/PHI + secret pattern redaction; opt-in via logging.redaction.enabled
+└── Version           # VERSION constant
+
+# Module-level writers (pluggable lambda slots replacing old Hooks for AMQP forwarding)
+Legion::Logging.log_writer       # -> lambda(->(event, routing_key:) {})
+Legion::Logging.exception_writer # -> lambda(->(event, routing_key:, headers:, properties:) {})
 ```
 
 ### Key Design Patterns
 
-- **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:, 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
+- **Singleton Module**: `Legion::Logging` uses `class << self` — called directly: `Legion::Logging.info("msg")`
+- **Rainbow Colorization**: Console output uses Rainbow gem for colored terminal output. Color auto-disabled in JSON format and when writing to a log file.
+- **Setup Method**: `Legion::Logging.setup(level:, format:, async:, **options)` configures output, level, format, and async mode. Increments `configuration_generation` on each call.
+- **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[: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 (disables color)
 - **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. 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.
+- **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. 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. `fingerprint` produces MD5 for dedup in log aggregation.
 - **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.
+- **Writer Lambdas**: `log_writer` and `exception_writer` are module-level lambda slots for forwarding to external systems (AMQP, etc.). Default implementations are no-ops. Set via `Legion::Logging.log_writer = lambda`.
+- **CategoryRegistry**: Named log categories with description and expected_fields. Register via `Legion::Logging.register_category`. Used for structured log validation.
+- **Redactor**: Opt-in PII/PHI redaction (`logging.redaction.enabled: true`). Guards against Settings recursive init via `@loader` ivar check. Patterns: SSN, phone, MRN, DOB, Vault tokens, JWTs, bearer tokens, lease IDs.
 
 ## Dependencies
 
@@ -62,7 +72,15 @@ Legion::Logging (singleton module)
 | `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/event_builder.rb` | Structured event payload builder; `fingerprint` for MD5 dedup |
+| `lib/legion/logging/tagged_logger.rb` | Logger wrapper that prepends structured tags to each message |
+| `lib/legion/logging/category_registry.rb` | Named log category registration and lookup |
+| `lib/legion/logging/method_tracer.rb` | Method call tracing instrumentation (call/return, formatted args) |
+| `lib/legion/logging/shipper.rb` | Buffered log event forwarding to external systems |
+| `lib/legion/logging/shipper/file_transport.rb` | File-based log shipper transport |
+| `lib/legion/logging/shipper/http_transport.rb` | HTTP-based log shipper transport |
+| `lib/legion/logging/siem_exporter.rb` | PHI-redacting SIEM export (Splunk HEC, ELK format) |
+| `lib/legion/logging/redactor.rb` | PII/PHI + secret pattern redaction (opt-in) |
 | `lib/legion/logging/version.rb` | VERSION constant |
 
 ## Role in LegionIO

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.4.1
+**Version**: 1.5.0
 
 ## Installation
 

data/lib/legion/logging/helper.rb

@@ -2,6 +2,7 @@
 
 require 'securerandom'
 require_relative 'tagged_logger'
+require_relative 'method_tracer'
 
 module Legion
   module Logging
@@ -102,6 +103,14 @@ module Legion
         publish_exception(event, level) if structured_exception_support?
       end
 
+      def self.included(base)
+        MethodTracer.attach(base) if defined?(MethodTracer) && MethodTracer::ENABLED
+      end
+
+      def self.extended(base)
+        MethodTracer.attach(base, match_singleton: true) if defined?(MethodTracer) && MethodTracer::ENABLED
+      end
+
       private
 
       def build_exception_event(exception:, level:, spec:, handled:, task_id:, payload_summary:)

data/lib/legion/logging/method_tracer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    module MethodTracer
+      ENABLED = false
+      ATTACHED = {} # rubocop:disable Style/MutableConstant
+      ATTACHED_MUTEX = Mutex.new
+      private_constant :ATTACHED_MUTEX
+
+      def self.attach(base, match_singleton: false)
+        return unless ENABLED
+
+        ATTACHED_MUTEX.synchronize do
+          return if ATTACHED.key?(base)
+
+          base_name = base.to_s
+          tp = TracePoint.new(:call, :return) do |trace|
+            next unless trace.defined_class == base || (match_singleton && trace.defined_class == base.singleton_class)
+
+            stack = (Thread.current[:_legion_trace_stack] ||= [])
+
+            case trace.event
+            when :call
+              params = format_params(trace)
+              params_segment = params.empty? ? '' : ", #{params.join(', ')}"
+              indent = '  ' * stack.size
+              puts "#{indent}-> #{trace.method_id}, #{base_name}#{params_segment}"
+              stack.push(trace.method_id)
+            when :return
+              stack.pop
+              indent = '  ' * stack.size
+              puts "#{indent}<- #{trace.method_id}, #{base_name}"
+            end
+          end
+          tp.enable
+          ATTACHED[base] = tp
+        end
+      end
+
+      def self.detach(base)
+        ATTACHED_MUTEX.synchronize do
+          tp = ATTACHED.delete(base)
+          tp&.disable
+        end
+      end
+
+      def self.detach_all
+        ATTACHED_MUTEX.synchronize do
+          ATTACHED.each_value(&:disable)
+          ATTACHED.clear
+        end
+      end
+
+      def self.format_params(trace_point)
+        trace_point.parameters.filter_map do |type, name|
+          next unless name
+
+          val = begin
+            trace_point.binding.local_variable_get(name)
+          rescue StandardError
+            '?'
+          end
+          case type
+          when :req, :opt then "#{name}=#{val.inspect}"
+          when :keyreq, :key then "#{name}: #{val.inspect}"
+          when :rest then "*#{name}"
+          when :keyrest then "**#{name}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/logging/methods.rb

@@ -104,9 +104,18 @@ module Legion
                         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)
+        # 1. Log human-readable line + backtrace to stdout/file (bypass writer callbacks)
         msg = exception.respond_to?(:message) ? exception.message : exception.to_s
         msg = maybe_redact(msg)
+        bt = Array(exception.backtrace)
+        if bt.any?
+          limit = defined?(Legion::Logging::Helper::EXCEPTION_BACKTRACE_LIMIT) ? Legion::Logging::Helper::EXCEPTION_BACKTRACE_LIMIT : 10
+          lines = ["#{exception.class}: #{msg}"]
+          bt.first(limit).each { |frame| lines << "  #{frame}" }
+          remaining = bt.length - limit
+          lines << "  ... #{remaining} more" if remaining.positive?
+          msg = lines.join("\n")
+        end
         log.public_send(level, msg) if respond_to?(:log) && log.respond_to?(level)
 
         # 2. Build rich exception event

data/lib/legion/logging/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Logging
-    VERSION = '1.5.0'
+    VERSION = '1.5.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-logging
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.1
 platform: ruby
 authors:
 - Esity
@@ -66,6 +66,7 @@ files:
 - lib/legion/logging/helper.rb
 - lib/legion/logging/hooks.rb
 - lib/legion/logging/logger.rb
+- lib/legion/logging/method_tracer.rb
 - lib/legion/logging/methods.rb
 - lib/legion/logging/multi_io.rb
 - lib/legion/logging/redactor.rb