From 496ae35e906dafcc7172ebe2aa5d4cba5b7dd92f Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Fri, 23 Aug 2024 16:53:37 +0100 Subject: [PATCH 01/17] Make 'for libraries' section a top section and rename --- guides/source/error_reporting.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index 4920c5a4d63a1..3f565d15e1c4d 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -165,7 +165,8 @@ Rails.error.handle(context: { b: 3 }) { raise } # The reported context will be: {:a=>1, :b=>3} ``` -### For Libraries +Error-reporting Libraries +------------------------ Error-reporting libraries can register their subscribers in a `Railtie`: @@ -179,4 +180,4 @@ module MySdk end ``` -If you register an error subscriber, but still have other error mechanisms like a Rack middleware, you may end up with errors reported multiple times. You should either remove your other mechanisms or adjust your report functionality so it skips reporting an exception it has seen before. +If you register an error subscriber, but still have other error mechanisms like a Rack middleware, you may end up with errors reported multiple times. You should either remove your other mechanisms or adjust your report functionality so it skips reporting an exception it has seen before. \ No newline at end of file From c56150eba6c6466a53c931141e5d9a32e56f47f5 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Fri, 23 Aug 2024 17:08:46 +0100 Subject: [PATCH 02/17] Wrap error reporting libraries subscriber information in a note --- guides/source/error_reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index 3f565d15e1c4d..7423d226e2c34 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -45,7 +45,7 @@ Using the Rails' error reporter is not required. All other means of capturing er To use the error reporter, you need a _subscriber_. A subscriber is any object with a `report` method. When an error occurs in your application or is manually reported, the Rails error reporter will call this method with the error object and some options. -Some error-reporting libraries, such as [Sentry's](https://github.com/getsentry/sentry-ruby/blob/e18ce4b6dcce2ebd37778c1e96164684a1e9ebfc/sentry-rails/lib/sentry/rails/error_subscriber.rb) and [Honeybadger's](https://docs.honeybadger.io/lib/ruby/integration-guides/rails-exception-tracking/), automatically register a subscriber for you. Consult your provider's documentation for more details. +NOTE: Some error-reporting libraries, such as [Sentry's](https://github.com/getsentry/sentry-ruby/blob/e18ce4b6dcce2ebd37778c1e96164684a1e9ebfc/sentry-rails/lib/sentry/rails/error_subscriber.rb) and [Honeybadger's](https://docs.honeybadger.io/lib/ruby/integration-guides/rails-exception-tracking/), automatically register a subscriber for you. Consult your provider's documentation for more details. You may also create a custom subscriber. For example: From 103fe22b9a249d78be06a79aa7a5272c501ee445 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Fri, 23 Aug 2024 18:36:20 +0100 Subject: [PATCH 03/17] Adjust wording and add links to make easier for beginners --- guides/source/error_reporting.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index 7423d226e2c34..7015716ee70fa 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -3,7 +3,7 @@ Error Reporting in Rails Applications ======================== -This guide introduces ways to manage exceptions that occur in Ruby on Rails applications. +This guide introduces ways to manage exceptions that occur in Ruby on Rails applications. Exceptions are any events that interrupt the normal flow of your program, such as errors. After reading this guide, you will know: @@ -15,7 +15,7 @@ After reading this guide, you will know: Error Reporting ------------------------ -The Rails [error reporter](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html) provides a standard way to collect exceptions that occur in your application and report them to your preferred service or location. +The Rails [error reporter](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html) provides a standard way to collect exceptions that occur in your application and report them to your preferred service or location (e.g. a monitoring service such as [Sentry](https://github.com/getsentry/sentry-ruby/blob/e18ce4b6dcce2ebd37778c1e96164684a1e9ebfc/sentry-rails/lib/sentry/rails/error_subscriber.rb)). The error reporter aims to replace boilerplate error-handling code like this: @@ -35,15 +35,15 @@ Rails.error.handle(SomethingIsBroken) do end ``` -Rails wraps all executions (such as HTTP requests, jobs, and `rails runner` invocations) in the error reporter, so any unhandled errors raised in your app will automatically be reported to your error-reporting service via their subscribers. +Rails wraps all executions (such as [HTTP requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), [jobs](https://guides.rubyonrails.org/active_job_basics.html), and [rails runner](https://guides.rubyonrails.org/command_line.html#bin-rails-runner) invocations) in the error reporter, so any unhandled errors raised in your app will automatically be reported to your error-reporting service via their subscribers. -This means that third-party error-reporting libraries no longer need to insert a Rack middleware or do any monkey-patching to capture unhandled exceptions. Libraries that use ActiveSupport can also use this to non-intrusively report warnings that would previously have been lost in logs. +This means that third-party error-reporting libraries no longer need to insert a [Rack](https://guides.rubyonrails.org/rails_on_rack.html) middleware or do any monkey-patching to capture unhandled exceptions. Libraries that use ActiveSupport can also use this to non-intrusively report warnings that would previously have been lost in logs. -Using the Rails' error reporter is not required. All other means of capturing errors still work. +NOTE: Using the Rails' error reporter is not required. All other means of capturing errors still work. ### Subscribing to the Reporter -To use the error reporter, you need a _subscriber_. A subscriber is any object with a `report` method. When an error occurs in your application or is manually reported, the Rails error reporter will call this method with the error object and some options. +To use the error reporter, you need a _subscriber_. A subscriber can be any object with a `report` method. When an error occurs in your application or is manually reported, the Rails error reporter will call this method with the error object and some options. NOTE: Some error-reporting libraries, such as [Sentry's](https://github.com/getsentry/sentry-ruby/blob/e18ce4b6dcce2ebd37778c1e96164684a1e9ebfc/sentry-rails/lib/sentry/rails/error_subscriber.rb) and [Honeybadger's](https://docs.honeybadger.io/lib/ruby/integration-guides/rails-exception-tracking/), automatically register a subscriber for you. Consult your provider's documentation for more details. @@ -58,7 +58,7 @@ class ErrorSubscriber end ``` -After defining the subscriber class, register it by calling [`Rails.error.subscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-subscribe) method: +After defining the subscriber class, register it by calling [`Rails.error.subscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-subscribe) method in an initializer: ```ruby Rails.error.subscribe(ErrorSubscriber.new) @@ -117,7 +117,7 @@ rescue StandardError => e end ``` -Any options you pass will be passed on the error subscribers. +Any options you pass will be passed on to the error subscribers. ### Error-reporting Options @@ -168,7 +168,7 @@ Rails.error.handle(context: { b: 3 }) { raise } Error-reporting Libraries ------------------------ -Error-reporting libraries can register their subscribers in a `Railtie`: +Error-reporting libraries can register their subscribers in a [Railtie](https://api.rubyonrails.org/classes/Rails/Railtie.html): ```ruby module MySdk From 9f943e7c4a8e959a893cefe8f16ab1d7764840c2 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Fri, 30 Aug 2024 19:58:16 +0100 Subject: [PATCH 04/17] Add Reporting Unexpected Errors section --- guides/source/error_reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index 7015716ee70fa..fe719d8a3f79f 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -94,7 +94,7 @@ end #### Reporting and Re-raising Errors -[`Rails.error.record`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-record) will report errors to all registered subscribers and then re-raise the error, meaning that the rest of your code won't execute. +[`Rails.error.record`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-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.record do From fa7d09c76de9c31acac2bf414b4dab94dbcb5896 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Fri, 30 Aug 2024 21:34:00 +0100 Subject: [PATCH 05/17] Add further information to Reporting Unexpected Errors --- guides/source/error_reporting.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index fe719d8a3f79f..0f1eb54bbdd07 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -119,6 +119,27 @@ end Any options you pass will be passed on to the error subscribers. +#### Reporting Unexpected Errors + +You can report any errors that unexpectedly occur when the imagined conditions of your code are not met by calling [`Rails.error.unexpected`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unexpected") + +When called in production, this method will return nil after the error is reported and the execution of your code will continue. + +When called in development, the error will be wrapped in a new error class (to ensure it's not being rescued higher in the stack) and surfaced to the developer. + +For example: + +```ruby +def edit + if published? + Rails.error.unexpected("[BUG] Attempting to edit a published article, that shouldn't be possible") + return false + end + # ... +end +``` +This method is intended to gracefully handle any errors that may occur in production, but that aren't anticipated at the time of writing. + ### Error-reporting Options All 3 reporting APIs (`#handle`, `#record`, and `#report`) support the following options, which are then passed along to all registered subscribers: From 52e93e758776253f7393f3ac8c249a4fa6027afe Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Fri, 30 Aug 2024 21:40:15 +0100 Subject: [PATCH 06/17] Add unsubscribe section --- guides/source/error_reporting.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index 0f1eb54bbdd07..82e505f0222b3 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -66,6 +66,15 @@ Rails.error.subscribe(ErrorSubscriber.new) You can register as many subscribers as you wish. Rails will call them in turn, in the order in which they were registered. +You can also unregister a subscriber by calling [`Rails.error.unsubscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unsubscribe). Both `subscribe` and `unsubscribe` can take either a subscriber or a class as follows: + +```ruby +subscriber = ErrorSubscriber.new +Rails.error.unsubscribe(subscriber) +# or +Rails.error.unsubscribe(ErrorSubscriber) +``` + NOTE: The Rails error-reporter will always call registered subscribers, regardless of your environment. However, many error-reporting services only report errors in production by default. You should configure and test your setup across environments as needed. ### Using the Error Reporter From da0c869eb40d0a2ab6afc592b0b30f1a0bd01e1a Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Sat, 31 Aug 2024 14:44:05 +0100 Subject: [PATCH 07/17] Add disabling notifications and further touch ups --- guides/source/error_reporting.md | 51 +++++++++++++++++++------------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index 82e505f0222b3..de11daafd490e 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -3,7 +3,7 @@ Error Reporting in Rails Applications ======================== -This guide introduces ways to manage exceptions that occur in Ruby on Rails applications. Exceptions are any events that interrupt the normal flow of your program, such as errors. +This guide introduces some ways that you can manage exceptions that occur in Ruby on Rails applications. Exceptions are any events that interrupt the normal flow of your program, such as errors. After reading this guide, you will know: @@ -37,7 +37,7 @@ end Rails wraps all executions (such as [HTTP requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), [jobs](https://guides.rubyonrails.org/active_job_basics.html), and [rails runner](https://guides.rubyonrails.org/command_line.html#bin-rails-runner) invocations) in the error reporter, so any unhandled errors raised in your app will automatically be reported to your error-reporting service via their subscribers. -This means that third-party error-reporting libraries no longer need to insert a [Rack](https://guides.rubyonrails.org/rails_on_rack.html) middleware or do any monkey-patching to capture unhandled exceptions. Libraries that use ActiveSupport can also use this to non-intrusively report warnings that would previously have been lost in logs. +This means that third-party error-reporting libraries no longer need to insert a [Rack](https://guides.rubyonrails.org/rails_on_rack.html) middleware or do any monkey-patching to capture unhandled exceptions. Libraries that use [ActiveSupport](https://edgeapi.rubyonrails.org/classes/ActiveSupport.html) can also use this to non-intrusively report warnings that would previously have been lost in logs. NOTE: Using the Rails' error reporter is not required. All other means of capturing errors still work. @@ -58,7 +58,7 @@ class ErrorSubscriber end ``` -After defining the subscriber class, register it by calling [`Rails.error.subscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-subscribe) method in an initializer: +After defining the subscriber class, you can register it by calling the [`Rails.error.subscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-subscribe) method: ```ruby Rails.error.subscribe(ErrorSubscriber.new) @@ -66,7 +66,7 @@ Rails.error.subscribe(ErrorSubscriber.new) You can register as many subscribers as you wish. Rails will call them in turn, in the order in which they were registered. -You can also unregister a subscriber by calling [`Rails.error.unsubscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unsubscribe). Both `subscribe` and `unsubscribe` can take either a subscriber or a class as follows: +It is also possible to unregister a subscriber by calling [`Rails.error.unsubscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unsubscribe). Both `subscribe` and `unsubscribe` can take either a subscriber or a class as follows: ```ruby subscriber = ErrorSubscriber.new @@ -79,7 +79,7 @@ NOTE: The Rails error-reporter will always call registered subscribers, regardle ### Using the Error Reporter -There are three ways you can use the error reporter: +There are four ways you can use the error reporter: #### Reporting and Swallowing Errors @@ -130,7 +130,7 @@ Any options you pass will be passed on to the error subscribers. #### Reporting Unexpected Errors -You can report any errors that unexpectedly occur when the imagined conditions of your code are not met by calling [`Rails.error.unexpected`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unexpected") +You can report any errors that may unexpectedly occur when the imagined conditions of your code are not met by calling [`Rails.error.unexpected`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unexpected"). When called in production, this method will return nil after the error is reported and the execution of your code will continue. @@ -147,7 +147,7 @@ def edit # ... end ``` -This method is intended to gracefully handle any errors that may occur in production, but that aren't anticipated at the time of writing. +NOTE: This method is intended to gracefully handle any errors that may occur in production, but that aren't anticipated to be the result of typical use. ### Error-reporting Options @@ -163,6 +163,23 @@ Rails.error.handle(context: { user_id: user.id }, severity: :info) do # ... end ``` +### Setting Context Globally + +In addition to setting context through the `context` option, you can use [`Rails.error.set_context`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-set_context). For example: + +```ruby +Rails.error.set_context(section: "checkout", user_id: @user.id) +``` + +Any context set this way will be merged with the `context` option + +```ruby +Rails.error.set_context(a: 1) +Rails.error.handle(context: { b: 2 }) { raise } +# The reported context will be: {:a=>1, :b=>2} +Rails.error.handle(context: { b: 3 }) { raise } +# The reported context will be: {:a=>1, :b=>3} +``` ### Filtering by Error Classes @@ -177,23 +194,17 @@ end Here, the `TypeError` will not be captured by the Rails error reporter. Only instances of `IOError` and its descendants will be reported. Any other errors will be raised as normal. -### Setting Context Globally +### Disabling Notifications -In addition to setting context through the `context` option, you can use the [`#set_context`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-set_context) API. For example: +You can prevent a subscriber from being notified of errors for the duration of a block by calling [`Rails.error.disable`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-disable). Similarly to `subscribe` and `unsubscribe`, you can pass in either the subscriber itself, or its class. ```ruby -Rails.error.set_context(section: "checkout", user_id: @user.id) +Rails.error.disable(ErrorSubscriber) do + 1 + '1' # TypeError will not be reported via the ErrorSubscriber +end ``` +NOTE: This can also be helpful for third-party error reporting services who may want to manage error handling on their own. -Any context set this way will be merged with the `context` option - -```ruby -Rails.error.set_context(a: 1) -Rails.error.handle(context: { b: 2 }) { raise } -# The reported context will be: {:a=>1, :b=>2} -Rails.error.handle(context: { b: 3 }) { raise } -# The reported context will be: {:a=>1, :b=>3} -``` Error-reporting Libraries ------------------------ @@ -210,4 +221,4 @@ module MySdk end ``` -If you register an error subscriber, but still have other error mechanisms like a Rack middleware, you may end up with errors reported multiple times. You should either remove your other mechanisms or adjust your report functionality so it skips reporting an exception it has seen before. \ No newline at end of file +NOTE: If you register an error subscriber, but still have other error mechanisms like a Rack middleware, you may end up with errors reported multiple times. You should either remove your other mechanisms or adjust your report functionality so it skips reporting an exception it has seen before. \ No newline at end of file From d5bd0cca00ebf59f081a9d1f68022d87d0830c58 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Sun, 1 Sep 2024 12:01:43 +0100 Subject: [PATCH 08/17] Final wording tweaks for readability --- guides/source/error_reporting.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index de11daafd490e..f97d728e34457 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -43,7 +43,7 @@ NOTE: Using the Rails' error reporter is not required. All other means of captur ### Subscribing to the Reporter -To use the error reporter, you need a _subscriber_. A subscriber can be any object with a `report` method. When an error occurs in your application or is manually reported, the Rails error reporter will call this method with the error object and some options. +To use the error reporter with an external service, you need a _subscriber_. A subscriber can be any object with a `report` method. When an error occurs in your application or is manually reported, the Rails error reporter will call this method with the error object and some options. NOTE: Some error-reporting libraries, such as [Sentry's](https://github.com/getsentry/sentry-ruby/blob/e18ce4b6dcce2ebd37778c1e96164684a1e9ebfc/sentry-rails/lib/sentry/rails/error_subscriber.rb) and [Honeybadger's](https://docs.honeybadger.io/lib/ruby/integration-guides/rails-exception-tracking/), automatically register a subscriber for you. Consult your provider's documentation for more details. @@ -66,7 +66,7 @@ Rails.error.subscribe(ErrorSubscriber.new) You can register as many subscribers as you wish. Rails will call them in turn, in the order in which they were registered. -It is also possible to unregister a subscriber by calling [`Rails.error.unsubscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unsubscribe). Both `subscribe` and `unsubscribe` can take either a subscriber or a class as follows: +It is also possible to unregister a subscriber by calling [`Rails.error.unsubscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unsubscribe). This may be useful if you'd like to replace or remove a subscriber added by one of your dependencies. Both `subscribe` and `unsubscribe` can take either a subscriber or a class as follows: ```ruby subscriber = ErrorSubscriber.new @@ -75,7 +75,7 @@ Rails.error.unsubscribe(subscriber) Rails.error.unsubscribe(ErrorSubscriber) ``` -NOTE: The Rails error-reporter will always call registered subscribers, regardless of your environment. However, many error-reporting services only report errors in production by default. You should configure and test your setup across environments as needed. +NOTE: The Rails error reporter will always call registered subscribers, regardless of your environment. However, many error-reporting services only report errors in production by default. You should configure and test your setup across environments as needed. ### Using the Error Reporter @@ -134,7 +134,7 @@ You can report any errors that may unexpectedly occur when the imagined conditio When called in production, this method will return nil after the error is reported and the execution of your code will continue. -When called in development, the error will be wrapped in a new error class (to ensure it's not being rescued higher in the stack) and surfaced to the developer. +When called in development, the error will be wrapped in a new error class (to ensure it's not being rescued higher in the stack) and surfaced to the developer for debugging. For example: @@ -151,7 +151,7 @@ NOTE: This method is intended to gracefully handle any errors that may occur in ### Error-reporting Options -All 3 reporting APIs (`#handle`, `#record`, and `#report`) support the following options, which are then passed along to all registered subscribers: +The 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`. @@ -203,7 +203,7 @@ Rails.error.disable(ErrorSubscriber) do 1 + '1' # TypeError will not be reported via the ErrorSubscriber end ``` -NOTE: This can also be helpful for third-party error reporting services who may want to manage error handling on their own. +NOTE: This can also be helpful for third-party error reporting services who may want to manage error handling a different way, or higher in the stack. Error-reporting Libraries From 44218851d2224ce38fc40dbc66ad1cc6834cffe8 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Wed, 4 Sep 2024 18:17:22 +0100 Subject: [PATCH 09/17] Make sentry example clearer in first paragraph --- guides/source/error_reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index f97d728e34457..06a1c08357cb1 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -15,7 +15,7 @@ After reading this guide, you will know: Error Reporting ------------------------ -The Rails [error reporter](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html) provides a standard way to collect exceptions that occur in your application and report them to your preferred service or location (e.g. a monitoring service such as [Sentry](https://github.com/getsentry/sentry-ruby/blob/e18ce4b6dcce2ebd37778c1e96164684a1e9ebfc/sentry-rails/lib/sentry/rails/error_subscriber.rb)). +The Rails [error reporter](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html) provides a standard way to collect exceptions that occur in your application and report them to your preferred service or location (e.g. you could report the errors to a monitoring service such as [Sentry](https://github.com/getsentry/sentry-ruby)). The error reporter aims to replace boilerplate error-handling code like this: From 5579d4334de254e66e1d240e7b7e0b94edd7a3c0 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Wed, 4 Sep 2024 18:24:51 +0100 Subject: [PATCH 10/17] Adjust links --- guides/source/error_reporting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index 06a1c08357cb1..cc75fff12744d 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -35,9 +35,9 @@ Rails.error.handle(SomethingIsBroken) do end ``` -Rails wraps all executions (such as [HTTP requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), [jobs](https://guides.rubyonrails.org/active_job_basics.html), and [rails runner](https://guides.rubyonrails.org/command_line.html#bin-rails-runner) invocations) in the error reporter, so any unhandled errors raised in your app will automatically be reported to your error-reporting service via their subscribers. +Rails wraps all executions (such as [HTTP requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), [jobs](active_job_basics.html), and [rails runner](command_line.html#bin-rails-runner) invocations) in the error reporter, so any unhandled errors raised in your app will automatically be reported to your error-reporting service via their subscribers. -This means that third-party error-reporting libraries no longer need to insert a [Rack](https://guides.rubyonrails.org/rails_on_rack.html) middleware or do any monkey-patching to capture unhandled exceptions. Libraries that use [ActiveSupport](https://edgeapi.rubyonrails.org/classes/ActiveSupport.html) can also use this to non-intrusively report warnings that would previously have been lost in logs. +This means that third-party error-reporting libraries no longer need to insert a [Rack](rails_on_rack.html) middleware or do any monkey-patching to capture unhandled exceptions. Libraries that use [Active Support](https://api.rubyonrails.org/classes/ActiveSupport.html) can also use this to non-intrusively report warnings that would previously have been lost in logs. NOTE: Using the Rails' error reporter is not required. All other means of capturing errors still work. From 3d54af17e2f39d698a84fe5c14ec7c83e06422e9 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Wed, 4 Sep 2024 19:12:03 +0100 Subject: [PATCH 11/17] Adjust wording for consistency and clarity --- guides/source/error_reporting.md | 33 +++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index cc75fff12744d..4f01edf038b23 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -3,7 +3,7 @@ Error Reporting in Rails Applications ======================== -This guide introduces some ways that you can manage exceptions that occur in Ruby on Rails applications. Exceptions are any events that interrupt the normal flow of your program, such as errors. +This guide introduces ways to manage errors in a Rails application. After reading this guide, you will know: @@ -13,11 +13,11 @@ After reading this guide, you will know: -------------------------------------------------------------------------------- Error Reporting ------------------------- +--------------- -The Rails [error reporter](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html) provides a standard way to collect exceptions that occur in your application and report them to your preferred service or location (e.g. you could report the errors to a monitoring service such as [Sentry](https://github.com/getsentry/sentry-ruby)). +The Rails [error reporter](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html) provides a standard way to collect errors that occur in your application and report them to your preferred service or location (e.g. you could report the errors to a monitoring service such as [Sentry](https://github.com/getsentry/sentry-ruby)). -The error reporter aims to replace boilerplate error-handling code like this: +It aims to replace boilerplate error-handling code like this: ```ruby begin @@ -37,15 +37,15 @@ end Rails wraps all executions (such as [HTTP requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), [jobs](active_job_basics.html), and [rails runner](command_line.html#bin-rails-runner) invocations) in the error reporter, so any unhandled errors raised in your app will automatically be reported to your error-reporting service via their subscribers. -This means that third-party error-reporting libraries no longer need to insert a [Rack](rails_on_rack.html) middleware or do any monkey-patching to capture unhandled exceptions. Libraries that use [Active Support](https://api.rubyonrails.org/classes/ActiveSupport.html) can also use this to non-intrusively report warnings that would previously have been lost in logs. +This means that third-party error-reporting libraries no longer need to insert a [Rack](rails_on_rack.html) middleware or do any monkey-patching to capture unhandled errors. Libraries that use [Active Support](https://api.rubyonrails.org/classes/ActiveSupport.html) can also use this to non-intrusively report warnings that would previously have been lost in logs. -NOTE: Using the Rails' error reporter is not required. All other means of capturing errors still work. +NOTE: Using the Rails error reporter is optional, as other means of capturing errors still work. ### Subscribing to the Reporter -To use the error reporter with an external service, you need a _subscriber_. A subscriber can be any object with a `report` method. When an error occurs in your application or is manually reported, the Rails error reporter will call this method with the error object and some options. +To use the error reporter with an external service, you need a _subscriber_. A subscriber can be any Ruby object with a `report` method. When an error occurs in your application or is manually reported, the Rails error reporter will call this method with the error object and some options. -NOTE: Some error-reporting libraries, such as [Sentry's](https://github.com/getsentry/sentry-ruby/blob/e18ce4b6dcce2ebd37778c1e96164684a1e9ebfc/sentry-rails/lib/sentry/rails/error_subscriber.rb) and [Honeybadger's](https://docs.honeybadger.io/lib/ruby/integration-guides/rails-exception-tracking/), automatically register a subscriber for you. Consult your provider's documentation for more details. +NOTE: Some error-reporting libraries, such as [Sentry's](https://github.com/getsentry/sentry-ruby/blob/e18ce4b6dcce2ebd37778c1e96164684a1e9ebfc/sentry-rails/lib/sentry/rails/error_subscriber.rb) and [Honeybadger's](https://docs.honeybadger.io/lib/ruby/integration-guides/rails-exception-tracking/), automatically register a subscriber for you. You may also create a custom subscriber. For example: @@ -64,7 +64,7 @@ After defining the subscriber class, you can register it by calling the [`Rails. Rails.error.subscribe(ErrorSubscriber.new) ``` -You can register as many subscribers as you wish. Rails will call them in turn, in the order in which they were registered. +You can register as many subscribers as you wish. Rails will call them in the order in which they were registered. It is also possible to unregister a subscriber by calling [`Rails.error.unsubscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unsubscribe). This may be useful if you'd like to replace or remove a subscriber added by one of your dependencies. Both `subscribe` and `unsubscribe` can take either a subscriber or a class as follows: @@ -79,11 +79,11 @@ NOTE: The Rails error reporter will always call registered subscribers, regardle ### Using the Error Reporter -There are four ways you can use the error reporter: +Rails error reporter has four methods that allow you to report methods in different ways: `Rails.error.handle`, `Rails.error.record`, `Rails.error.report`, and `Rails.error.unexpected`. #### Reporting and Swallowing Errors -[`Rails.error.handle`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-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. +The [`Rails.error.handle`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-handle) method 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 @@ -103,7 +103,7 @@ end #### Reporting and Re-raising Errors -[`Rails.error.record`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-record) will report errors to all registered subscribers and then **re-raise** the error, meaning that the rest of your code won't execute. +The [`Rails.error.record`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-record) method 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.record do @@ -130,7 +130,7 @@ Any options you pass will be passed on to the error subscribers. #### Reporting Unexpected Errors -You can report any errors that may unexpectedly occur when the imagined conditions of your code are not met by calling [`Rails.error.unexpected`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unexpected"). +You can report any unexpected error by calling [`Rails.error.unexpected`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unexpected"). When called in production, this method will return nil after the error is reported and the execution of your code will continue. @@ -147,6 +147,7 @@ def edit # ... end ``` + NOTE: This method is intended to gracefully handle any errors that may occur in production, but that aren't anticipated to be the result of typical use. ### Error-reporting Options @@ -163,6 +164,7 @@ Rails.error.handle(context: { user_id: user.id }, severity: :info) do # ... end ``` + ### Setting Context Globally In addition to setting context through the `context` option, you can use [`Rails.error.set_context`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-set_context). For example: @@ -196,13 +198,14 @@ Here, the `TypeError` will not be captured by the Rails error reporter. Only ins ### Disabling Notifications -You can prevent a subscriber from being notified of errors for the duration of a block by calling [`Rails.error.disable`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-disable). Similarly to `subscribe` and `unsubscribe`, you can pass in either the subscriber itself, or its class. +You can prevent a subscriber from being notified of errors for the duration of a block by calling [`Rails.error.disable`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-disable). Similarly to `subscribe` and `unsubscribe`, you can pass in either the subscriber itself, or its class. ```ruby Rails.error.disable(ErrorSubscriber) do 1 + '1' # TypeError will not be reported via the ErrorSubscriber end ``` + NOTE: This can also be helpful for third-party error reporting services who may want to manage error handling a different way, or higher in the stack. @@ -221,4 +224,4 @@ module MySdk end ``` -NOTE: If you register an error subscriber, but still have other error mechanisms like a Rack middleware, you may end up with errors reported multiple times. You should either remove your other mechanisms or adjust your report functionality so it skips reporting an exception it has seen before. \ No newline at end of file +NOTE: If you register an error subscriber, but still have other error mechanisms like a Rack middleware, you may end up with errors reported multiple times. You should either remove your other mechanisms or adjust your report functionality so it skips reporting an error it has seen before. \ No newline at end of file From f2a9ce9037134dc907d7c8cfb2057c0a9ddce1ff Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Wed, 4 Sep 2024 19:24:24 +0100 Subject: [PATCH 12/17] Wrap text with 80 columns --- guides/source/error_reporting.md | 139 +++++++++++++++++++++++-------- 1 file changed, 106 insertions(+), 33 deletions(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index 4f01edf038b23..1fc693a028d46 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -15,7 +15,12 @@ After reading this guide, you will know: Error Reporting --------------- -The Rails [error reporter](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html) provides a standard way to collect errors that occur in your application and report them to your preferred service or location (e.g. you could report the errors to a monitoring service such as [Sentry](https://github.com/getsentry/sentry-ruby)). +The Rails [error +reporter](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html) +provides a standard way to collect errors that occur in your application and +report them to your preferred service or location (e.g. you could report the +errors to a monitoring service such as +[Sentry](https://github.com/getsentry/sentry-ruby)). It aims to replace boilerplate error-handling code like this: @@ -35,17 +40,35 @@ Rails.error.handle(SomethingIsBroken) do end ``` -Rails wraps all executions (such as [HTTP requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), [jobs](active_job_basics.html), and [rails runner](command_line.html#bin-rails-runner) invocations) in the error reporter, so any unhandled errors raised in your app will automatically be reported to your error-reporting service via their subscribers. +Rails wraps all executions (such as [HTTP +requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), +[jobs](active_job_basics.html), and [rails +runner](command_line.html#bin-rails-runner) invocations) in the error reporter, +so any unhandled errors raised in your app will automatically be reported to +your error-reporting service via their subscribers. -This means that third-party error-reporting libraries no longer need to insert a [Rack](rails_on_rack.html) middleware or do any monkey-patching to capture unhandled errors. Libraries that use [Active Support](https://api.rubyonrails.org/classes/ActiveSupport.html) can also use this to non-intrusively report warnings that would previously have been lost in logs. +This means that third-party error-reporting libraries no longer need to insert a +[Rack](rails_on_rack.html) middleware or do any monkey-patching to capture +unhandled errors. Libraries that use [Active +Support](https://api.rubyonrails.org/classes/ActiveSupport.html) can also use +this to non-intrusively report warnings that would previously have been lost in +logs. -NOTE: Using the Rails error reporter is optional, as other means of capturing errors still work. +NOTE: Using the Rails error reporter is optional, as other means of capturing +errors still work. ### Subscribing to the Reporter -To use the error reporter with an external service, you need a _subscriber_. A subscriber can be any Ruby object with a `report` method. When an error occurs in your application or is manually reported, the Rails error reporter will call this method with the error object and some options. +To use the error reporter with an external service, you need a _subscriber_. A +subscriber can be any Ruby object with a `report` method. When an error occurs +in your application or is manually reported, the Rails error reporter will call +this method with the error object and some options. -NOTE: Some error-reporting libraries, such as [Sentry's](https://github.com/getsentry/sentry-ruby/blob/e18ce4b6dcce2ebd37778c1e96164684a1e9ebfc/sentry-rails/lib/sentry/rails/error_subscriber.rb) and [Honeybadger's](https://docs.honeybadger.io/lib/ruby/integration-guides/rails-exception-tracking/), automatically register a subscriber for you. +NOTE: Some error-reporting libraries, such as +[Sentry's](https://github.com/getsentry/sentry-ruby/blob/e18ce4b6dcce2ebd37778c1e96164684a1e9ebfc/sentry-rails/lib/sentry/rails/error_subscriber.rb) +and +[Honeybadger's](https://docs.honeybadger.io/lib/ruby/integration-guides/rails-exception-tracking/), +automatically register a subscriber for you. You may also create a custom subscriber. For example: @@ -58,15 +81,22 @@ class ErrorSubscriber end ``` -After defining the subscriber class, you can register it by calling the [`Rails.error.subscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-subscribe) method: +After defining the subscriber class, you can register it by calling the +[`Rails.error.subscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-subscribe) +method: ```ruby Rails.error.subscribe(ErrorSubscriber.new) ``` -You can register as many subscribers as you wish. Rails will call them in the order in which they were registered. +You can register as many subscribers as you wish. Rails will call them in the +order in which they were registered. -It is also possible to unregister a subscriber by calling [`Rails.error.unsubscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unsubscribe). This may be useful if you'd like to replace or remove a subscriber added by one of your dependencies. Both `subscribe` and `unsubscribe` can take either a subscriber or a class as follows: +It is also possible to unregister a subscriber by calling +[`Rails.error.unsubscribe`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unsubscribe). +This may be useful if you'd like to replace or remove a subscriber added by one +of your dependencies. Both `subscribe` and `unsubscribe` can take either a +subscriber or a class as follows: ```ruby subscriber = ErrorSubscriber.new @@ -75,15 +105,23 @@ Rails.error.unsubscribe(subscriber) Rails.error.unsubscribe(ErrorSubscriber) ``` -NOTE: The Rails error reporter will always call registered subscribers, regardless of your environment. However, many error-reporting services only report errors in production by default. You should configure and test your setup across environments as needed. +NOTE: The Rails error reporter will always call registered subscribers, +regardless of your environment. However, many error-reporting services only +report errors in production by default. You should configure and test your setup +across environments as needed. ### Using the Error Reporter -Rails error reporter has four methods that allow you to report methods in different ways: `Rails.error.handle`, `Rails.error.record`, `Rails.error.report`, and `Rails.error.unexpected`. +Rails error reporter has four methods that allow you to report methods in +different ways: `Rails.error.handle`, `Rails.error.record`, +`Rails.error.report`, and `Rails.error.unexpected`. #### Reporting and Swallowing Errors -The [`Rails.error.handle`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-handle) method 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. +The +[`Rails.error.handle`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-handle) +method 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 @@ -93,7 +131,9 @@ result # => nil 1 + 1 # This will be executed ``` -If no error is raised in the block, `Rails.error.handle` will return the result of the block, otherwise it will return `nil`. You can override this by providing a `fallback`: +If no error is raised in the block, `Rails.error.handle` will return the result +of the block, otherwise it will return `nil`. You can override this by providing +a `fallback`: ```ruby user = Rails.error.handle(fallback: -> { User.anonymous }) do @@ -103,7 +143,10 @@ end #### Reporting and Re-raising Errors -The [`Rails.error.record`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-record) method will report errors to all registered subscribers and then **re-raise** the error, meaning that the rest of your code won't execute. +The +[`Rails.error.record`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-record) +method 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.record do @@ -112,11 +155,13 @@ end 1 + 1 # This won't be executed ``` -If no error is raised in the block, `Rails.error.record` will return the result of the block. +If no error is raised in the block, `Rails.error.record` will return the result +of the block. #### Manually Reporting Errors -You can also manually report errors by calling [`Rails.error.report`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-report): +You can also manually report errors by calling +[`Rails.error.report`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-report): ```ruby begin @@ -130,11 +175,15 @@ Any options you pass will be passed on to the error subscribers. #### Reporting Unexpected Errors -You can report any unexpected error by calling [`Rails.error.unexpected`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unexpected"). +You can report any unexpected error by calling +[`Rails.error.unexpected`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-unexpected"). -When called in production, this method will return nil after the error is reported and the execution of your code will continue. +When called in production, this method will return nil after the error is +reported and the execution of your code will continue. -When called in development, the error will be wrapped in a new error class (to ensure it's not being rescued higher in the stack) and surfaced to the developer for debugging. +When called in development, the error will be wrapped in a new error class (to +ensure it's not being rescued higher in the stack) and surfaced to the developer +for debugging. For example: @@ -148,16 +197,26 @@ def edit end ``` -NOTE: This method is intended to gracefully handle any errors that may occur in production, but that aren't anticipated to be the result of typical use. +NOTE: This method is intended to gracefully handle any errors that may occur in +production, but that aren't anticipated to be the result of typical use. ### Error-reporting Options -The 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. +The 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 @@ -167,7 +226,9 @@ end ### Setting Context Globally -In addition to setting context through the `context` option, you can use [`Rails.error.set_context`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-set_context). For example: +In addition to setting context through the `context` option, you can use +[`Rails.error.set_context`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-set_context). +For example: ```ruby Rails.error.set_context(section: "checkout", user_id: @user.id) @@ -185,7 +246,8 @@ Rails.error.handle(context: { b: 3 }) { raise } ### Filtering by Error Classes -With `Rails.error.handle` and `Rails.error.record`, you can also choose to only report errors of certain classes. For example: +With `Rails.error.handle` and `Rails.error.record`, you can also choose to only +report errors of certain classes. For example: ```ruby Rails.error.handle(IOError) do @@ -194,11 +256,17 @@ end 1 + 1 # TypeErrors are not IOErrors, so this will *not* be executed ``` -Here, the `TypeError` will not be captured by the Rails error reporter. Only instances of `IOError` and its descendants will be reported. Any other errors will be raised as normal. +Here, the `TypeError` will not be captured by the Rails error reporter. Only +instances of `IOError` and its descendants will be reported. Any other errors +will be raised as normal. ### Disabling Notifications -You can prevent a subscriber from being notified of errors for the duration of a block by calling [`Rails.error.disable`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-disable). Similarly to `subscribe` and `unsubscribe`, you can pass in either the subscriber itself, or its class. +You can prevent a subscriber from being notified of errors for the duration of a +block by calling +[`Rails.error.disable`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-disable). +Similarly to `subscribe` and `unsubscribe`, you can pass in either the +subscriber itself, or its class. ```ruby Rails.error.disable(ErrorSubscriber) do @@ -206,13 +274,15 @@ Rails.error.disable(ErrorSubscriber) do end ``` -NOTE: This can also be helpful for third-party error reporting services who may want to manage error handling a different way, or higher in the stack. +NOTE: This can also be helpful for third-party error reporting services who may +want to manage error handling a different way, or higher in the stack. Error-reporting Libraries ------------------------ -Error-reporting libraries can register their subscribers in a [Railtie](https://api.rubyonrails.org/classes/Rails/Railtie.html): +Error-reporting libraries can register their subscribers in a +[Railtie](https://api.rubyonrails.org/classes/Rails/Railtie.html): ```ruby module MySdk @@ -224,4 +294,7 @@ module MySdk end ``` -NOTE: If you register an error subscriber, but still have other error mechanisms like a Rack middleware, you may end up with errors reported multiple times. You should either remove your other mechanisms or adjust your report functionality so it skips reporting an error it has seen before. \ No newline at end of file +NOTE: If you register an error subscriber, but still have other error mechanisms +like a Rack middleware, you may end up with errors reported multiple times. You +should either remove your other mechanisms or adjust your report functionality +so it skips reporting an error it has seen before. \ No newline at end of file From a839cacb98935605ad49b40074120cae1f31d5e5 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Mon, 9 Sep 2024 20:18:04 +0100 Subject: [PATCH 13/17] Remove external references --- guides/source/error_reporting.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index 1fc693a028d46..31b5f73a53ede 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -20,7 +20,7 @@ reporter](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html) provides a standard way to collect errors that occur in your application and report them to your preferred service or location (e.g. you could report the errors to a monitoring service such as -[Sentry](https://github.com/getsentry/sentry-ruby)). +Sentry). It aims to replace boilerplate error-handling code like this: @@ -40,10 +40,9 @@ Rails.error.handle(SomethingIsBroken) do end ``` -Rails wraps all executions (such as [HTTP -requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), -[jobs](active_job_basics.html), and [rails -runner](command_line.html#bin-rails-runner) invocations) in the error reporter, +Rails wraps all executions (such as HTTP +requests, +[jobs](active_job_basics.html), and [rails runner](command_line.html#bin-rails-runner) invocations) in the error reporter, so any unhandled errors raised in your app will automatically be reported to your error-reporting service via their subscribers. @@ -64,10 +63,8 @@ subscriber can be any Ruby object with a `report` method. When an error occurs in your application or is manually reported, the Rails error reporter will call this method with the error object and some options. -NOTE: Some error-reporting libraries, such as -[Sentry's](https://github.com/getsentry/sentry-ruby/blob/e18ce4b6dcce2ebd37778c1e96164684a1e9ebfc/sentry-rails/lib/sentry/rails/error_subscriber.rb) -and -[Honeybadger's](https://docs.honeybadger.io/lib/ruby/integration-guides/rails-exception-tracking/), +NOTE: Some error-reporting libraries, such as Sentry's +and Honeybadger's, automatically register a subscriber for you. You may also create a custom subscriber. For example: From cf989531ffdff4a261a48cef84622b6f9ef8a851 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Mon, 9 Sep 2024 20:20:02 +0100 Subject: [PATCH 14/17] Remove blank line --- guides/source/error_reporting.md | 1 - 1 file changed, 1 deletion(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index 31b5f73a53ede..f2b90512145c7 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -274,7 +274,6 @@ end NOTE: This can also be helpful for third-party error reporting services who may want to manage error handling a different way, or higher in the stack. - Error-reporting Libraries ------------------------ From dc106f7ff57f1cf7684181e80f01f08cb8a16a96 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Wed, 11 Sep 2024 17:57:38 +0100 Subject: [PATCH 15/17] Remove redundant return --- guides/source/error_reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index f2b90512145c7..3e05dc9a5660c 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -188,7 +188,7 @@ For example: def edit if published? Rails.error.unexpected("[BUG] Attempting to edit a published article, that shouldn't be possible") - return false + false end # ... end From 59685f4b51a66a02932a3c66b65184b207b851f5 Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Wed, 11 Sep 2024 18:00:24 +0100 Subject: [PATCH 16/17] Add newline to the end of the file --- guides/source/error_reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index 3e05dc9a5660c..fc304fccfb2a1 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -293,4 +293,4 @@ end NOTE: If you register an error subscriber, but still have other error mechanisms like a Rack middleware, you may end up with errors reported multiple times. You should either remove your other mechanisms or adjust your report functionality -so it skips reporting an error it has seen before. \ No newline at end of file +so it skips reporting an error it has seen before. From 6bb02656097f6ac261268e2713f612ce1a82653a Mon Sep 17 00:00:00 2001 From: harriet oughton Date: Wed, 2 Oct 2024 18:24:53 +0100 Subject: [PATCH 17/17] Update documents.yml and add bullet points --- guides/source/documents.yaml | 2 +- guides/source/error_reporting.md | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/guides/source/documents.yaml b/guides/source/documents.yaml index 3a46baca0ca02..cf51a370aa10f 100644 --- a/guides/source/documents.yaml +++ b/guides/source/documents.yaml @@ -175,7 +175,7 @@ - name: Error Reporting in Rails Applications url: error_reporting.html - description: This guide introduces ways to manage exceptions that occur in Ruby on Rails applications. + description: This guide introduces ways to manage errors that occur in Ruby on Rails applications. - name: Debugging Rails Applications url: debugging_rails_applications.html diff --git a/guides/source/error_reporting.md b/guides/source/error_reporting.md index fc304fccfb2a1..eb167116619a6 100644 --- a/guides/source/error_reporting.md +++ b/guides/source/error_reporting.md @@ -110,8 +110,12 @@ across environments as needed. ### Using the Error Reporter Rails error reporter has four methods that allow you to report methods in -different ways: `Rails.error.handle`, `Rails.error.record`, -`Rails.error.report`, and `Rails.error.unexpected`. +different ways: + +* `Rails.error.handle` +* `Rails.error.record` +* `Rails.error.report` +* `Rails.error.unexpected` #### Reporting and Swallowing Errors