enhanced_errors 2.1.0 → 2.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. checksums.yaml +4 -4
  2. data/.yardoc/checksums +4 -4
  3. data/.yardoc/object_types +0 -0
  4. data/.yardoc/objects/root.dat +0 -0
  5. data/README.md +5 -1
  6. data/doc/Enhanced/Colors.html +25 -18
  7. data/doc/Enhanced.html +3 -7
  8. data/doc/EnhancedErrors.html +1784 -795
  9. data/doc/Exception.html +2 -2
  10. data/doc/Minitest.html +238 -0
  11. data/doc/_index.html +5 -22
  12. data/doc/class_list.html +1 -1
  13. data/doc/file.README.html +76 -80
  14. data/doc/index.html +76 -80
  15. data/doc/method_list.html +144 -16
  16. data/doc/top-level-namespace.html +3 -3
  17. data/enhanced_errors.gemspec +1 -1
  18. data/examples/demo_rspec.rb +16 -1
  19. data/lib/enhanced_errors.rb +136 -94
  20. metadata +4 -3
data/doc/index.html CHANGED
@@ -62,41 +62,13 @@
62
62
 
63
63
  <h2 id="label-Overview">Overview</h2>
64
64
 
65
- <p><strong>EnhancedErrors</strong> is a pure Ruby gem that enhances exceptions by capturing variables and their values from the scope where the error was raised.</p>
65
+ <p><strong>EnhancedErrors</strong> is a lightweight Ruby gem that enhances exceptions by capturing variables and their values from the scope where the exception was raised.</p>
66
66
 
67
67
  <p><strong>EnhancedErrors</strong> leverages Ruby’s built-in <a href="https://ruby-doc.org/core-3.1.0/TracePoint.html">TracePoint</a> feature to provide detailed context for exceptions, making debugging easier without significant performance overhead.</p>
68
68
 
69
- <p>When an exception is raised, EnhancedErrors captures the surrounding context. It works like this: <br></p>
69
+ <p>EnhancedErrors captures exception context using either a test-framework integration (RSpec/Minitest) or a global enhancement for runtime exceptions.</p>
70
70
 
71
- <h4 id="label-Enhanced+Exception+In+Code-3A">Enhanced Exception In Code:</h4>
72
-
73
- <pre class="code ruby"><code class="ruby">
74
- <span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>enhanced_errors</span><span class='tstring_end'>&#39;</span></span>
75
- <span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>awesome_print</span><span class='tstring_end'>&#39;</span></span> <span class='comment'># Optional, for better output
76
- </span>
77
- <span class='comment'># Enable capturing of variables at exception at raise-time. The .captured_variables method
78
- </span><span class='comment'># is added to all Exceptions and gets populated with in-scope variables and values on `raise`
79
- </span>
80
- <span class='const'><span class='object_link'><a href="EnhancedErrors.html" title="EnhancedErrors (class)">EnhancedErrors</a></span></span><span class='period'>.</span><span class='id identifier rubyid_enhance_exceptions!'><span class='object_link'><a href="EnhancedErrors.html#enhance_exceptions!-class_method" title="EnhancedErrors.enhance_exceptions! (method)">enhance_exceptions!</a></span></span>
81
-
82
- <span class='kw'>def</span> <span class='id identifier rubyid_foo'>foo</span>
83
- <span class='kw'>begin</span>
84
- <span class='id identifier rubyid_myvar'>myvar</span> <span class='op'>=</span> <span class='int'>0</span>
85
- <span class='ivar'>@myinstance</span> <span class='op'>=</span> <span class='int'>10</span>
86
- <span class='id identifier rubyid_foo'>foo</span> <span class='op'>=</span> <span class='ivar'>@myinstance</span> <span class='op'>/</span> <span class='id identifier rubyid_myvar'>myvar</span>
87
- <span class='kw'>rescue</span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_e'>e</span>
88
- <span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_captured_variables'>captured_variables</span>
89
- <span class='kw'>end</span>
90
- <span class='kw'>end</span>
91
-
92
- <span class='id identifier rubyid_foo'>foo</span>
93
- </code></pre>
94
-
95
- <h5 id="label-Output-3A">Output:</h5>
96
-
97
- <p>&lt;img src=“./doc/images/enhanced-error.png” style=“height: 215px; width: 429px;”&gt;&lt;/img&gt; <br></p>
98
-
99
- <h4 id="label-Enhanced+Exception+In+Specs-3A">Enhanced Exception In Specs:</h4>
71
+ <h3 id="label-Enhanced+Errors+In+RSpec-3A">Enhanced Errors In RSpec:</h3>
100
72
 
101
73
  <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_describe'>describe</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>sees through</span><span class='tstring_end'>&#39;</span></span> <span class='kw'>do</span>
102
74
 
@@ -119,50 +91,84 @@
119
91
 
120
92
  <p>&lt;img src=“./doc/images/enhanced-spec.png” style=“height: 369px; width: 712px;”&gt;&lt;/img&gt;</p>
121
93
 
122
- <h1 id="label-RSpec+Setup">RSpec Setup</h1>
94
+ <p>The RSpec test-time only approach constrained only to test-time.</p>
123
95
 
124
- <p>The simplest way to get started with EnhancedErrors is to use it for RSpec exception capturing. To get variable output into RSpec, the approach below enables capturing, but also gives nice output by formatting the failure message with the variable capture.</p>
96
+ <h3 id="label-RSpec+Setup">RSpec Setup</h3>
125
97
 
126
- <p>The advantage of this approach is that it is only active for your spec runs. This approach is ideal for CI and local testing because it doesn’t make any changes that should bleed through to production–it doesn’t enhance exceptions except those that pass by during the RSpec run.</p>
98
+ <p>Use EnhancedErrors with RSpec for test-specific exception capturing, ideal for CI and local testing without impacting production.</p>
127
99
 
128
100
  <pre class="code ruby"><code class="ruby">
129
101
  <span class='const'>RSpec</span><span class='period'>.</span><span class='id identifier rubyid_configure'>configure</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
130
-
131
- <span class='comment'># add these config changes to your RSpec config to get variable messages
132
- </span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_before'>before</span><span class='lparen'>(</span><span class='symbol'>:suite</span><span class='rparen'>)</span> <span class='kw'>do</span>
133
- <span class='const'>RSpec</span><span class='op'>::</span><span class='const'>Core</span><span class='op'>::</span><span class='const'>Example</span><span class='period'>.</span><span class='id identifier rubyid_prepend'>prepend</span><span class='lparen'>(</span><span class='const'><span class='object_link'><a href="Enhanced.html" title="Enhanced (module)">Enhanced</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Enhanced/Integrations.html" title="Enhanced::Integrations (module)">Integrations</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Enhanced/Integrations/RSpecErrorFailureMessage.html" title="Enhanced::Integrations::RSpecErrorFailureMessage (module)">RSpecErrorFailureMessage</a></span></span><span class='rparen'>)</span>
102
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_before'>before</span><span class='lparen'>(</span><span class='symbol'>:example</span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid__example'>_example</span><span class='op'>|</span>
103
+ <span class='const'><span class='object_link'><a href="EnhancedErrors.html" title="EnhancedErrors (class)">EnhancedErrors</a></span></span><span class='period'>.</span><span class='id identifier rubyid_start_rspec_binding_capture'><span class='object_link'><a href="EnhancedErrors.html#start_rspec_binding_capture-class_method" title="EnhancedErrors.start_rspec_binding_capture (method)">start_rspec_binding_capture</a></span></span>
134
104
  <span class='kw'>end</span>
135
-
105
+
136
106
  <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_before'>before</span><span class='lparen'>(</span><span class='symbol'>:example</span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid__example'>_example</span><span class='op'>|</span>
137
107
  <span class='const'><span class='object_link'><a href="EnhancedErrors.html" title="EnhancedErrors (class)">EnhancedErrors</a></span></span><span class='period'>.</span><span class='id identifier rubyid_start_rspec_binding_capture'><span class='object_link'><a href="EnhancedErrors.html#start_rspec_binding_capture-class_method" title="EnhancedErrors.start_rspec_binding_capture (method)">start_rspec_binding_capture</a></span></span>
138
108
  <span class='kw'>end</span>
139
109
 
140
110
  <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_after'>after</span><span class='lparen'>(</span><span class='symbol'>:example</span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_example'>example</span><span class='op'>|</span>
141
- <span class='id identifier rubyid_example'>example</span><span class='period'>.</span><span class='id identifier rubyid_metadata'>metadata</span><span class='lbracket'>[</span><span class='symbol'>:expect_binding</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="EnhancedErrors.html" title="EnhancedErrors (class)">EnhancedErrors</a></span></span><span class='period'>.</span><span class='id identifier rubyid_stop_rspec_binding_capture'><span class='object_link'><a href="EnhancedErrors.html#stop_rspec_binding_capture-class_method" title="EnhancedErrors.stop_rspec_binding_capture (method)">stop_rspec_binding_capture</a></span></span>
111
+ <span class='const'><span class='object_link'><a href="EnhancedErrors.html" title="EnhancedErrors (class)">EnhancedErrors</a></span></span><span class='period'>.</span><span class='id identifier rubyid_override_rspec_message'><span class='object_link'><a href="EnhancedErrors.html#override_rspec_message-class_method" title="EnhancedErrors.override_rspec_message (method)">override_rspec_message</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_example'>example</span><span class='comma'>,</span> <span class='const'><span class='object_link'><a href="EnhancedErrors.html" title="EnhancedErrors (class)">EnhancedErrors</a></span></span><span class='period'>.</span><span class='id identifier rubyid_stop_rspec_binding_capture'><span class='object_link'><a href="EnhancedErrors.html#stop_rspec_binding_capture-class_method" title="EnhancedErrors.stop_rspec_binding_capture (method)">stop_rspec_binding_capture</a></span></span><span class='rparen'>)</span>
142
112
  <span class='kw'>end</span>
143
-
144
113
  <span class='kw'>end</span>
145
114
  </code></pre>
146
115
 
147
- <h2 id="label-Minitest">Minitest</h2>
116
+ <p><br></p>
148
117
 
149
- <p>Untested as of yet, but enhance_exceptions!(override_messages: true) is likely to work.</p>
118
+ <h2 id="label-MiniTest+Setup">MiniTest Setup</h2>
150
119
 
151
- <p>If anyone wants to look into an integration implementation like RSpec, it would be welcomed. With a more targeted approach like the RSpec one, exceptions could be captured and modified only during test time, like the RSpec approach. This would be advantageous as it wouldn’t modify the exception message itself, but still makes the variable output available in test messages.</p>
120
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>enhanced_errors</span><span class='tstring_end'>&#39;</span></span>
121
+ <span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>enhanced/minitest_patch</span><span class='tstring_end'>&#39;</span></span>
152
122
 
153
- <h2 id="label-Enhancing+.message">Enhancing .message</h2>
123
+ <span class='comment'># Once the patch is loaded, it should just work!
124
+ </span></code></pre>
154
125
 
155
- <p>EnhancedErrors can also append the captured variable description into the Exception’s .message method output if the override_messages argument is true.</p>
126
+ <p><br></p>
156
127
 
157
- <p>This can be very convenient as it lets you capture and diagnose the context of totally unanticipated exceptions without modifying all your error handlers.</p>
128
+ <h3 id="label-Enhanced+Errors+In+Everyday+Ruby+Exceptions-3A">Enhanced Errors In Everyday Ruby Exceptions:</h3>
158
129
 
159
- <p>The downside to this approach is that if you have expectations in your tests/specs around exception messages, those may break. Also, if you are doing something with the error messages, like storing them in a database, they could be <em>much</em> longer and that may pose an issue.</p>
130
+ <pre class="code ruby"><code class="ruby">
131
+ <span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>enhanced_errors</span><span class='tstring_end'>&#39;</span></span>
132
+ <span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>awesome_print</span><span class='tstring_end'>&#39;</span></span> <span class='comment'># Optional, for better output
133
+ </span>
134
+ <span class='comment'># Enable capturing of variables at exception at raise-time. The .captured_variables method
135
+ </span><span class='comment'># is added to all Exceptions and gets populated with in-scope variables and values on `raise`
136
+ </span>
137
+ <span class='const'><span class='object_link'><a href="EnhancedErrors.html" title="EnhancedErrors (class)">EnhancedErrors</a></span></span><span class='period'>.</span><span class='id identifier rubyid_enhance_exceptions!'><span class='object_link'><a href="EnhancedErrors.html#enhance_exceptions!-class_method" title="EnhancedErrors.enhance_exceptions! (method)">enhance_exceptions!</a></span></span>
138
+
139
+ <span class='kw'>def</span> <span class='id identifier rubyid_foo'>foo</span>
140
+ <span class='kw'>begin</span>
141
+ <span class='id identifier rubyid_myvar'>myvar</span> <span class='op'>=</span> <span class='int'>0</span>
142
+ <span class='ivar'>@myinstance</span> <span class='op'>=</span> <span class='int'>10</span>
143
+ <span class='id identifier rubyid_foo'>foo</span> <span class='op'>=</span> <span class='ivar'>@myinstance</span> <span class='op'>/</span> <span class='id identifier rubyid_myvar'>myvar</span>
144
+ <span class='kw'>rescue</span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_e'>e</span>
145
+ <span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_captured_variables'>captured_variables</span>
146
+ <span class='kw'>end</span>
147
+ <span class='kw'>end</span>
148
+
149
+ <span class='id identifier rubyid_foo'>foo</span>
150
+ </code></pre>
151
+
152
+ <h3 id="label-Enhancing+.message">Enhancing .message</h3>
153
+
154
+ <p>EnhancedErrors can append the captured variable description onto every Exception’s .message method with</p>
155
+
156
+ <pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="EnhancedErrors.html" title="EnhancedErrors (class)">EnhancedErrors</a></span></span><span class='period'>.</span><span class='id identifier rubyid_enhance_exceptions'>enhance_exceptions</span><span class='lparen'>(</span><span class='label'>override_messages:</span> <span class='kw'>true</span><span class='rparen'>)</span>
157
+ </code></pre>
158
+
159
+ <p>This captures unanticipated exceptions without modifying all your error handlers. This approach can be used to get detailed logs when problems happen in something like a cron-job.</p>
160
+
161
+ <p>The tradeoff of this approach is that if you have expectations in your tests/specs around exception messages, those may break. Also, if you are doing something like storing the errors in a database, they could be <em>much</em> longer and that may pose an issue on field lengths. Or if you are writing your logs to Datadog, New Relic, Splunk, etc, log messages for errors will be longer, and you should consider what data/PII you are sharing.</p>
160
162
 
161
163
  <p>Ideally, use exception.captured_variables instead.</p>
162
164
 
163
165
  <pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="EnhancedErrors.html" title="EnhancedErrors (class)">EnhancedErrors</a></span></span><span class='period'>.</span><span class='id identifier rubyid_enhance_exceptions!'><span class='object_link'><a href="EnhancedErrors.html#enhance_exceptions!-class_method" title="EnhancedErrors.enhance_exceptions! (method)">enhance_exceptions!</a></span></span><span class='lparen'>(</span><span class='label'>override_messages:</span> <span class='kw'>true</span><span class='rparen'>)</span>
164
166
  </code></pre>
165
167
 
168
+ <h4 id="label-Output-3A">Output:</h4>
169
+
170
+ <p>&lt;img src=“./doc/images/enhanced-error.png” style=“height: 215px; width: 429px;”&gt;&lt;/img&gt; <br></p>
171
+
166
172
  <h2 id="label-Features">Features</h2>
167
173
  <ul><li>
168
174
  <p><strong>Pure Ruby</strong>: No external dependencies, C extensions, or C API calls.</p>
@@ -184,23 +190,17 @@
184
190
  <p><strong>Lightweight</strong>: Minimal performance impact, as tracing is only active during exception raising.</p>
185
191
  </li></ul>
186
192
 
187
- <p>EnhancedErrors has a few big use-cases:</p>
193
+ <p>EnhancedErrors use-cases:</p>
188
194
  <ul><li>
189
- <p><strong>Catch Data-driven bugs</strong>. For example, if, while processing a 10 gig file, you get an error, you can’t just re-run the code with a debugger. 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.</p>
190
- </li><li>
191
- <p><strong>Debug</strong> a complex application erroring deep in the stack when you can’t tell where the error originates.</p>
195
+ <p>Catch data-driven bugs without needing re-runs or extensive logging.</p>
192
196
  </li><li>
193
- <p><strong>Reduce MTTR</strong> Reduce mean time to resolution.</p>
197
+ <p>Debug deep-stack errors and reduce mean time to resolution (MTTR).</p>
194
198
  </li><li>
195
- <p><strong>Faster CI -&gt; Fix loop</strong>. When a bug happens in CI, usually there’s a step where you first reproduce it locally. EnhancedErrors can help you skip that step.</p>
199
+ <p>Handle CI failures faster by skipping reproduction steps.</p>
196
200
  </li><li>
197
- <p><strong>Faster TDD</strong>. 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.</p>
201
+ <p>Address elusive “Heisenbugs” by capturing error context preemptively.</p>
198
202
  </li><li>
199
- <p><strong>Heisenbugs</strong> - bugs that disappear when you try to debug them. EnhancedErrors can help you capture the data that causes the bug before it disappears.</p>
200
- </li><li>
201
- <p><strong>Unknown Unknowns</strong> - you can’t pre-emptively log variables from failure cases you never imagined.</p>
202
- </li><li>
203
- <p><strong>Cron jobs</strong> and <strong>daemons</strong> - when it fails for unknown reasons at 4am, check the log and fix–it probably has what you need. Note that</p>
203
+ <p>Debug cron jobs and daemons with rich, failure-specific logs.</p>
204
204
  </li></ul>
205
205
 
206
206
  <h2 id="label-Installation">Installation</h2>
@@ -232,11 +232,11 @@
232
232
  </span><span class='const'><span class='object_link'><a href="EnhancedErrors.html" title="EnhancedErrors (class)">EnhancedErrors</a></span></span><span class='period'>.</span><span class='id identifier rubyid_enhance_exceptions!'><span class='object_link'><a href="EnhancedErrors.html#enhance_exceptions!-class_method" title="EnhancedErrors.enhance_exceptions! (method)">enhance_exceptions!</a></span></span><span class='lparen'>(</span><span class='label'>override_messages:</span> <span class='kw'>true</span><span class='rparen'>)</span>
233
233
  </code></pre>
234
234
 
235
- <p>The approach above activates the TracePoint to start capturing exceptions and their surrounding context. It also overrides the .message to have the variables.</p>
235
+ <p>This captures all exceptions and their surrounding context. It also overrides the .message to display the variables.</p>
236
236
 
237
- <p>If modifying your exception handlers is an option, it is better <em>not</em> to use override_messages: true, but instead just use the exception.captured_variables, which is a string describing what was found, that is available regardless.</p>
237
+ <p>If modifying your exception handlers is an option, it is better <em>not</em> to use but instead just use the exception.captured_variables, which is a string describing what was found.</p>
238
238
 
239
- <p>Note that a minimalistic approach is taken to generating the string–if no qualifying variables were present, you won’t see any message!</p>
239
+ <p>Note: a minimalistic approach is taken to generating the capture string. If no qualifying variables were present, you won’t see any message additions!</p>
240
240
 
241
241
  <h3 id="label-Configuration+Options">Configuration Options</h3>
242
242
 
@@ -256,8 +256,6 @@
256
256
  <p><code>max_length</code>: Sets the maximum length of the captured_variables string (default: <code>2500</code>).</p>
257
257
  </li></ul>
258
258
 
259
- <p>Currently, the first <code>raise</code> exception binding is presented. This may be changed in the future to allow more binding data to be presented.</p>
260
-
261
259
  <h3 id="label-Environment-Based+Defaults">Environment-Based Defaults</h3>
262
260
 
263
261
  <p>EnhancedErrors adjusts its default settings based on the environment:</p>
@@ -378,7 +376,7 @@
378
376
 
379
377
  <p>While this is close to “Things that don’t descend from StandardError”, it’s not exactly that.</p>
380
378
 
381
- <p>In Info mode, variables starting with @_ are also ignored.</p>
379
+ <p>By default, many noisy instance variables are ignored in the default skip list. If you want to see every instance variable, you’ll need to clear out the skip list.</p>
382
380
 
383
381
  <h3 id="label-Capture+Levels">Capture Levels</h3>
384
382
 
@@ -386,7 +384,7 @@
386
384
  <ul><li>
387
385
  <p><strong>Info Level</strong>: Respects the skip list, excluding predefined sensitive or irrelevant variables. Global variables are ignored.</p>
388
386
  </li><li>
389
- <p><strong>Debug Level</strong>: Ignores the skip lists, capturing all variables including those typically excluded and global variables. Global variables are only captured in debug mode, and they exclude the default Ruby global variables.</p>
387
+ <p><strong>Debug Level</strong>: Ignores the skip lists, capturing all variables including those typically excluded and global variables. Global variables are only captured in debug mode, and they exclude the default Ruby global variables.</p>
390
388
  </li></ul>
391
389
 
392
390
  <p><strong>Default Behavior</strong>: By default, <code>info</code> level is used, which excludes variables in the skip list to protect sensitive information. In <code>debug</code> mode, the skip lists are ignored to provide more comprehensive data, which is useful during development but should be used cautiously to avoid exposing sensitive data. The info mode is recommended.</p>
@@ -434,13 +432,11 @@
434
432
 
435
433
  <p>The captured data is available in .captured_variables, to provide context for debugging.</p>
436
434
  <ul><li>
437
- <p>EnhancedErrors does not persist captured data--it only keep it in memory for the lifetime of the exception.</p>
435
+ <p>EnhancedErrors does not persist captured data–it only keep it in memory for the lifetime of the exception.</p>
438
436
  </li><li>
439
- <p>There are benchmarks around Tracepoint in the benchmark folder. Targeted tracepoints seem to be very cheap--as in, you can hit them ten thousand+ times a second without heavy overhead.</p>
437
+ <p>There are benchmarks around Tracepoint in the benchmark folder. Targeted tracepoints seem to be very cheap–as in, you can hit them ten thousand+ times a second without heavy overhead.</p>
440
438
  </li></ul>
441
439
 
442
- <p>*</p>
443
-
444
440
  <h2 id="label-Awesome+Print">Awesome Print</h2>
445
441
 
446
442
  <p>EnhancedErrors automatically uses the <a href="https://github.com/awesome-print/awesome_print">awesome_print</a> gem to format the captured data, <strong><em>if</em></strong> it is installed and available. If not, error enhancement will work, but the output may be less pretty (er, awesome). AwesomePrint is not required directly by EnhancedErrors, so you will need to add it to your Gemfile if you want to use it.</p>
@@ -454,26 +450,26 @@
454
450
 
455
451
  <p><a href="https://github.com/banister/binding_of_caller">binding_of_caller</a> or <a href="https://github.com/pry/pry">Pry</a> or <a href="https://github.com/BetterErrors/better_errors">better_errors</a>?</p>
456
452
 
457
- <p>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!</p>
453
+ <p>First off, these gems are a-m-a-z-i-n-g!!! I use them every day–kudos to their creators and maintainers!</p>
458
454
 
459
- <p>This is intended for different use-cases. In sum, the goal of this gem is an every-day driver for <strong>non-interactive</strong> variable inspection.</p>
455
+ <p>EnhancedErrors is intended as an every-day driver for <strong>non-interactive</strong> variable inspection.</p>
460
456
 
461
- <p>With EnhancedErrors is that I want extra details when I run into a problem I <strong>didn’t anticipate ahead of time</strong>. 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.</p>
457
+ <p>I want extra details when I run into a problem I <strong>didn’t anticipate ahead of time</strong>. To make that work, it has to be able to safely be ‘on’ ahead of time, and gather data in a way I naturally will retain without requiring extra preparation I obviously didn’t know to do.</p>
462
458
  <ul><li>
463
- <p>That won’t interrupt CI, but also, that lets me know what happened without reproduction</p>
459
+ <p>EnhancedErrors won’t interrupt CI, but it lets me know what happened <em>without</em> reproduction steps</p>
464
460
  </li><li>
465
- <p>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)</p>
461
+ <p>EnhancedErrors could, theoretically, also be fine in production (if data security, redaction, PII, access, and encryption concerns were all addressed. Big list, but another option is to selectively enable targeted capture.</p>
466
462
  </li><li>
467
463
  <p>Has decent performance characteristics</p>
468
464
  </li><li>
469
465
  <p><strong>Only</strong> becomes active in exception raise/rescue scenarios</p>
470
466
  </li></ul>
471
467
 
472
- <p>This gem could have been implemented using binding_of_caller, or the gem it depends on, <a href="https://rubygems.org/gems/debug_inspector/versions/1.1.0?locale=en">debug_inspector</a>. 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.</p>
468
+ <p>This gem could have been implemented using binding_of_caller, or the gem it depends on, <a href="https://rubygems.org/gems/debug_inspector/versions/1.1.0?locale=en">debug_inspector</a>. However, the recommendation is not to use those in production as they use C API extensions. This doesn’t. EnhancedErrors selectively uses Ruby’s TracePoint binding capture very narrowly with no other C API or dependencies, and only to target Exceptions. It operates in a narrow scope–becoming active only when exceptions are raised.</p>
473
469
 
474
470
  <h2 id="label-Performance+Considerations">Performance Considerations</h2>
475
471
  <ul><li>
476
- <p><strong>Minimal Overhead</strong>: Since TracePoint is only activated during exception raising and rescuing, the performance impact is negligible during normal operation. (Benchmark included)</p>
472
+ <p><strong>Small Overhead</strong>: Since TracePoint is only activated during exception raising and rescuing, the performance impact is negligible during normal operation. (Benchmark included)</p>
477
473
  </li><li>
478
474
  <p><strong>TBD</strong>: Memory considerations. This does capture data when an exception happens. EnhancedErrors hides under the bed when it sees <strong>NoMemoryError</strong>.</p>
479
475
  </li><li>
@@ -490,9 +486,9 @@
490
486
  </div></div>
491
487
 
492
488
  <div id="footer">
493
- Generated on Mon Dec 9 19:51:26 2024 by
489
+ Generated on Mon Dec 16 10:41:42 2024 by
494
490
  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
495
- 0.9.37 (ruby-3.1.3).
491
+ 0.9.37 (ruby-3.3.6).
496
492
  </div>
497
493
 
498
494
  </div>
data/doc/method_list.html CHANGED
@@ -88,6 +88,30 @@
88
88
 
89
89
 
90
90
  <li class="even ">
91
+ <div class="item">
92
+ <span class='object_link'><a href="EnhancedErrors.html#capture_events_count-class_method" title="EnhancedErrors.capture_events_count (method)">capture_events_count</a></span>
93
+ <small>EnhancedErrors</small>
94
+ </div>
95
+ </li>
96
+
97
+
98
+ <li class="odd ">
99
+ <div class="item">
100
+ <span class='object_link'><a href="EnhancedErrors.html#capture_events_count=-class_method" title="EnhancedErrors.capture_events_count= (method)">capture_events_count=</a></span>
101
+ <small>EnhancedErrors</small>
102
+ </div>
103
+ </li>
104
+
105
+
106
+ <li class="even ">
107
+ <div class="item">
108
+ <span class='object_link'><a href="EnhancedErrors.html#capture_limit_exceeded%3F-class_method" title="EnhancedErrors.capture_limit_exceeded? (method)">capture_limit_exceeded?</a></span>
109
+ <small>EnhancedErrors</small>
110
+ </div>
111
+ </li>
112
+
113
+
114
+ <li class="odd ">
91
115
  <div class="item">
92
116
  <span class='object_link'><a href="EnhancedErrors.html#capture_rescue-class_method" title="EnhancedErrors.capture_rescue (method)">capture_rescue</a></span>
93
117
  <small>EnhancedErrors</small>
@@ -95,6 +119,14 @@
95
119
  </li>
96
120
 
97
121
 
122
+ <li class="even ">
123
+ <div class="item">
124
+ <span class='object_link'><a href="EnhancedErrors.html#capture_rescue=-class_method" title="EnhancedErrors.capture_rescue= (method)">capture_rescue=</a></span>
125
+ <small>EnhancedErrors</small>
126
+ </div>
127
+ </li>
128
+
129
+
98
130
  <li class="odd ">
99
131
  <div class="item">
100
132
  <span class='object_link'><a href="Exception.html#captured_variables-instance_method" title="Exception#captured_variables (method)">#captured_variables</a></span>
@@ -104,6 +136,14 @@
104
136
 
105
137
 
106
138
  <li class="even ">
139
+ <div class="item">
140
+ <span class='object_link'><a href="EnhancedErrors.html#class_to_string-class_method" title="EnhancedErrors.class_to_string (method)">class_to_string</a></span>
141
+ <small>EnhancedErrors</small>
142
+ </div>
143
+ </li>
144
+
145
+
146
+ <li class="odd ">
107
147
  <div class="item">
108
148
  <span class='object_link'><a href="Enhanced/Colors.html#code-class_method" title="Enhanced::Colors.code (method)">code</a></span>
109
149
  <small>Enhanced::Colors</small>
@@ -111,7 +151,7 @@
111
151
  </li>
112
152
 
113
153
 
114
- <li class="odd ">
154
+ <li class="even ">
115
155
  <div class="item">
116
156
  <span class='object_link'><a href="Enhanced/Colors.html#color-class_method" title="Enhanced::Colors.color (method)">color</a></span>
117
157
  <small>Enhanced::Colors</small>
@@ -119,7 +159,7 @@
119
159
  </li>
120
160
 
121
161
 
122
- <li class="even ">
162
+ <li class="odd ">
123
163
  <div class="item">
124
164
  <span class='object_link'><a href="EnhancedErrors.html#config_block-class_method" title="EnhancedErrors.config_block (method)">config_block</a></span>
125
165
  <small>EnhancedErrors</small>
@@ -127,7 +167,7 @@
127
167
  </li>
128
168
 
129
169
 
130
- <li class="odd ">
170
+ <li class="even ">
131
171
  <div class="item">
132
172
  <span class='object_link'><a href="EnhancedErrors.html#convert_binding_to_binding_info-class_method" title="EnhancedErrors.convert_binding_to_binding_info (method)">convert_binding_to_binding_info</a></span>
133
173
  <small>EnhancedErrors</small>
@@ -135,15 +175,15 @@
135
175
  </li>
136
176
 
137
177
 
138
- <li class="even ">
178
+ <li class="odd ">
139
179
  <div class="item">
140
- <span class='object_link'><a href="EnhancedErrors.html#default_skip_list-class_method" title="EnhancedErrors.default_skip_list (method)">default_skip_list</a></span>
180
+ <span class='object_link'><a href="EnhancedErrors.html#disable_capturing!-class_method" title="EnhancedErrors.disable_capturing! (method)">disable_capturing!</a></span>
141
181
  <small>EnhancedErrors</small>
142
182
  </div>
143
183
  </li>
144
184
 
145
185
 
146
- <li class="odd ">
186
+ <li class="even ">
147
187
  <div class="item">
148
188
  <span class='object_link'><a href="EnhancedErrors.html#eligible_for_capture-class_method" title="EnhancedErrors.eligible_for_capture (method)">eligible_for_capture</a></span>
149
189
  <small>EnhancedErrors</small>
@@ -151,7 +191,7 @@
151
191
  </li>
152
192
 
153
193
 
154
- <li class="even ">
194
+ <li class="odd ">
155
195
  <div class="item">
156
196
  <span class='object_link'><a href="EnhancedErrors.html#enabled-class_method" title="EnhancedErrors.enabled (method)">enabled</a></span>
157
197
  <small>EnhancedErrors</small>
@@ -159,7 +199,7 @@
159
199
  </li>
160
200
 
161
201
 
162
- <li class="odd ">
202
+ <li class="even ">
163
203
  <div class="item">
164
204
  <span class='object_link'><a href="Enhanced/Colors.html#enabled=-class_method" title="Enhanced::Colors.enabled= (method)">enabled=</a></span>
165
205
  <small>Enhanced::Colors</small>
@@ -167,7 +207,7 @@
167
207
  </li>
168
208
 
169
209
 
170
- <li class="even ">
210
+ <li class="odd ">
171
211
  <div class="item">
172
212
  <span class='object_link'><a href="Enhanced/Colors.html#enabled%3F-class_method" title="Enhanced::Colors.enabled? (method)">enabled?</a></span>
173
213
  <small>Enhanced::Colors</small>
@@ -175,6 +215,14 @@
175
215
  </li>
176
216
 
177
217
 
218
+ <li class="even ">
219
+ <div class="item">
220
+ <span class='object_link'><a href="EnhancedErrors.html#enforce_capture_limit!-class_method" title="EnhancedErrors.enforce_capture_limit! (method)">enforce_capture_limit!</a></span>
221
+ <small>EnhancedErrors</small>
222
+ </div>
223
+ </li>
224
+
225
+
178
226
  <li class="odd ">
179
227
  <div class="item">
180
228
  <span class='object_link'><a href="EnhancedErrors.html#enhance_exceptions!-class_method" title="EnhancedErrors.enhance_exceptions! (method)">enhance_exceptions!</a></span>
@@ -185,8 +233,8 @@
185
233
 
186
234
  <li class="even ">
187
235
  <div class="item">
188
- <span class='object_link'><a href="Enhanced/Integrations/RSpecErrorFailureMessage.html#execution_result-instance_method" title="Enhanced::Integrations::RSpecErrorFailureMessage#execution_result (method)">#execution_result</a></span>
189
- <small>Enhanced::Integrations::RSpecErrorFailureMessage</small>
236
+ <span class='object_link'><a href="EnhancedErrors.html#exception_trace-class_method" title="EnhancedErrors.exception_trace (method)">exception_trace</a></span>
237
+ <small>EnhancedErrors</small>
190
238
  </div>
191
239
  </li>
192
240
 
@@ -208,6 +256,46 @@
208
256
 
209
257
 
210
258
  <li class="odd ">
259
+ <div class="item">
260
+ <span class='object_link'><a href="EnhancedErrors.html#increment_capture_events_count-class_method" title="EnhancedErrors.increment_capture_events_count (method)">increment_capture_events_count</a></span>
261
+ <small>EnhancedErrors</small>
262
+ </div>
263
+ </li>
264
+
265
+
266
+ <li class="even ">
267
+ <div class="item">
268
+ <span class='object_link'><a href="EnhancedErrors.html#is_a_minitest%3F-class_method" title="EnhancedErrors.is_a_minitest? (method)">is_a_minitest?</a></span>
269
+ <small>EnhancedErrors</small>
270
+ </div>
271
+ </li>
272
+
273
+
274
+ <li class="odd ">
275
+ <div class="item">
276
+ <span class='object_link'><a href="EnhancedErrors.html#is_rspec_example%3F-class_method" title="EnhancedErrors.is_rspec_example? (method)">is_rspec_example?</a></span>
277
+ <small>EnhancedErrors</small>
278
+ </div>
279
+ </li>
280
+
281
+
282
+ <li class="even ">
283
+ <div class="item">
284
+ <span class='object_link'><a href="EnhancedErrors.html#max_capture_events-class_method" title="EnhancedErrors.max_capture_events (method)">max_capture_events</a></span>
285
+ <small>EnhancedErrors</small>
286
+ </div>
287
+ </li>
288
+
289
+
290
+ <li class="odd ">
291
+ <div class="item">
292
+ <span class='object_link'><a href="EnhancedErrors.html#max_capture_events=-class_method" title="EnhancedErrors.max_capture_events= (method)">max_capture_events=</a></span>
293
+ <small>EnhancedErrors</small>
294
+ </div>
295
+ </li>
296
+
297
+
298
+ <li class="even ">
211
299
  <div class="item">
212
300
  <span class='object_link'><a href="EnhancedErrors.html#max_length-class_method" title="EnhancedErrors.max_length (method)">max_length</a></span>
213
301
  <small>EnhancedErrors</small>
@@ -215,6 +303,14 @@
215
303
  </li>
216
304
 
217
305
 
306
+ <li class="odd ">
307
+ <div class="item">
308
+ <span class='object_link'><a href="EnhancedErrors.html#mutex-class_method" title="EnhancedErrors.mutex (method)">mutex</a></span>
309
+ <small>EnhancedErrors</small>
310
+ </div>
311
+ </li>
312
+
313
+
218
314
  <li class="even ">
219
315
  <div class="item">
220
316
  <span class='object_link'><a href="EnhancedErrors.html#on_capture-class_method" title="EnhancedErrors.on_capture (method)">on_capture</a></span>
@@ -256,6 +352,14 @@
256
352
 
257
353
 
258
354
  <li class="odd ">
355
+ <div class="item">
356
+ <span class='object_link'><a href="Minitest.html#original_run_one_method-class_method" title="Minitest.original_run_one_method (method)">original_run_one_method</a></span>
357
+ <small>Minitest</small>
358
+ </div>
359
+ </li>
360
+
361
+
362
+ <li class="even ">
259
363
  <div class="item">
260
364
  <span class='object_link'><a href="EnhancedErrors.html#override_exception_message-class_method" title="EnhancedErrors.override_exception_message (method)">override_exception_message</a></span>
261
365
  <small>EnhancedErrors</small>
@@ -263,7 +367,7 @@
263
367
  </li>
264
368
 
265
369
 
266
- <li class="even ">
370
+ <li class="odd ">
267
371
  <div class="item">
268
372
  <span class='object_link'><a href="EnhancedErrors.html#override_messages-class_method" title="EnhancedErrors.override_messages (method)">override_messages</a></span>
269
373
  <small>EnhancedErrors</small>
@@ -271,6 +375,30 @@
271
375
  </li>
272
376
 
273
377
 
378
+ <li class="even ">
379
+ <div class="item">
380
+ <span class='object_link'><a href="EnhancedErrors.html#override_rspec_message-class_method" title="EnhancedErrors.override_rspec_message (method)">override_rspec_message</a></span>
381
+ <small>EnhancedErrors</small>
382
+ </div>
383
+ </li>
384
+
385
+
386
+ <li class="odd ">
387
+ <div class="item">
388
+ <span class='object_link'><a href="EnhancedErrors.html#reset_capture_events_count-class_method" title="EnhancedErrors.reset_capture_events_count (method)">reset_capture_events_count</a></span>
389
+ <small>EnhancedErrors</small>
390
+ </div>
391
+ </li>
392
+
393
+
394
+ <li class="even ">
395
+ <div class="item">
396
+ <span class='object_link'><a href="Minitest.html#run_one_method-class_method" title="Minitest.run_one_method (method)">run_one_method</a></span>
397
+ <small>Minitest</small>
398
+ </div>
399
+ </li>
400
+
401
+
274
402
  <li class="odd ">
275
403
  <div class="item">
276
404
  <span class='object_link'><a href="EnhancedErrors.html#running_in_ci%3F-class_method" title="EnhancedErrors.running_in_ci? (method)">running_in_ci?</a></span>
@@ -289,7 +417,7 @@
289
417
 
290
418
  <li class="odd ">
291
419
  <div class="item">
292
- <span class='object_link'><a href="EnhancedErrors.html#safely_prepend_rspec_custom_failure_message-class_method" title="EnhancedErrors.safely_prepend_rspec_custom_failure_message (method)">safely_prepend_rspec_custom_failure_message</a></span>
420
+ <span class='object_link'><a href="EnhancedErrors.html#skip_list-class_method" title="EnhancedErrors.skip_list (method)">skip_list</a></span>
293
421
  <small>EnhancedErrors</small>
294
422
  </div>
295
423
  </li>
@@ -297,7 +425,7 @@
297
425
 
298
426
  <li class="even ">
299
427
  <div class="item">
300
- <span class='object_link'><a href="EnhancedErrors.html#skip_list-class_method" title="EnhancedErrors.skip_list (method)">skip_list</a></span>
428
+ <span class='object_link'><a href="EnhancedErrors.html#start_minitest_binding_capture-class_method" title="EnhancedErrors.start_minitest_binding_capture (method)">start_minitest_binding_capture</a></span>
301
429
  <small>EnhancedErrors</small>
302
430
  </div>
303
431
  </li>
@@ -313,7 +441,7 @@
313
441
 
314
442
  <li class="even ">
315
443
  <div class="item">
316
- <span class='object_link'><a href="EnhancedErrors.html#stop_rspec_binding_capture-class_method" title="EnhancedErrors.stop_rspec_binding_capture (method)">stop_rspec_binding_capture</a></span>
444
+ <span class='object_link'><a href="EnhancedErrors.html#stop_minitest_binding_capture-class_method" title="EnhancedErrors.stop_minitest_binding_capture (method)">stop_minitest_binding_capture</a></span>
317
445
  <small>EnhancedErrors</small>
318
446
  </div>
319
447
  </li>
@@ -321,7 +449,7 @@
321
449
 
322
450
  <li class="odd ">
323
451
  <div class="item">
324
- <span class='object_link'><a href="EnhancedErrors.html#trace-class_method" title="EnhancedErrors.trace (method)">trace</a></span>
452
+ <span class='object_link'><a href="EnhancedErrors.html#stop_rspec_binding_capture-class_method" title="EnhancedErrors.stop_rspec_binding_capture (method)">stop_rspec_binding_capture</a></span>
325
453
  <small>EnhancedErrors</small>
326
454
  </div>
327
455
  </li>