From dd827a39ac27edd33e752432aa77a9e7abc79ae7 Mon Sep 17 00:00:00 2001 From: Stephen Margheim Date: Thu, 22 Aug 2024 16:37:57 +0200 Subject: [PATCH] Add more detail from the rails guide in the section on manually reporting an error --- README.md | 46 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4b118c9..3cbc37f 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Solid Errors is a DB-based, app-internal exception tracker for Rails applications, designed with simplicity and performance in mind. It uses the new [Rails error reporting API](https://guides.rubyonrails.org/error_reporting.html) to store uncaught exceptions in the database, and provides a simple UI for viewing and managing exceptions. -> [!WARNING] +> [!WARNING] > The current point release of Rails (7.1.3.2) has a bug which severely limits the utility of Solid Errors. Exceptions raised during a web request *are not* reported to Rails' error reporter. There is a fix in the `main` branch, but it has not been released in a new point release. As such, Solid Errors is **not** production-ready unless you are running Rails from the `main` branch or until a new point version is released and you upgrade. > The original bug report can be found [here](https://github.com/rails/rails/issues/51002) and the pull request making the fix is [here](https://github.com/rails/rails/pull/51050). I will try to backport the fix into the gem directly, but I haven't quite figured it out yet. @@ -71,10 +71,50 @@ There are intentionally few features; you can view and resolve errors. That’s ### Manually reporting an Error -Errors can be added to Solid Errors via the Rails error reporting API: +Errors can be added to Solid Errors via the [Rails error reporter](https://guides.rubyonrails.org/error_reporting.html). + +There are [three ways](https://guides.rubyonrails.org/error_reporting.html#using-the-error-reporter) you can use the error reporter: + +`Rails.error.handle` will report any error raised within the block. It will then swallow the error, and the rest of your code outside the block will continue as normal. + +```ruby +result = Rails.error.handle do + 1 + '1' # raises TypeError +end +result # => nil +1 + 1 # This will be executed +``` + +`Rails.error.record` will report errors to all registered subscribers and then re-raise the error, meaning that the rest of your code won't execute. ```ruby -Rails.error.report(error) +Rails.error.record do + 1 + '1' # raises TypeError +end +1 + 1 # This won't be executed +``` + +You can also manually report errors by calling `Rails.error.report`: + +```ruby +begin + # code +rescue StandardError => e + Rails.error.report(e) +end +``` + +All 3 reporting APIs (`#handle`, `#record`, and `#report`) support the following options, which are then passed along to all registered subscribers: + +* `handled`: a Boolean to indicate if the error was handled. This is set to `true` by default. `#record` sets this to `false`. +* `severity`: a Symbol describing the severity of the error. Expected values are: `:error`, `:warning`, and `:info`. `#handle` sets this to `:warning`, while `#record` sets it to `:error`. +* `context`: a Hash to provide more context about the error, like request or user details +* `source`: a String about the source of the error. The default source is `"application"`. Errors reported by internal libraries may set other sources; the Redis cache library may use "redis_cache_store.active_support", for instance. Your subscriber can use the source to ignore errors you aren't interested in. + +```ruby +Rails.error.handle(context: { user_id: user.id }, severity: :info) do + # ... +end ``` ### Configuration