enhanced_errors 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fe5b1005d924a2d75afc6603d81b9a858b44158a94f97e71381ee12f0d9f691
-  data.tar.gz: 8a574198151511f3b7774d95fb06217ba6739a258d8092724bd1fc2238071634
+  metadata.gz: 58869aa7d7b2b2e3fb4f983ec425c909fd231396920da0283dc53a84afd943fe
+  data.tar.gz: 3ec8adc214e86d163930a0500ccb869221be072469dcc99cb0ab5f6150b851e5
 SHA512:
-  metadata.gz: 5b6674b41ae75c55c5433ebd58cb3a214198183345993931f2a88e6df0eb58b2c0908ea1103c6c296a7899fb554570c65ec72d19c58377ef611718423810b83e
-  data.tar.gz: 5885b07b737a9758ec18bca9f55a7d0b305cb0b5300decd0250999dc08a2d470dcb014085db913af6fafab3b8b64e1e30dd8d6f54a5681dda491fee27fd3fb88
+  metadata.gz: cd0dcfd36be230736ce342db302c01002b6ce06bc9e7eb967d5870121002707fc6d30cb25efc0f7cec101350d8b670db7b4168ca5759a8fe1940537de2b7e620
+  data.tar.gz: e5d1bc47e7cc8efe21627225e520a332bc48efba549eb408d1420332f510f88f8f491ff4caf3979c07c620c9a5c5423db670ba0eec32ef769f764b0a9afdab2a

data/.yardoc/checksums

@@ -1,4 +1,4 @@
 lib/colors.rb a4314ef9531d4713907c3fea22955c943fdb8cf3
 lib/binding.rb fdd7d5a2dd2edde22e3b10773510738dcdce4aeb
-lib/enhanced_errors.rb 314e2109290db51b63e2e417f67b834425131726
-lib/error_enhancements.rb 5ff3b60d76a44979b9745d1c47e77f7569fd03ac
+lib/enhanced_errors.rb d12ce0629f2565e5179ae5076be8a495e19ecda2
+lib/error_enhancements.rb a97d0f139d35f6e1b5bf49386271b1f4cf71761c

data/README.md

@@ -64,14 +64,14 @@ end
 ## Features
 
 - **Pure Ruby**: No external dependencies, C extensions, or C API calls.
-- **Lightweight**: Minimal performance impact, as tracing is only active during exception raising.
 - **Customizable Output**: Supports multiple output formats (`:json`, `:plaintext`, `:terminal`).
-- **Flexible Hooks**: Redact or modifying captured data via the `on_capture` hook.
+- **Flexible Hooks**: Redact or modifying captured data via the `on_capture` hook. Update the final string with on_format.
 - **Environment-Based Defaults**: For Rails apps, automatically adjusts settings based on the environment (`development`, `test`, `production`, `ci`).
 - **Pre-Populated Skip List**: Comes with predefined skip lists to exclude irrelevant variables from being captured.
 - **Capture Levels**: Supports `info` and `debug` levels, where `debug` level ignores the skip lists for more comprehensive data capture.
 - **Capture Types**: Captures variables from the first `raise` and the last `rescue` for an exception by default.
 - **No dependencies**:  EnhancedErrors does not ___require___ any dependencies--it uses [awesome_print](https://github.com/awesome-print/awesome_print) for nicer output if it is installed and available.
+- **Lightweight**: Minimal performance impact, as tracing is only active during exception raising.
 
 EnhancedErrors has a few big use-cases:
 
@@ -79,20 +79,20 @@ EnhancedErrors has a few big use-cases:
 You also can't just print out all the data, because it's too big. You want to know what the data was the cause of the error.
 Ideally, without long instrument-re-run-fix loops. If your logging didn't capture the data, normally, you'd be stuck. 
 
-* **Debug** a complex application erroring deep in the stack when you can't tell where the error originates
+* **Debug** a complex application erroring deep in the stack when you can't tell where the error originates.
 
-* **Faster TDD** - Often, you won't have to re-run to see an error--you can go straight to the fix.
+* **Reduce MTTR** Reduce mean time to resolution.
 
 * **Faster CI -> Fix loop**. When a bug happens in CI, usually there's a step where you first reproduce it locally.
   EnhancedErrors can help you skip that step.
 
-* **Faster debugging**. In general, you can skip the add-instrumentation step and jump to the fix.
+* **Faster TDD**. In general, you can skip the add-instrumentation step and jump to the fix. Usually, you won't have to re-run to see an error.
 
 * **Heisenbugs** - bugs that disappear when you try to debug them. EnhancedErrors can help you capture the data that causes the bug before it disappears.
 
 * **Unknown Unknowns** - you can't pre-emptively log variables from failure cases you never imagined.
 
-* **Cron jobs** and **daemons** - when it fails for unknown reasons at 4am, check the log and fix--it probably has what you need.
+* **Cron jobs** and **daemons** - when it fails for unknown reasons at 4am, check the log and fix--it probably has what you need. Note that 
 
 ## Installation
 
@@ -202,7 +202,7 @@ it yields out a hash with the structure below. Modify it as needed and return th
     globals: globals
   },
   exception: exception.class.name,
-  capture_type: capture_type # 'raise' or 'rescue'
+  capture_event: capture_event # 'raise' or 'rescue'
 }
 ```
 
@@ -266,6 +266,26 @@ end
 The skip list is pre-populated with common variables to exclude and can be extended based on your application's requirements. 
 
 
+#### Capture Rules
+
+These exceptions are always ignored:
+
+```ruby
+SystemExit,
+NoMemoryError,
+SignalException,
+Interrupt,
+ScriptError,
+LoadError,
+NotImplementedError,
+SyntaxError,
+SystemStackError
+```
+
+While this is close to "Things that don't descend from StandardError", it's not exactly that.
+
+In Info mode, variables starting with @_ are also ignored.
+
 
 ### Capture Levels
 
@@ -316,7 +336,7 @@ When an exception is raised or rescued, it captures:
 - **Let Variables**: RSpec let variables, if applicable. Only memoized (evaluated) let variables are captured.
 - **Global Variables**: Global variables, in debug mode.
 
-The captured data includes a `capture_type` field indicating whether the data was captured during a `raise` or `rescue` event. By default, EnhancedErrors returns the first `raise` and the last `rescue` event for each exception, providing a clear trace of the exception lifecycle.
+The captured data includes a `capture_event` field indicating whether the data was captured during a `raise` or `rescue` event. By default, EnhancedErrors returns the first `raise` and the last `rescue` event for each exception, providing a clear trace of the exception lifecycle.
 
 The captured data is then appended to the exception's message, providing rich context for debugging.
 
@@ -333,11 +353,38 @@ if you want to use it.
 gem 'awesome_print'
 ```
 
+## Alternatives
+
+Why not use:
+
+[binding_of_caller](https://github.com/banister/binding_of_caller) or [Pry](https://github.com/pry/pry) or [better_errors](https://github.com/BetterErrors/better_errors)?
+
+First off, these gems are, I cannot stress this enough, a-m-a-z-i-n-g!!! I use them every day--kudos to their creators and maintainers!
+
+This is intended for different use-cases. In sum, the goal of this gem is an every-day driver for __non-interactive__ variable inspection. 
+
+With EnhancedErrors is that I want extra details when I run into a problem I __didn't anticipate ahead of time__.
+To make that work, it has to be able to safely be 'on' all the time, and it has to gather the data in
+a way I naturally will see it without requiring extra preparation I obviously didn't know to do.
+
+- That won't interrupt CI, but also, that lets me know what happened without reproduction
+- That could, theoretically, also be fine in production (if data security, redaction, access, and encryption concerns were all addressed--Ok, big
+list, but another option is to selectively enable targeted capture)
+- Has decent performance characteristics
+- **Only** becomes active in exception raise/rescue scenarios
+
+This gem could have been implemented using binding_of_caller, or the gem it depends on, [debug_inspector](https://rubygems.org/gems/debug_inspector/versions/1.1.0?locale=en). 
+However, the recommendation is not to use those in production as they use C API extensions. This doesn't. This selectively uses 
+Ruby's TracePoint binding capture very narrowly with no other C API or dependencies, and only to target Exceptions--not to allow universal calls to the prior binding. It doesn't work as a debugger, but that also means it can, with care, operate safely in a narrow scope--becoming active only when exceptions are raised.
+
 
 ## Performance Considerations
 
-- **Minimal Overhead**: Since TracePoint is only activated during exception raising and rescuing, the performance impact is negligible during normal operation.
-- **Production Safe**: The gem is designed to be safe for production use, giving you valuable insights without compromising performance. Although this is the case, I'd still suggest letting it get well-vetted before making the leap.
+- **Minimal Overhead**: Since TracePoint is only activated during exception raising and rescuing, the performance impact is negligible during normal operation. (Benchmark included)
+
+- **TBD**: Memory considerations. This does capture data when an exception happens. EnhancedErrors hides under the bed when it sees **NoMemoryError**.
+
+- **Goal: Production Safety**: The gem is designed to, once vetted, be safe for production use, giving you valuable insights without compromising performance. I suggest letting it get well-vetted before making the leap and testing it for both performance and memory under load internally, as well.
 
 ## Contributing
 

data/benchmark/memory_bench.rb

@@ -0,0 +1,78 @@
+# benchmark_tracepoint.rb
+
+def memory_usage
+  pid = Process.pid
+  `ps -o rss= -p #{pid}`.to_i  # Returns memory usage in KB
+end
+
+# Generate a 100 MB string outside the iterations
+large_string = 'a' * 10_000_000  # 10 million characters
+
+def test_with_tracepoint(iterations, large_string)
+  puts "\nTest with TracePoint capturing bindings:"
+  captured_bindings = []
+
+  trace = TracePoint.new(:raise) do |tp|
+    captured_bindings << tp.binding
+  end
+
+  trace.enable
+
+  puts "Memory usage before exceptions: #{memory_usage} KB"
+
+  iterations.times do
+    begin
+      # Use the large string within the local scope
+      local_large_string = large_string
+      raise 'Test exception'
+    rescue => e
+      raise e rescue nil  # Suppress the exception to continue the loop
+    end
+  end
+
+  puts "Memory usage after exceptions: #{memory_usage} KB"
+
+  trace.disable
+end
+
+def test_without_tracepoint(iterations, large_string)
+  puts "\nTest without TracePoint capturing bindings:"
+
+  puts "Memory usage before exceptions: #{memory_usage} KB"
+
+  iterations.times do
+    begin
+      # Use the large string within the local scope
+      local_large_string = large_string
+      raise 'Test exception'
+    rescue => e
+      raise e rescue nil
+    end
+  end
+
+  puts "Memory usage after exceptions: #{memory_usage} KB"
+end
+
+def test_exception_with_large_variable(iterations, large_string)
+  puts "\nTest with exceptions storing large variable:"
+
+  puts "Memory usage before exceptions: #{memory_usage} KB"
+
+  iterations.times do
+    begin
+      raise 'Test exception'
+    rescue => e
+      # Store a reference to the large string in the exception
+      e.instance_variable_set(:@large_string, large_string)
+      raise e rescue nil
+    end
+  end
+
+  puts "Memory usage after exceptions: #{memory_usage} KB"
+end
+
+iterations = 10  # Adjust iterations as needed
+
+test_with_tracepoint(iterations, large_string)
+test_without_tracepoint(iterations, large_string)
+test_exception_with_large_variable(iterations, large_string)

data/doc/Binding.html

@@ -127,7 +127,7 @@
 </div>
 
       <div id="footer">
-  Generated on Tue Oct 22 23:16:25 2024 by
+  Generated on Sun Nov 10 12:01:14 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.1.3).
 </div>

data/doc/Colors.html

@@ -374,7 +374,7 @@
 </div>
 
       <div id="footer">
-  Generated on Tue Oct 22 23:16:25 2024 by
+  Generated on Sun Nov 10 12:01:14 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.1.3).
 </div>

data/doc/Debugging.html

@@ -171,7 +171,7 @@
 </div>
 
       <div id="footer">
-  Generated on Tue Oct 22 23:16:25 2024 by
+  Generated on Sun Nov 10 12:01:14 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.1.3).
 </div>