enhanced_errors 0.1.0 → 0.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.
- checksums.yaml +4 -4
- data/.yardoc/checksums +4 -0
- data/.yardoc/complete +0 -0
- data/.yardoc/object_types +0 -0
- data/.yardoc/objects/root.dat +0 -0
- data/.yardoc/proxy_types +0 -0
- data/README.md +52 -70
- data/doc/Binding.html +137 -0
- data/doc/Colors.html +384 -0
- data/doc/Debugging.html +181 -0
- data/doc/EnhancedErrors.html +2742 -0
- data/doc/ErrorEnhancements.html +252 -0
- data/doc/_index.html +151 -0
- data/doc/class_list.html +54 -0
- data/doc/css/common.css +1 -0
- data/doc/css/full_list.css +58 -0
- data/doc/css/style.css +503 -0
- data/doc/file.README.html +432 -0
- data/doc/file_list.html +59 -0
- data/doc/frames.html +22 -0
- data/doc/images/enhanced-error.png +0 -0
- data/doc/images/enhanced-spec.png +0 -0
- data/doc/index.html +432 -0
- data/doc/js/app.js +344 -0
- data/doc/js/full_list.js +242 -0
- data/doc/js/jquery.js +4 -0
- data/doc/method_list.html +286 -0
- data/doc/top-level-namespace.html +112 -0
- data/enhanced_errors.gemspec +6 -3
- data/examples/example_spec.rb +2 -2
- data/lib/enhanced_errors.rb +43 -30
- metadata +58 -6
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: b74f8777e19b73bcfd4024c4d3191abf98acfa397adaf99252b80cbbabf583af
|
4
|
+
data.tar.gz: 47df87c1b8820fc1f0c0bdea2abe48ad4ed817472b22d8728328b52397e21b4c
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: c1db064f46691c84d3321b735c4bbf3258aa9d6f71a1611096cbe21d9a52bd67a352cc750a2fe16ad5f9fb46911fd4111e5166f4bb08844e28b80b64ba4af7ee
|
7
|
+
data.tar.gz: cb1664d2de142e882f6d408817ac9c7a8b0bb14a54dedf30fa35fde05ba215bed7b42c17eef3109ffa4e7736f35f9eb937eac1c37a6d9a7278a6a989baff070f
|
data/.yardoc/checksums
ADDED
data/.yardoc/complete
ADDED
File without changes
|
Binary file
|
Binary file
|
data/.yardoc/proxy_types
ADDED
Binary file
|
data/README.md
CHANGED
@@ -7,10 +7,13 @@
|
|
7
7
|
**EnhancedErrors** leverages Ruby's built-in [TracePoint](https://ruby-doc.org/core-3.1.0/TracePoint.html) feature to provide detailed context for exceptions, making debugging easier without significant performance overhead.
|
8
8
|
|
9
9
|
When an exception is raised, EnhancedErrors captures the surrounding context. It works like this:
|
10
|
+
<br>
|
11
|
+
|
12
|
+
#### Enhanced Exception In Code:
|
10
13
|
|
11
14
|
```ruby
|
12
15
|
|
13
|
-
require '
|
16
|
+
require 'enhanced_errors'
|
14
17
|
require 'awesome_print' # Optional, for better output
|
15
18
|
|
16
19
|
EnhancedErrors.enhance!
|
@@ -29,37 +32,38 @@ foo
|
|
29
32
|
|
30
33
|
```
|
31
34
|
|
32
|
-
|
33
|
-
|
34
|
-
<img src="./doc/images/enhanced-error.png" style="height: 171px; width: 440px;"></img>
|
35
|
+
##### Output:
|
35
36
|
|
37
|
+
<img src="./doc/images/enhanced-error.png" style="height: 215px; width: 429px;"></img>
|
38
|
+
<br>
|
39
|
+
#### Enhanced Exception In Specs:
|
36
40
|
|
37
41
|
```ruby
|
38
|
-
|
39
|
-
let(:the_matrix) { 'code rains, dramatically' }
|
42
|
+
describe 'sees through' do
|
40
43
|
|
41
|
-
|
42
|
-
@spoon = 'there is no spoon'
|
43
|
-
end
|
44
|
+
let(:the_matrix) { 'code rains, dramatically' }
|
44
45
|
|
45
|
-
|
46
|
-
|
47
|
-
|
48
|
-
|
49
|
-
|
50
|
-
|
46
|
+
before(:each) do
|
47
|
+
@spoon = 'there is no spoon'
|
48
|
+
end
|
49
|
+
|
50
|
+
it 'the matrix' do
|
51
|
+
#activate memoized item
|
52
|
+
the_matrix
|
53
|
+
stop = 'bullets'
|
54
|
+
raise 'No!'
|
51
55
|
end
|
56
|
+
end
|
52
57
|
```
|
53
58
|
|
54
|
-
####
|
59
|
+
#### Output:
|
55
60
|
|
56
|
-
<img src="./doc/images/enhanced-spec.png" style="height:
|
61
|
+
<img src="./doc/images/enhanced-spec.png" style="height: 369px; width: 712px;"></img>
|
57
62
|
|
58
63
|
|
59
64
|
## Features
|
60
65
|
|
61
|
-
- **Pure Ruby**: No external dependencies or C
|
62
|
-
- **Standalone**: Does not rely on any external libraries.
|
66
|
+
- **Pure Ruby**: No external dependencies, C extensions, or C API calls.
|
63
67
|
- **Lightweight**: Minimal performance impact, as tracing is only active during exception raising.
|
64
68
|
- **Customizable Output**: Supports multiple output formats (`:json`, `:plaintext`, `:terminal`).
|
65
69
|
- **Flexible Hooks**: Redact or modifying captured data via the `on_capture` hook.
|
@@ -71,26 +75,24 @@ foo
|
|
71
75
|
|
72
76
|
EnhancedErrors has a few big use-cases:
|
73
77
|
|
74
|
-
* Data-driven bugs
|
78
|
+
* **Catch Data-driven bugs**. For example, if, while processing a 10 gig file, you get an error, you can't just re-run the code with a debugger.
|
75
79
|
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.
|
76
|
-
Ideally, without long instrument-re-run-fix loops.
|
77
|
-
|
78
|
-
If your logging didn't capture the data, normally, you'd be stuck.
|
80
|
+
Ideally, without long instrument-re-run-fix loops. If your logging didn't capture the data, normally, you'd be stuck.
|
79
81
|
|
80
|
-
* Debug a complex application erroring deep in the stack when you can't tell where the error originates
|
82
|
+
* **Debug** a complex application erroring deep in the stack when you can't tell where the error originates
|
81
83
|
|
82
|
-
* Faster TDD - Often, you won't have to re-run to see an error--you can go straight to the fix.
|
84
|
+
* **Faster TDD** - Often, you won't have to re-run to see an error--you can go straight to the fix.
|
83
85
|
|
84
|
-
* Faster CI ->
|
86
|
+
* **Faster CI -> Fix loop**. When a bug happens in CI, usually there's a step where you first reproduce it locally.
|
85
87
|
EnhancedErrors can help you skip that step.
|
86
88
|
|
87
|
-
* Faster debugging
|
89
|
+
* **Faster debugging**. In general, you can skip the add-instrumentation step and jump to the fix.
|
88
90
|
|
89
|
-
* Heisenbugs - bugs that disappear when you try to debug them. EnhancedErrors can help you capture the data that causes the bug before it disappears.
|
91
|
+
* **Heisenbugs** - bugs that disappear when you try to debug them. EnhancedErrors can help you capture the data that causes the bug before it disappears.
|
90
92
|
|
91
|
-
*
|
93
|
+
* **Unknown Unknowns** - you can't pre-emptively log variables from failure cases you never imagined.
|
92
94
|
|
93
|
-
* Cron jobs and daemons - when it fails for unknown reasons at 4am, check the log and fix--it probably has what you need.
|
95
|
+
* **Cron jobs** and **daemons** - when it fails for unknown reasons at 4am, check the log and fix--it probably has what you need.
|
94
96
|
|
95
97
|
## Installation
|
96
98
|
|
@@ -117,11 +119,19 @@ $ gem install enhanced_errors
|
|
117
119
|
To enable EnhancedErrors, call the `enhance!` method:
|
118
120
|
|
119
121
|
```ruby
|
122
|
+
# For a rails app, put this in an initializer, or spec_helper.rb
|
123
|
+
# ex: config/initializers/enhanced_errors.rb
|
124
|
+
|
125
|
+
require 'awesome_print' # Optional, for better output
|
120
126
|
EnhancedErrors.enhance!
|
127
|
+
|
128
|
+
# -> now your error messages will have variables and their values appended to them.
|
129
|
+
|
121
130
|
```
|
122
131
|
|
123
132
|
This activates the TracePoint to start capturing exceptions and their surrounding context.
|
124
133
|
|
134
|
+
|
125
135
|
### Configuration Options
|
126
136
|
|
127
137
|
You can pass configuration options to `enhance!`:
|
@@ -133,9 +143,14 @@ EnhancedErrors.enhance!(enabled: true, max_length: 2000) do
|
|
133
143
|
end
|
134
144
|
|
135
145
|
```
|
146
|
+
- `add_to_skip_list`: Variables to ignore, as symbols. ex: :@instance_variable_to_skip, :local_to_skip`
|
136
147
|
- `enabled`: Enables or disables the enhancement (default: `true`).
|
137
148
|
- `max_length`: Sets the maximum length of the enhanced message (default: `2500`).
|
138
149
|
|
150
|
+
Currently, the first `raise` exception binding is presented.
|
151
|
+
This may be changed in the future to allow more binding data to be presented.
|
152
|
+
|
153
|
+
|
139
154
|
### Environment-Based Defaults
|
140
155
|
|
141
156
|
EnhancedErrors adjusts its default settings based on the environment:
|
@@ -252,14 +267,13 @@ The skip list is pre-populated with common variables to exclude and can be exten
|
|
252
267
|
|
253
268
|
|
254
269
|
|
255
|
-
|
256
270
|
### Capture Levels
|
257
271
|
|
258
272
|
EnhancedErrors supports different capture levels to control the verbosity of the captured data:
|
259
273
|
|
260
274
|
- **Info Level**: Respects the skip list, excluding predefined sensitive or irrelevant variables. Global variables are ignored.
|
261
275
|
- **Debug Level**: Ignores the skip lists, capturing all variables including those typically excluded and global variables.
|
262
|
-
Global variables,
|
276
|
+
Global variables are only captured in debug mode, and they exclude the default Ruby global variables.
|
263
277
|
|
264
278
|
**Default Behavior**: By default, `info` level is used, which excludes variables in the skip list to protect sensitive information. In `debug` 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.
|
265
279
|
The info mode is recommended.
|
@@ -274,7 +288,7 @@ EnhancedErrors differentiates between two types of capture events:
|
|
274
288
|
- **`rescue`**: Captures the context when an exception is last rescued.
|
275
289
|
|
276
290
|
**Default Behavior**: By default, EnhancedErrors returns the first `raise` and the last `rescue` event for each exception.
|
277
|
-
|
291
|
+
The `rescue` exception is only available in Ruby 3.2+ as it was added to TracePoint events in Ruby 3.2.
|
278
292
|
|
279
293
|
|
280
294
|
### Example: Redacting Sensitive Information
|
@@ -291,39 +305,6 @@ EnhancedErrors.on_capture do |binding_info|
|
|
291
305
|
end
|
292
306
|
```
|
293
307
|
|
294
|
-
### Example: Encrypting Data in Custom Format
|
295
|
-
|
296
|
-
|
297
|
-
```ruby
|
298
|
-
# config/initializers/encryption.rb
|
299
|
-
|
300
|
-
require 'active_support'
|
301
|
-
|
302
|
-
# Retrieve the encryption key from Rails credentials or environment variables
|
303
|
-
ENCRYPTION_KEY = Rails.application.credentials.encryption_key || ENV['ENCRYPTION_KEY']
|
304
|
-
|
305
|
-
# It's recommended to use a 256-bit key (32 bytes)
|
306
|
-
# If your key is in hex or another format, ensure it's properly decoded
|
307
|
-
key = ActiveSupport::KeyGenerator.new(ENCRYPTION_KEY).generate_key('enhanced_errors', 32)
|
308
|
-
ENCRYPTOR = ActiveSupport::MessageEncryptor.new(key)
|
309
|
-
```
|
310
|
-
|
311
|
-
```ruby
|
312
|
-
|
313
|
-
require_relative 'path_to/enhanced_errors' # Adjust the path accordingly
|
314
|
-
require 'active_support/message_encryptor'
|
315
|
-
|
316
|
-
# Ensure the encryptor is initialized
|
317
|
-
encryptor = ENCRYPTOR
|
318
|
-
|
319
|
-
EnhancedErrors.on_format = lambda do |formatted_string|
|
320
|
-
encrypted_data = encryptor.encrypt_and_sign(formatted_string)
|
321
|
-
encrypted_base64 = Base64.strict_encode64(encrypted_data)
|
322
|
-
"ENCRYPTED[#{encrypted_data}]"
|
323
|
-
end
|
324
|
-
```
|
325
|
-
|
326
|
-
|
327
308
|
## How It Works
|
328
309
|
|
329
310
|
EnhancedErrors uses Ruby's `TracePoint` to listen for `:raise` and `:rescue` events.
|
@@ -342,10 +323,11 @@ The captured data is then appended to the exception's message, providing rich co
|
|
342
323
|
|
343
324
|
## Awesome Print
|
344
325
|
|
345
|
-
EnhancedErrors uses the [awesome_print](https://github.com/awesome-print/awesome_print)
|
346
|
-
gem to format the captured data,
|
347
|
-
If not,
|
348
|
-
required directly by EnhancedErrors, so you will need to add it to your Gemfile
|
326
|
+
EnhancedErrors automatically uses the [awesome_print](https://github.com/awesome-print/awesome_print)
|
327
|
+
gem to format the captured data, ___if___ it is installed and available.
|
328
|
+
If not, error enhancement will work, but the output may be less pretty (er, awesome).
|
329
|
+
AwesomePrint is not required directly by EnhancedErrors, so you will need to add it to your Gemfile
|
330
|
+
if you want to use it.
|
349
331
|
|
350
332
|
```ruby
|
351
333
|
gem 'awesome_print'
|
data/doc/Binding.html
ADDED
@@ -0,0 +1,137 @@
|
|
1
|
+
<!DOCTYPE html>
|
2
|
+
<html>
|
3
|
+
<head>
|
4
|
+
<meta charset="utf-8">
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
6
|
+
<title>
|
7
|
+
Class: Binding
|
8
|
+
|
9
|
+
— Documentation by YARD 0.9.37
|
10
|
+
|
11
|
+
</title>
|
12
|
+
|
13
|
+
<link rel="stylesheet" href="css/style.css" type="text/css" />
|
14
|
+
|
15
|
+
<link rel="stylesheet" href="css/common.css" type="text/css" />
|
16
|
+
|
17
|
+
<script type="text/javascript">
|
18
|
+
pathId = "Binding";
|
19
|
+
relpath = '';
|
20
|
+
</script>
|
21
|
+
|
22
|
+
|
23
|
+
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
|
24
|
+
|
25
|
+
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
|
26
|
+
|
27
|
+
|
28
|
+
</head>
|
29
|
+
<body>
|
30
|
+
<div class="nav_wrap">
|
31
|
+
<iframe id="nav" src="class_list.html?1"></iframe>
|
32
|
+
<div id="resizer"></div>
|
33
|
+
</div>
|
34
|
+
|
35
|
+
<div id="main" tabindex="-1">
|
36
|
+
<div id="header">
|
37
|
+
<div id="menu">
|
38
|
+
|
39
|
+
<a href="_index.html">Index (B)</a> »
|
40
|
+
|
41
|
+
|
42
|
+
<span class="title">Binding</span>
|
43
|
+
|
44
|
+
</div>
|
45
|
+
|
46
|
+
<div id="search">
|
47
|
+
|
48
|
+
<a class="full_list_link" id="class_list_link"
|
49
|
+
href="class_list.html">
|
50
|
+
|
51
|
+
<svg width="24" height="24">
|
52
|
+
<rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
|
53
|
+
<rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
|
54
|
+
<rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
|
55
|
+
</svg>
|
56
|
+
</a>
|
57
|
+
|
58
|
+
</div>
|
59
|
+
<div class="clear"></div>
|
60
|
+
</div>
|
61
|
+
|
62
|
+
<div id="content"><h1>Class: Binding
|
63
|
+
|
64
|
+
|
65
|
+
|
66
|
+
</h1>
|
67
|
+
<div class="box_info">
|
68
|
+
|
69
|
+
<dl>
|
70
|
+
<dt>Inherits:</dt>
|
71
|
+
<dd>
|
72
|
+
<span class="inheritName">Object</span>
|
73
|
+
|
74
|
+
<ul class="fullTree">
|
75
|
+
<li>Object</li>
|
76
|
+
|
77
|
+
<li class="next">Binding</li>
|
78
|
+
|
79
|
+
</ul>
|
80
|
+
<a href="#" class="inheritanceTree">show all</a>
|
81
|
+
|
82
|
+
</dd>
|
83
|
+
</dl>
|
84
|
+
|
85
|
+
|
86
|
+
|
87
|
+
|
88
|
+
|
89
|
+
|
90
|
+
<dl>
|
91
|
+
<dt>Includes:</dt>
|
92
|
+
<dd><span class='object_link'><a href="Debugging.html" title="Debugging (module)">Debugging</a></span></dd>
|
93
|
+
</dl>
|
94
|
+
|
95
|
+
|
96
|
+
|
97
|
+
|
98
|
+
|
99
|
+
|
100
|
+
<dl>
|
101
|
+
<dt>Defined in:</dt>
|
102
|
+
<dd>lib/binding.rb</dd>
|
103
|
+
</dl>
|
104
|
+
|
105
|
+
</div>
|
106
|
+
|
107
|
+
|
108
|
+
|
109
|
+
|
110
|
+
|
111
|
+
|
112
|
+
|
113
|
+
|
114
|
+
|
115
|
+
|
116
|
+
|
117
|
+
|
118
|
+
|
119
|
+
|
120
|
+
|
121
|
+
<h2>Method Summary</h2>
|
122
|
+
|
123
|
+
<h3 class="inherited">Methods included from <span class='object_link'><a href="Debugging.html" title="Debugging (module)">Debugging</a></span></h3>
|
124
|
+
<p class="inherited"><span class='object_link'><a href="Debugging.html#let_vars_hash-instance_method" title="Debugging#let_vars_hash (method)">#let_vars_hash</a></span></p>
|
125
|
+
|
126
|
+
|
127
|
+
</div>
|
128
|
+
|
129
|
+
<div id="footer">
|
130
|
+
Generated on Tue Oct 22 23:16:25 2024 by
|
131
|
+
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
132
|
+
0.9.37 (ruby-3.1.3).
|
133
|
+
</div>
|
134
|
+
|
135
|
+
</div>
|
136
|
+
</body>
|
137
|
+
</html>
|