legion-logging 1.5.0 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62c3c14ff8e6f67a11941a869f4f4ea2b682686c85c41bb1568368b448f23d0c
-  data.tar.gz: af9c1588f601a09f6b986d9dc47cc07b1c8e9b966e482b45d1a7242342e8d500
+  metadata.gz: 57e4eef04828ffa39cae5277822be4f2f5264d4010b05e724dbb179f0af5b771
+  data.tar.gz: 740663a6979cf6b5c5d90a12bc8c43e0fcd989b8d8253269d8a1f1bf9aff9d03
 SHA512:
-  metadata.gz: 66a26f844b44432886b1d703d93dbb9547134ede3542610861e123e240b8ec89746d7bdc522ae8e831c93e212f9e1a9bff5fc9b2fa19a78dfb47007373c5e0ab
-  data.tar.gz: add0a140cbe3c101dc83dcfb4b1c3eef385e4c778a4b6957be6d71b2ec95a9316c3b36d7b687906867046d482b2246ad0a44e8fd4cc98472ad1157994207146a
+  metadata.gz: c590642e775a8f6ed7f87f9b4525049033c3e3f42635ea2e460e5b4ddd89e646a97d8744b80755a82db340ba6e813d8e95e3a8b27ffc17a63f8f3aee99e5b5a6
+  data.tar.gz: b812f47d57057a466655f22ae1f3922b6326a22fd40297ce602850069092efaf20ff40a6689ecbfe22a7498429bb3266df70ec40efb69617d11da045695155bd

data/.gitignore

@@ -9,7 +9,8 @@
 /tmp/
 /legion/.idea/
 /.idea/
+*.gem
 *.key
 # rspec failure tracking
 .rspec_status
-legionio.key
+legionio.key

data/CHANGELOG.md

@@ -1,8 +1,16 @@
 # Legion::Logging Changelog
 
-## [1.5.0] - 2026-04-02
+## [1.5.2] - 2026-04-27
+
+### Changed
+- Exception stdout/file log lines now include the full backtrace instead of truncating after 10 frames with a `... N more` suffix.
+
+## [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.2
 
 ## Installation
 
@@ -96,23 +96,46 @@ end
 
 ### Exception Logging
 
-`log_exception` provides a single call for complete structured exception events with component context:
+`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.
 
 ```ruby
-Legion::Logging.log_exception(exception,
-  handled: true,
-  component_type: :runner,
-  lex: 'my_extension',
-  task_id: 'abc-123')
+begin
+  runner.call
+rescue StandardError => e
+  Legion::Logging.log_exception(
+    e,
+    handled: true,
+    component_type: :runner,
+    lex: 'my_extension',
+    task_id: 'abc-123'
+  )
+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.
+
+Structured exception events include:
+
+- exception class and message
+- full backtrace array
+- caller file, line, and function where available
+- log level and handled/unhandled status
+- component type, lex name, gem name, version, and source path metadata
+- task and thread context
+- stable error fingerprint for deduplication
+
 ### 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) }
+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:)
+end
 ```
 
 ### EventBuilder
@@ -121,7 +144,9 @@ Legion::Logging.log_writer = ->(context, routing_key:) { publish_log(context) }
 
 ### 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.
+`Legion::Logging::Redactor` redacts PII/PHI patterns (SSN, email, phone, MRN, DOB, credit card) plus Vault tokens, JWTs, bearer tokens, `vault://` URIs, `lease://` URIs, and lease IDs from log messages. Redaction is opt-in for text log lines: 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.
+
+Structured exception events are redacted before publishing when the redactor is loaded. This includes event identity fields such as `user`, so email-shaped local usernames are not forwarded raw.
 
 ## Requirements
 

data/lib/legion/logging/helper.rb

@@ -2,6 +2,7 @@
 
 require 'securerandom'
 require_relative 'tagged_logger'
+require_relative 'method_tracer'
 
 module Legion
   module Logging
@@ -31,7 +32,6 @@ module Legion
         'middleware' => :middleware
       }.freeze
 
-      EXCEPTION_BACKTRACE_LIMIT = 10
       EXCEPTION_PRIORITY = { warn: 0, error: 5, fatal: 9 }.freeze
       EXCEPTION_COLORS = {
         fatal:   :darkred,
@@ -102,6 +102,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:)
@@ -480,11 +488,7 @@ module Legion
         lines << "  #{context_line}" unless context_line.empty?
 
         bt = exception.backtrace
-        if bt&.any?
-          bt.first(EXCEPTION_BACKTRACE_LIMIT).each { |frame| lines << "  #{frame}" }
-          remaining = bt.length - EXCEPTION_BACKTRACE_LIMIT
-          lines << "  ... #{remaining} more" if remaining.positive?
-        end
+        bt.each { |frame| lines << "  #{frame}" } if bt&.any?
 
         lines.join("\n")
       end

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,15 @@ 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?
+          lines = ["#{exception.class}: #{msg}"]
+          bt.each { |frame| lines << "  #{frame}" }
+          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.2'
   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.2
 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