rails_nexus 2.1.4 → 2.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68f6936b492e804cacc457cb32a3c211f46a1200b57efe2c478fa3c6769fa7e2
-  data.tar.gz: 85fcf9d42acb0def8427800684cffffccfbe03b63791bbe4c3d1938c9cef33da
+  metadata.gz: 906957a4703c0c553eca5cb3966cccec4c71b117a07653e17c648ff96098e819
+  data.tar.gz: 2bc584d69992b1c1dd9947b266db3541ced28b24a9be7af5dddc909ad9a2eb05
 SHA512:
-  metadata.gz: 0fe9502389240d9c4f486613ca0730da70fa0f4d932b0b86359f6d8587d5c456e16ac90f8caaeea9c9bb204e77a359c3fbf493ebeb5244119a1071d228ccac01
-  data.tar.gz: 7c6bab5a7baafe7dbc87fc89d2c6cf2de10137906cc910b4b2fcbb5f935f4ec89923ee6d97fa592ffc3ebbd6eca4e9e38a1e8ac07d1b96bcac1212f680a3f276
+  metadata.gz: 178c8c34f47ad84234bc910222c9fc507b89869bb09c6b93b1c88c424277859696aebedf4dd7c2d1f838a13ea9768bc1b747a8ccc47c45e169e91f594815a149
+  data.tar.gz: dd78c3b2c913ee5f2f15957b074a7c10083dd3e26eb81bfb2c1aa0cb1081076676a4e03d23d698774a2892a6fa5eb69b2e9baed8ed5d6159bbd2141869918724

data/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to RailsNexus will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- **Rich exception diagnostics** — Structured logs and persisted exception records now capture filtered request/user context, cause chains, runtime details, app version, custom exception data, and exception instance variables with bounded serialization.
+- **Diagnostic context UI** — Exception details expose fingerprint, occurrence, platform, app/user metadata, and a dedicated context tab.
+
+### Fixed
+- **Safe exception boundary** — Capture and custom-context failures no longer replace the original application exception.
+- **Precise exception grouping** — Fingerprints now include normalized messages and source frames so unrelated failures in the same action are not merged.
+
 ## [2.1.4] - 2026-08-24
 
 ### Changed

data/README.md

@@ -144,6 +144,17 @@ end
 
 RailsNexus logs the exception and then re-raises it so Rails keeps its normal error handling.
 
+Each capture includes the full filtered request context, request ID, user agent,
+current-user identity, normalized fingerprint, cause chain, bounded backtrace,
+exception instance variables, runtime/system health, and any `exception_data`
+returned by your configuration. Custom and exception data appear in the
+**Context** tab. Passwords, tokens, cookies, authorization headers, and the host
+application's configured filter parameters are replaced with `[FILTERED]`.
+
+When structured logging is enabled, the Rails logger receives the same context
+as a single JSON event. `log_backtrace_limit`, `log_params`, and
+`log_user_info` control how much is included in that event.
+
 ### API controllers
 
 For `ActionController::API` subclasses (e.g., API namespaces):

data/app/controllers/rails_nexus/application_controller.rb

@@ -1,11 +1,16 @@
 module RailsNexus
   class ApplicationController < ActionController::Base
-    include Pagy::Backend
+    include Pagy::Method
     protect_from_forgery with: :exception
     before_action :rails_nexus_require_auth!
 
     private
 
+    def rails_nexus_pagy(collection, **options)
+      limit = options.delete(:limit) || RailsNexus.configuration.per_page || 30
+      pagy(:offset, collection, limit: limit, **options)
+    end
+
     def rails_nexus_require_auth!
       auth_block = RailsNexus.configuration.auth_block
       return if auth_block&.call(self)

data/app/controllers/rails_nexus/cron_jobs_controller.rb

@@ -23,7 +23,7 @@ module RailsNexus
 
       requested_size = params[:per_page].to_i
       page_size = requested_size.between?(1, 100) ? requested_size : 30
-      @pagy, @cron_jobs = pagy(cron_jobs, items: page_size)
+      @pagy, @cron_jobs = rails_nexus_pagy(cron_jobs, limit: page_size)
     end
 
     def show
@@ -42,7 +42,6 @@ module RailsNexus
 
     def retry_job
       cron_job = CronJob.find(params[:id])
-      # Re-run the job (implementation depends on job scheduler)
       redirect_to cron_jobs_path, notice: "Retrying job: #{cron_job.name}"
     end
 
@@ -51,6 +50,5 @@ module RailsNexus
     def set_cron_job
       @cron_job = CronJob.find(params[:id])
     end
-
   end
 end

data/app/controllers/rails_nexus/logged_exceptions_controller.rb

@@ -96,9 +96,7 @@ module RailsNexus
       load_filter_options
       @q = ransack_search
       load_stats if RailsNexus.configuration.show_stats
-      @pagy, @exceptions = pagy(@q.result(distinct: true), items: page_size)
-    rescue Pagy::OverflowError
-      @pagy, @exceptions = pagy(@q.result(distinct: true), page: 1, items: page_size)
+      @pagy, @exceptions = rails_nexus_pagy(@q.result(distinct: true), limit: page_size)
     end
 
     def ransack_search
@@ -218,7 +216,9 @@ module RailsNexus
         backtrace: @exception.backtrace.present?,
         request: @exception.request.present?,
         environment: @exception.environment.present?,
-        user_info: @exception.user_info.present?
+        user_info: @exception.user_info.present?,
+        diagnostic_context: (@exception.respond_to?(:local_variables) && @exception.local_variables.present?) ||
+          (@exception.respond_to?(:instance_variables) && @exception.instance_variables.present?)
       }
     end
   end

data/app/helpers/rails_nexus/application_helper.rb

@@ -1,10 +1,12 @@
 module RailsNexus
   module ApplicationHelper
-    include Pagy::Frontend
-
     def page_title(text)
       title = [RailsNexus.application_name.presence, text].compact.join(" :: ")
       content_for(:title, title)
     end
+
+    def rails_nexus_pagy_nav(pagy)
+      pagy.series_nav
+    end
   end
 end

data/app/models/rails_nexus/logged_exception.rb

@@ -5,11 +5,13 @@ module RailsNexus
     self.table_name = "rails_nexus_exceptions"
     HOSTNAME = Socket.gethostname
 
-    serialize :cause_chain, coder: JSON unless method_defined?(:cause_chain)
-    serialize :breadcrumbs, coder: JSON unless method_defined?(:breadcrumbs)
-    serialize :system_health, coder: JSON unless method_defined?(:system_health)
-    serialize :local_variables, coder: JSON unless method_defined?(:local_variables)
-    serialize :instance_variables, coder: JSON unless method_defined?(:instance_variables)
+    serialize :cause_chain, coder: JSON
+    serialize :breadcrumbs, coder: JSON
+    serialize :system_health, coder: JSON
+    serialize :local_variables, coder: JSON
+    # This column intentionally overrides Object#instance_variables so the
+    # captured exception context is readable through the normal model API.
+    serialize :instance_variables, coder: JSON
 
     # ─── Associations ──────────────────────────────────────────────
     has_many :comments, class_name: "RailsNexus::Comment", dependent: :destroy
@@ -45,8 +47,13 @@ module RailsNexus
           end
         end
 
+        data = normalize_context_data(data)
         message = exception.message.to_s
-        message += "\n* Extra Data\n\n#{data}" unless data.blank?
+        message += "\n* Extra Data\n\n#{data.inspect}" unless data.blank?
+
+        request = safe_call(controller, :request)
+        controller_name = safe_call(controller, :controller_path) || controller.class.name
+        action_name = safe_call(controller, :action_name)
 
         # Detect platform from user agent and request format
         platform_data = detect_platform(controller)
@@ -57,15 +64,18 @@ module RailsNexus
         end
 
         # Extract user info for impact scoring
-        user = controller.respond_to?(:current_user, true) ? controller.current_user : nil
-        user_id = user&.id&.to_s || data[:user_id]&.to_s rescue nil
-        user_type = user.class.name rescue nil
+        user = current_user_for(controller)
+        user_context = capture_user_context(user, data)
+        user_id = user_context[:id]&.to_s || data[:user_id]&.to_s || data["user_id"]&.to_s
+        user_type = user_context[:type]
 
         # Generate fingerprint for grouping
         fingerprint = generate_fingerprint(
           exception.class.name,
-          controller.controller_path,
-          controller.action_name
+          controller_name,
+          action_name,
+          message: exception.message,
+          backtrace: exception.backtrace
         )
 
         # Check if this fingerprint already exists (occurrence counting)
@@ -73,36 +83,34 @@ module RailsNexus
 
         attrs = {
           exception_class: exception.class.name,
-          controller_name: controller.controller_path,
-          action_name: controller.action_name,
+          controller_name: controller_name,
+          action_name: action_name,
           message: message,
           backtrace: exception.backtrace,
-          request: controller.request,
-          user_info: user,
-          remote_ip: controller.request.remote_ip,
+          request: request,
+          user_info: user_context.except(:id, :type).presence&.to_json,
+          user_agent: safe_call(request, :user_agent),
+          remote_ip: safe_call(request, :remote_ip),
           user_id: user_id,
           user_type: user_type,
           fingerprint: fingerprint,
           platform: platform_data[:platform],
           platform_version: platform_data[:platform_version],
           device_type: platform_data[:device_type],
+          app_version: app_version(request, data),
           cause_chain: extract_cause_chain(exception),
           breadcrumbs: breadcrumbs_data.presence,
           system_health: capture_system_health,
+          local_variables: data.presence,
+          instance_variables: capture_exception_variables(exception).presence,
           occurrence_count: existing ? existing.occurrence_count + 1 : 1
         }
 
         if existing
-          existing.update!(
-            message: message,
-            backtrace: exception.backtrace,
-            request: controller.request,
-            user_info: user,
-            remote_ip: controller.request.remote_ip,
+          existing.update!(attrs.except(:fingerprint, :occurrence_count).merge(
             occurrence_count: existing.occurrence_count + 1,
-            cause_chain: attrs[:cause_chain],
-            system_health: attrs[:system_health]
-          )
+            created_at: Time.current
+          ))
           RailsNexus::StormProtection.record_captured if defined?(RailsNexus::StormProtection)
           existing
         else
@@ -115,6 +123,84 @@ module RailsNexus
       def host_name
         HOSTNAME
       end
+
+      private
+
+      def normalize_context_data(data)
+        data = data.to_unsafe_h if data.respond_to?(:to_unsafe_h)
+        data = data.to_h if !data.is_a?(Hash) && data.respond_to?(:to_h)
+        data = { value: data } unless data.is_a?(Hash)
+        safe_context_value(RailsNexus.filter_sensitive_data(data))
+      rescue StandardError
+        {}
+      end
+
+      def current_user_for(controller)
+        controller.send(:current_user) if controller.respond_to?(:current_user, true)
+      rescue StandardError
+        nil
+      end
+
+      def capture_user_context(user, data)
+        return {} unless RailsNexus.configuration.user_impact_tracking
+
+        context = {
+          id: safe_call(user, :id),
+          type: user&.class&.name,
+          email: safe_call(user, :email),
+          username: safe_call(user, :username),
+          name: safe_call(user, :name)
+        }.compact
+        context[:id] ||= data[:user_id] || data["user_id"]
+        safe_context_value(RailsNexus.filter_sensitive_data(context))
+      rescue StandardError
+        {}
+      end
+
+      def capture_exception_variables(exception)
+        values = exception.instance_variables.each_with_object({}) do |name, result|
+          result[name.to_s.delete_prefix("@")] = safe_context_value(exception.instance_variable_get(name))
+        rescue StandardError
+          result[name.to_s.delete_prefix("@")] = "[unavailable]"
+        end
+        RailsNexus.filter_sensitive_data(values)
+      rescue StandardError
+        {}
+      end
+
+      def app_version(request, data)
+        data[:app_version] || data["app_version"] ||
+          safe_call(request, :get_header, "HTTP_X_APP_VERSION") ||
+          safe_call(request, :get_header, "HTTP_X_CLIENT_VERSION")
+      end
+
+      def safe_call(object, method_name, *args)
+        object.public_send(method_name, *args) if object
+      rescue StandardError
+        nil
+      end
+
+      def safe_context_value(value, depth = 0, seen = {})
+        return "[MAX DEPTH]" if depth >= 5
+        return value if value.nil? || value == true || value == false || value.is_a?(Numeric)
+        return value.to_s.truncate(10_000) if value.is_a?(String) || value.is_a?(Symbol)
+        return value.iso8601 if value.respond_to?(:iso8601) && (value.is_a?(Time) || value.is_a?(Date))
+
+        object_id = value.object_id
+        return "[CIRCULAR]" if seen[object_id]
+        seen[object_id] = true
+
+        case value
+        when Hash
+          value.first(100).to_h.transform_values { |child| safe_context_value(child, depth + 1, seen) }
+        when Array
+          value.first(100).map { |child| safe_context_value(child, depth + 1, seen) }
+        else
+          value.to_s.truncate(10_000)
+        end
+      ensure
+        seen&.delete(object_id) if defined?(object_id) && object_id
+      end
     end
 
     scope :by_exception_class, lambda { |exception_class| where(:exception_class => exception_class) }
@@ -147,18 +233,30 @@ module RailsNexus
     end
 
     # Generate fingerprint for grouping similar exceptions
-    def self.generate_fingerprint(exception_class, controller_name, action_name)
+    def self.generate_fingerprint(exception_class, controller_name, action_name, message: nil, backtrace: nil)
       require "digest"
-      Digest::SHA256.hexdigest("#{exception_class}#{controller_name}#{action_name}")[0..15]
+      normalized_message = message.to_s
+        .gsub(/\b\d+\b/, "?")
+        .gsub(/\b[0-9a-f]{8,}\b/i, "?")
+        .gsub(/\s+/, " ")
+        .strip
+      source = Array(backtrace).find { |line| line.to_s.include?(Rails.root.to_s) } || Array(backtrace).first
+      normalized_source = source.to_s.sub(/:\d+(?::in .*)?\z/, "")
+      parts = [exception_class, controller_name, action_name, normalized_message, normalized_source]
+      Digest::SHA256.hexdigest(parts.join("\0"))[0, 16]
     end
 
     # Detect platform from user_agent and request
     def self.detect_platform(controller)
       request = controller.request
+      return { platform: "unknown", platform_version: nil, device_type: "unknown", app_version: nil } unless request
+
       user_agent = request.respond_to?(:user_agent) ? request.user_agent.to_s.downcase : ""
 
       # API detection: no user_agent or JSON/XML format
-      if user_agent.blank? || request.format&.ref == "json" || request.format&.ref == "xml"
+      format = request.respond_to?(:format) ? request.format : nil
+      format_ref = format.respond_to?(:ref) ? format.ref.to_s : format.to_s
+      if user_agent.blank? || %w[json xml].include?(format_ref)
         return { platform: "api", platform_version: nil, device_type: "server", app_version: nil }
       end
 
@@ -196,6 +294,8 @@ module RailsNexus
 
       # Default: web
       { platform: "web", platform_version: nil, device_type: "unknown", app_version: nil }
+    rescue StandardError
+      { platform: "unknown", platform_version: nil, device_type: "unknown", app_version: nil }
     end
 
     # Platform analytics
@@ -497,16 +597,35 @@ module RailsNexus
       if request.is_a?(String)
         write_attribute :request, request
       elsif request.respond_to?(:env) && request.env.is_a?(Hash)
-        filtered_env = RailsNexus.filter_sensitive_data(request.env)
-        keys = filtered_env.keys.map(&:to_s).sort
-        max_length = keys.map(&:length).max || 0
-        env = keys.each_with_object([]) do |key, memo|
-          value = filtered_env[key] || filtered_env[key.to_sym]
-          memo << ("* %-*s: %s" % [max_length, key, value.to_s.strip])
-        end
-        write_attribute(:environment, (env << "* Process: #{$$}" << "* Server : #{self.class.host_name}").join("\n"))
-
-        method_str = request.respond_to?(:get?) && request.get? ? "" : " #{request.respond_to?(:method) ? request.method.to_s.upcase : "GET"}"
+        captured_env_keys = %w[
+          REQUEST_METHOD HTTP_HOST SERVER_NAME SERVER_PORT HTTPS
+          HTTP_X_FORWARDED_PROTO HTTP_X_FORWARDED_HOST HTTP_X_REQUEST_ID
+          HTTP_X_CORRELATION_ID HTTP_TRACEPARENT HTTP_TRACESTATE HTTP_BAGGAGE
+          action_dispatch.request_id HTTP_REFERER HTTP_ORIGIN CONTENT_TYPE
+          CONTENT_LENGTH HTTP_ACCEPT HTTP_ACCEPT_LANGUAGE HTTP_USER_AGENT
+          HTTP_X_APP_VERSION HTTP_X_CLIENT_VERSION HTTP_AUTHORIZATION HTTP_COOKIE
+        ]
+        captured_env = request.env.slice(*captured_env_keys)
+        filtered_env = RailsNexus.filter_sensitive_data(captured_env)
+        environment = {
+          "Rails Environment" => Rails.env.to_s,
+          "Rails Version" => Rails.version,
+          "Ruby Version" => RUBY_DESCRIPTION,
+          "Process" => Process.pid,
+          "Server" => self.class.host_name
+        }.merge(filtered_env)
+        max_length = environment.keys.map(&:length).max || 0
+        write_attribute(:environment, environment.sort.map do |key, value|
+          "* %-*s: %s" % [max_length, key, value.to_s.strip.truncate(10_000)]
+        end.join("\n"))
+
+        method = if request.respond_to?(:request_method)
+                   request.request_method
+                 elsif request.respond_to?(:method)
+                   request.method
+                 else
+                   "GET"
+                 end
         parameters = request.respond_to?(:parameters) ? RailsNexus.filter_sensitive_data(request.parameters) : {}
         request_path = if request.respond_to?(:path)
                          request.path
@@ -515,12 +634,18 @@ module RailsNexus
                        else
                          "/"
                        end
+        request_id = request.respond_to?(:request_id) ? request.request_id : filtered_env["HTTP_X_REQUEST_ID"]
+        host = filtered_env["HTTP_HOST"] || filtered_env["SERVER_NAME"] || "localhost"
+        protocol = request.respond_to?(:protocol) ? request.protocol : "http://"
         write_attribute(:request, [
-          "* URL:#{method_str} #{request.respond_to?(:protocol) ? request.protocol : "http://"}#{filtered_env["HTTP_HOST"] || "localhost"}#{request_path}",
+          "* Method: #{method.to_s.upcase}",
+          "* URL: #{protocol}#{host}#{request_path}",
+          ("* Request ID: #{request_id}" if request_id.present?),
           "* Format: #{request.respond_to?(:format) ? request.format.to_s : "html"}",
+          ("* Content Type: #{request.content_type}" if request.respond_to?(:content_type) && request.content_type.present?),
           "* Parameters: #{parameters.inspect}",
           "* Rails Root: #{rails_root}"
-        ].join("\n"))
+        ].compact.join("\n"))
       else
         write_attribute :request, request.to_s
       end

data/app/views/rails_nexus/cron_jobs/index.html.erb

@@ -133,7 +133,7 @@
       <%# Pagination %>
       <% if @pagy.pages > 1 %>
         <div class="rn-pagination">
-          <%== pagy_nav(@pagy) %>
+          <%== rails_nexus_pagy_nav(@pagy) %>
         </div>
       <% end %>
     <% end %>

data/app/views/rails_nexus/logged_exceptions/_exceptions.html.erb

@@ -152,7 +152,7 @@
           to <span class="font-medium" style="color: var(--rn-text-secondary)"><%= @pagy.to %></span>
           of <span class="font-medium" style="color: var(--rn-text-secondary)"><%= @pagy.count %></span>
         </p>
-        <div><%== pagy_nav(@pagy) %></div>
+        <div><%== rails_nexus_pagy_nav(@pagy) %></div>
       </div>
     <% end %>
   <% end %>

data/app/views/rails_nexus/logged_exceptions/_show.html.erb

@@ -74,6 +74,9 @@
       <% if @exception_tabs[:user_info] %>
         <button type="button" class="rn-tab" data-action="click->rails_nexus-detail#switchTab" data-rn-tab-param="user_info">User Info</button>
       <% end %>
+      <% if @exception_tabs[:diagnostic_context] %>
+        <button type="button" class="rn-tab" data-action="click->rails_nexus-detail#switchTab" data-rn-tab-param="diagnostic_context">Context</button>
+      <% end %>
       <% if @exception.respond_to?(:cause_chain) && @exception.cause_chain.present? && @exception.cause_chain.is_a?(Array) && @exception.cause_chain.length > 0 %>
         <button type="button" class="rn-tab" data-action="click->rails_nexus-detail#switchTab" data-rn-tab-param="cause_chain">
           Cause Chain
@@ -142,6 +145,36 @@
                 <div class="rn-meta-value" style="font-size: 0.8125rem; word-break: break-all"><%= @exception.user_agent %></div>
               </div>
             <% end %>
+            <% if @exception.respond_to?(:fingerprint) && @exception.fingerprint.present? %>
+              <div class="rn-meta-item">
+                <div class="rn-meta-label">Fingerprint</div>
+                <div class="rn-meta-value mono"><%= @exception.fingerprint %></div>
+              </div>
+            <% end %>
+            <% if @exception.respond_to?(:occurrence_count) && @exception.occurrence_count.present? %>
+              <div class="rn-meta-item">
+                <div class="rn-meta-label">Occurrences</div>
+                <div class="rn-meta-value"><%= number_with_delimiter(@exception.occurrence_count) %></div>
+              </div>
+            <% end %>
+            <% if @exception.respond_to?(:platform) && @exception.platform.present? %>
+              <div class="rn-meta-item">
+                <div class="rn-meta-label">Platform</div>
+                <div class="rn-meta-value"><%= [@exception.platform, @exception.platform_version].compact.join(" ") %></div>
+              </div>
+            <% end %>
+            <% if @exception.respond_to?(:app_version) && @exception.app_version.present? %>
+              <div class="rn-meta-item">
+                <div class="rn-meta-label">App Version</div>
+                <div class="rn-meta-value mono"><%= @exception.app_version %></div>
+              </div>
+            <% end %>
+            <% if @exception.respond_to?(:user_id) && @exception.user_id.present? %>
+              <div class="rn-meta-item">
+                <div class="rn-meta-label">User ID</div>
+                <div class="rn-meta-value mono"><%= @exception.user_id %></div>
+              </div>
+            <% end %>
             <div class="rn-meta-item">
               <div class="rn-meta-label">Exception ID</div>
               <div class="rn-meta-value mono"><%= @exception.id %></div>
@@ -342,6 +375,24 @@
       <% end %>
     </div>
 
+    <%# ─── Tab: Diagnostic Context ────────────────────────────── %>
+    <% if @exception_tabs[:diagnostic_context] %>
+      <div data-rails_nexus-detail-target="tabContent" data-rn-tab-content="diagnostic_context" style="display: none">
+        <% if @exception.respond_to?(:local_variables) && @exception.local_variables.present? %>
+          <div class="rn-detail-section">
+            <div class="rn-detail-section-header"><h3>Custom Exception Data</h3></div>
+            <div class="rn-detail-code" style="max-height: 24rem; overflow: auto"><%= pretty_format(@exception.local_variables) %></div>
+          </div>
+        <% end %>
+        <% if @exception.respond_to?(:instance_variables) && @exception.instance_variables.present? %>
+          <div class="rn-detail-section">
+            <div class="rn-detail-section-header"><h3>Exception Instance Variables</h3></div>
+            <div class="rn-detail-code" style="max-height: 24rem; overflow: auto"><%= pretty_format(@exception.instance_variables) %></div>
+          </div>
+        <% end %>
+      </div>
+    <% end %>
+
   </div>
 
   <%# ─── Tab: Cause Chain ────────────────────────────────────── %>

data/lib/generators/rails_nexus/templates/views/rails_nexus/logged_exceptions/_exceptions.html.erb

@@ -115,7 +115,7 @@
           of <span class="font-medium text-gray-600"><%= @pagy.count %></span>
         </p>
         <div>
-          <%== pagy_nav(@pagy) %>
+          <%== rails_nexus_pagy_nav(@pagy) %>
         </div>
       </div>
     <% end %>

data/lib/rails_nexus/logger.rb

@@ -1,21 +1,20 @@
 # frozen_string_literal: true
 
+require "json"
+
 module RailsNexus
   class Logger
-    # Log levels
     LEVELS = %i[debug info warn error fatal].freeze
+    MAX_CAUSE_DEPTH = 10
+    MAX_VALUE_DEPTH = 5
+    MAX_STRING_LENGTH = 10_000
 
-    # Default context that's attached to every log entry
     DEFAULT_CONTEXT = {
       gem: "rails_nexus",
       version: RailsNexus::VERSION
     }.freeze
 
     class << self
-      # Log an exception with full context
-      #
-      #   RailsNexus::Logger.error(exception, controller: self, extra: { key: "value" })
-      #
       def error(exception, controller: nil, extra: {}, **kwargs)
         log(:error, exception, controller: controller, extra: extra, **kwargs)
       end
@@ -24,6 +23,10 @@ module RailsNexus
         log(:warn, exception, controller: controller, extra: extra, **kwargs)
       end
 
+      def fatal(exception, controller: nil, extra: {}, **kwargs)
+        log(:fatal, exception, controller: controller, extra: extra, **kwargs)
+      end
+
       def info(message, controller: nil, extra: {}, **kwargs)
         log(:info, message, controller: controller, extra: extra, **kwargs)
       end
@@ -32,145 +35,272 @@ module RailsNexus
         log(:debug, message, controller: controller, extra: extra, **kwargs)
       end
 
-      # Log a custom event (not an exception)
-      #
-      #   RailsNexus::Logger.event("user.login", user_id: 123, method: "POST")
-      #
       def event(name, data = {})
-        entry = build_entry(:info, name, nil, extra: data)
-        write_to_output(entry)
-        write_to_file(entry) if RailsNexus.configuration.log_file.present?
+        return unless loggable?(:info)
+
+        entry = build_entry(:info, name.to_s, extra: data)
+        write(entry)
         entry
+      rescue StandardError => error
+        report_internal_error(error)
+        nil
       end
 
-      # Query logs with filters
-      #
-      #   RailsNexus::Logger.query(level: :error, since: 1.hour.ago, limit: 50)
-      #
       def query(level: nil, since: nil, controller_name: nil, limit: 100)
         scope = RailsNexus::LoggedException.order(created_at: :desc)
         scope = scope.where("created_at >= ?", since) if since.present?
-        scope = scope.where(exception_class: level.to_s.camelize) if level.present?
+        scope = scope.none if level.present? && level.to_sym != :error
         scope = scope.where(controller_name: controller_name) if controller_name.present?
         scope.limit(limit)
       end
 
-      # Get aggregated stats
-      #
-      #   RailsNexus::Logger.stats(since: 24.hours.ago)
-      #
       def stats(since: nil)
         scope = RailsNexus::LoggedException.all
         scope = scope.where("created_at >= ?", since) if since.present?
 
         {
           total: scope.count,
+          occurrences: scope.sum(:occurrence_count),
           by_class: scope.group(:exception_class).count,
           by_controller: scope.group(:controller_name).count,
-          by_hour: scope.group_by { |e| e.created_at.hour }.transform_values(&:count),
-          top_exceptions: scope.group(:exception_class).count.sort_by { |_, v| -v }.first(10)
+          by_hour: scope.group_by { |entry| entry.created_at.hour }.transform_values(&:count),
+          top_exceptions: scope.group(:exception_class).count.sort_by { |_, count| -count }.first(10),
+          occurrences_by_class: scope.group(:exception_class).sum(:occurrence_count),
+          occurrences_by_controller: scope.group(:controller_name).sum(:occurrence_count)
         }
       end
 
       private
 
       def log(level, exception_or_message, controller: nil, extra: {}, **kwargs)
-        message = exception_or_message.is_a?(Exception) ? exception_or_message.message : exception_or_message.to_s
-        exception_class = exception_or_message.is_a?(Exception) ? exception_or_message.class.name : nil
+        return unless loggable?(level)
 
-        entry = build_entry(level, message, exception_class,
+        exception = exception_or_message if exception_or_message.is_a?(Exception)
+        entry = build_entry(
+          level,
+          exception ? exception.message.to_s : exception_or_message.to_s,
+          exception: exception,
           controller: controller,
-          extra: extra.merge(kwargs),
-          backtrace: exception_or_message.is_a?(Exception) ? exception_or_message.backtrace&.first(20)&.join("\n") : nil
+          extra: merge_extra(extra, kwargs)
         )
-
-        write_to_output(entry)
-        write_to_file(entry) if RailsNexus.configuration.log_file.present?
+        write(entry)
         entry
+      rescue StandardError => error
+        report_internal_error(error)
+        nil
       end
 
-      def build_entry(level, message, exception_class, controller: nil, extra: {}, backtrace: nil)
+      def build_entry(level, message, exception: nil, controller: nil, extra: {})
         entry = DEFAULT_CONTEXT.merge(
           level: level,
-          message: message,
-          timestamp: Time.current.iso8601
+          message: truncate(message),
+          timestamp: Time.current.iso8601(6),
+          runtime: runtime_context
         )
 
-        entry[:exception_class] = exception_class if exception_class.present?
+        if exception
+          entry[:exception] = exception_context(exception)
+          # Preserve the original public entry keys while also providing the
+          # richer nested exception object.
+          entry[:exception_class] = entry.dig(:exception, :class)
+          entry[:backtrace] = entry.dig(:exception, :backtrace)&.join("\n")
+        end
 
-        # Add controller context
-        if controller.present?
+        if controller
+          entry[:request] = request_context(controller)
           entry[:controller] = {
             class: controller.class.name,
-            action: controller.action_name,
-            path: controller.request&.path,
-            method: controller.request&.request_method,
-            remote_ip: controller.request&.remote_ip,
-            user_agent: controller.request&.user_agent
+            action: entry.dig(:request, :action),
+            path: entry.dig(:request, :url),
+            method: entry.dig(:request, :method),
+            remote_ip: entry.dig(:request, :remote_ip),
+            user_agent: entry.dig(:request, :user_agent)
+          }.compact
+          entry[:params] = entry.dig(:request, :params) if entry.dig(:request, :params)
+        end
+
+        user = user_context(controller)
+        entry[:user] = user if user.present?
+
+        filtered_extra = safe_value(RailsNexus.filter_sensitive_data(extra))
+        entry[:extra] = filtered_extra if filtered_extra.present?
+        entry.compact
+      end
+
+      def exception_context(exception)
+        context = {
+          class: exception.class.name,
+          message: truncate(exception.message.to_s),
+          source: exception.backtrace&.first
+        }
+
+        if RailsNexus.configuration.log_backtrace
+          limit = positive_integer(RailsNexus.configuration.log_backtrace_limit, 20)
+          context[:backtrace] = Array(exception.backtrace).first(limit)
+        end
+
+        causes = []
+        current = exception.cause
+        while current && causes.length < MAX_CAUSE_DEPTH
+          causes << {
+            class: current.class.name,
+            message: truncate(current.message.to_s),
+            source: current.backtrace&.first
           }
+          current = current.cause
+        end
+        context[:causes] = causes if causes.any?
+        context.compact
+      end
 
-          # Add user context
-          if controller.respond_to?(:current_user, true) && controller.current_user.present?
-            entry[:user] = {
-              id: controller.current_user.id,
-              email: controller.current_user.email
-            }
-          end
+      def request_context(controller)
+        request = safe_call(controller, :request)
+        context = {
+          controller: safe_call(controller, :controller_path) || controller.class.name,
+          action: safe_call(controller, :action_name)
+        }
+        return context.compact unless request
 
-          # Add request params (filtered)
-          if controller.request.present?
-            entry[:params] = filter_params(controller.request.filtered_parameters)
-          end
+        context.merge!(
+          request_id: safe_call(request, :request_id),
+          correlation_id: safe_call(request, :get_header, "HTTP_X_CORRELATION_ID"),
+          traceparent: safe_call(request, :get_header, "HTTP_TRACEPARENT"),
+          method: safe_call(request, :request_method) || safe_call(request, :method),
+          url: safe_call(request, :original_url) || safe_call(request, :url) || safe_call(request, :fullpath) || safe_call(request, :path),
+          format: request_format(request),
+          remote_ip: safe_call(request, :remote_ip),
+          user_agent: safe_call(request, :user_agent),
+          referer: safe_call(request, :referer),
+          content_type: safe_call(request, :content_type),
+          content_length: safe_call(request, :content_length)
+        )
+
+        if RailsNexus.configuration.log_params
+          params = safe_call(request, :filtered_parameters) || safe_call(request, :parameters)
+          context[:params] = safe_value(RailsNexus.filter_sensitive_data(params)) if params
         end
 
-        # Add extra metadata
-        entry[:extra] = extra if extra.present?
-        entry[:backtrace] = backtrace if backtrace.present?
+        context.compact
+      end
 
-        entry
+      def user_context(controller)
+        return {} unless controller && RailsNexus.configuration.log_user_info
+        return {} unless controller.respond_to?(:current_user, true)
+
+        user = controller.send(:current_user)
+        return {} unless user
+
+        {
+          id: safe_call(user, :id),
+          type: user.class.name,
+          email: safe_call(user, :email)
+        }.compact
+      rescue StandardError
+        {}
+      end
+
+      def runtime_context
+        {
+          environment: defined?(Rails) && Rails.respond_to?(:env) ? Rails.env.to_s : nil,
+          hostname: Socket.gethostname,
+          pid: Process.pid,
+          thread_id: Thread.current.object_id,
+          ruby_version: RUBY_VERSION,
+          rails_version: defined?(Rails::VERSION) ? Rails::VERSION::STRING : nil
+        }.compact
+      rescue StandardError
+        { pid: Process.pid, ruby_version: RUBY_VERSION }
+      end
+
+      def write(entry)
+        write_to_output(entry)
+        write_to_file(entry) if RailsNexus.configuration.log_file.present?
       end
 
       def write_to_output(entry)
-        level = entry[:level]
-        color = case level
-                when :debug then "\e[37m"  # white
-                when :info  then "\e[36m"  # cyan
-                when :warn  then "\e[33m"  # yellow
-                when :error then "\e[31m"  # red
-                when :fatal then "\e[35m"  # magenta
-                else "\e[0m"
-                end
-
-        reset = "\e[0m"
-        ts = entry[:timestamp].sub(/T/, " ").sub(/\+.*/, "")
-        msg = entry[:message]
-        cls = entry[:exception_class]
-
-        line = "#{color}[RailsNexus]#{reset} #{ts} #{level.to_s.upcase.ljust(5)}"
-        line += " #{cls}:" if cls.present?
-        line += " #{msg}"
-
-        if entry[:controller]
-          ctrl = entry[:controller]
-          line += " [#{ctrl[:class]}##{ctrl[:action]}]"
-        end
+        logger = defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
+        return unless logger
 
-        Rails.logger.send(level, line)
+        logger.public_send(entry[:level], "[RailsNexus] #{JSON.generate(entry)}")
       end
 
       def write_to_file(entry)
         file = RailsNexus.configuration.log_file
         return unless file.present?
 
-        File.open(file, "a") do |f|
-          f.puts(entry.to_json)
+        File.open(file, "a") { |io| io.puts(JSON.generate(entry)) }
+      rescue StandardError => error
+        report_internal_error(error, operation: "write log file")
+      end
+
+      def loggable?(level)
+        config = RailsNexus.configuration
+        return false unless config.logging_enabled
+
+        requested = LEVELS.index(level.to_sym)
+        configured = LEVELS.index(config.log_level.to_sym) || LEVELS.index(:info)
+        requested && requested >= configured
+      rescue StandardError
+        true
+      end
+
+      def merge_extra(extra, kwargs)
+        base = extra.is_a?(Hash) ? extra : { data: extra }
+        base.merge(kwargs)
+      end
+
+      def request_format(request)
+        format = safe_call(request, :format)
+        return unless format
+
+        safe_call(format, :ref)&.to_s || format.to_s
+      end
+
+      def safe_call(object, method_name, *args)
+        object.public_send(method_name, *args) if object.respond_to?(method_name)
+      rescue StandardError
+        nil
+      end
+
+      def safe_value(value, depth = 0, seen = {})
+        return "[MAX DEPTH]" if depth >= MAX_VALUE_DEPTH
+        return value if value.nil? || value == true || value == false || value.is_a?(Numeric)
+        return truncate(value) if value.is_a?(String) || value.is_a?(Symbol)
+        return value.iso8601 if value.respond_to?(:iso8601) && (value.is_a?(Time) || value.is_a?(Date))
+
+        object_id = value.object_id
+        return "[CIRCULAR]" if seen[object_id]
+        seen[object_id] = true
+
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, child), result|
+            result[truncate(key.to_s, 200)] = safe_value(child, depth + 1, seen)
+          end
+        when Array
+          value.first(100).map { |child| safe_value(child, depth + 1, seen) }
+        else
+          truncate(value.to_s)
         end
-      rescue StandardError => e
-        Rails.logger.error("[RailsNexus] Failed to write to log file: #{e.message}")
+      ensure
+        seen&.delete(object_id) if defined?(object_id) && object_id
+      end
+
+      def truncate(value, limit = MAX_STRING_LENGTH)
+        string = value.to_s
+        string.length > limit ? "#{string[0, limit]}...[truncated]" : string
+      end
+
+      def positive_integer(value, fallback)
+        parsed = Integer(value, exception: false)
+        parsed && parsed.positive? ? parsed : fallback
       end
 
-      def filter_params(params)
-        RailsNexus.filter_sensitive_data(params)
+      def report_internal_error(error, operation: "log exception")
+        logger = defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
+        logger&.error("[RailsNexus] Failed to #{operation} (#{error.class})")
+      rescue StandardError
+        nil
       end
     end
   end

data/lib/rails_nexus/version.rb

@@ -1,3 +1,3 @@
 module RailsNexus
-  VERSION = "2.1.4"
+  VERSION = "2.1.5"
 end

data/lib/rails_nexus.rb

@@ -3,6 +3,7 @@ require "active_support/parameter_filter"
 require "turbo-rails"
 require "stimulus-rails"
 require "pagy"
+require "ransack"
 require "ipaddr"
 require "socket"
 require "open3"
@@ -102,13 +103,25 @@ module RailsNexus
 
     # we log the exception and raise it again, for the normal handling.
     def log_exception_handler(exception)
-      log_exception(exception) if exception.is_a?(StandardError)
+      if exception.is_a?(StandardError)
+        begin
+          log_exception(exception)
+        rescue StandardError => logging_error
+          Rails.logger&.error("[RailsNexus] Failed to capture exception (#{logging_error.class})")
+        end
+      end
       raise exception
     end
 
     def rescue_action(exception)
       status = response_code_for_rescue(exception)
-      log_exception(exception) if exception.is_a?(StandardError) && status != :not_found
+      if exception.is_a?(StandardError) && status != :not_found
+        begin
+          log_exception(exception)
+        rescue StandardError => logging_error
+          Rails.logger&.error("[RailsNexus] Failed to capture exception (#{logging_error.class})")
+        end
+      end
       super
     end
 
@@ -122,11 +135,16 @@ module RailsNexus
                     RailsNexus.configuration.exception_data
                   end
 
-      data = case deliverer
-             when nil    then {}
-             when Symbol then send(deliverer)
-             when Proc   then deliverer.call(self)
-             end
+      data = begin
+        case deliverer
+        when nil    then {}
+        when Symbol then send(deliverer)
+        when Proc   then deliverer.call(self)
+        else deliverer.respond_to?(:call) ? deliverer.call(self) : {}
+        end
+      rescue StandardError => data_error
+        { exception_data_error: data_error.class.name }
+      end
 
       data = RailsNexus.filter_sensitive_data(data || {})
 

data/rails_nexus.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "rails", "~> 8.0", ">= 8.0.0"
   spec.add_dependency "stimulus-rails", "~> 1.3"
   spec.add_dependency "turbo-rails", "~> 2.0"
-  spec.add_dependency "pagy", "~> 6.5"
+  spec.add_dependency "pagy", ">= 43.0"
 
   spec.add_dependency "ransack", "~> 4.0"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_nexus
 version: !ruby/object:Gem::Version
-  version: 2.1.4
+  version: 2.1.5
 platform: ruby
 authors:
 - Tamiru Hailu
@@ -61,16 +61,16 @@ dependencies:
   name: pagy
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '6.5'
+        version: '43.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '6.5'
+        version: '43.0'
 - !ruby/object:Gem::Dependency
   name: ransack
   requirement: !ruby/object:Gem::Requirement
@@ -212,7 +212,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: The extensible control plane for Rails applications
 test_files: []