Class: ActiveSupport::ErrorReporter
Relationships & Source Files | |
Namespace Children | |
Modules:
| |
Inherits: | Object |
Defined in: | activesupport/lib/active_support/error_reporter.rb |
Overview
ErrorReporter
is a common interface for error reporting services.
To rescue and report any unhandled error, you can use the #handle method:
Rails.error.handle do
do_something!
end
If an error is raised, it will be reported and swallowed.
Alternatively, if you want to report the error but not swallow it, you can use #record:
Rails.error.record do
do_something!
end
Both methods can be restricted to handle only a specific error class:
= Rails.error.handle(Redis::BaseError) { redis.get("tags") }
Constant Summary
-
DEFAULT_RESCUE =
# File 'activesupport/lib/active_support/error_reporter.rb', line 29[StandardError].freeze
-
DEFAULT_SOURCE =
# File 'activesupport/lib/active_support/error_reporter.rb', line 28"application"
-
SEVERITIES =
# File 'activesupport/lib/active_support/error_reporter.rb', line 27%i(error warning info)
-
UnexpectedError =
# File 'activesupport/lib/active_support/error_reporter.rb', line 33Class.new(Exception)
Class Method Summary
- .new(*subscribers, logger: nil) ⇒ ErrorReporter constructor
Instance Attribute Summary
- #debug_mode rw
- #logger rw
Instance Method Summary
-
#disable(subscriber)
Prevent a subscriber from being notified of errors for the duration of the block.
-
#handle(*error_classes, severity: :warning, context: {}, fallback: nil, source: DEFAULT_SOURCE)
Evaluates the given block, reporting and swallowing any unhandled error.
-
#record(*error_classes, severity: :error, context: {}, source: DEFAULT_SOURCE)
Evaluates the given block, reporting and re-raising any unhandled error.
-
#report(error, handled: true, severity: handled ? :warning : :error, context: {}, source: DEFAULT_SOURCE)
Report an error directly to subscribers.
-
#set_context
Update the execution context that is accessible to error subscribers.
-
#subscribe(subscriber)
Register a new error subscriber.
-
#unexpected(error, severity: :warning, context: {}, source: DEFAULT_SOURCE)
Either report the given error when in production, or raise it when in development or test.
-
#unsubscribe(subscriber)
Unregister an error subscriber.
- #ensure_backtrace(error) private
Constructor Details
.new(*subscribers, logger: nil) ⇒ ErrorReporter
# File 'activesupport/lib/active_support/error_reporter.rb', line 35
def initialize(*subscribers, logger: nil) @subscribers = subscribers.flatten @logger = logger @debug_mode = false end
Instance Attribute Details
#debug_mode (rw)
[ GitHub ]# File 'activesupport/lib/active_support/error_reporter.rb', line 31
attr_accessor :logger, :debug_mode
#logger (rw)
[ GitHub ]# File 'activesupport/lib/active_support/error_reporter.rb', line 31
attr_accessor :logger, :debug_mode
Instance Method Details
#disable(subscriber)
Prevent a subscriber from being notified of errors for the duration of the block. You may pass in the subscriber itself, or its class.
This can be helpful for error reporting service integrations, when they wish to handle any errors higher in the stack.
# File 'activesupport/lib/active_support/error_reporter.rb', line 185
def disable(subscriber) disabled_subscribers = (ActiveSupport::IsolatedExecutionState[self] ||= []) disabled_subscribers << subscriber begin yield ensure disabled_subscribers.delete(subscriber) end end
#ensure_backtrace(error) (private)
[ GitHub ]# File 'activesupport/lib/active_support/error_reporter.rb', line 243
def ensure_backtrace(error) return if error.frozen? # re-raising won't add a backtrace return unless error.backtrace.nil? begin # We could use Exception#set_backtrace, but until Ruby 3.4 # it only support setting `Exception#backtrace` and not # `Exception#backtrace_locations`. So raising the exception # is a good way to build a real backtrace. raise error rescue error.class => error end count = 0 while error.backtrace_locations.first&.path == __FILE__ count += 1 error.backtrace_locations.shift end error.backtrace.shift(count) end
#handle(*error_classes, severity: :warning, context: {}, fallback: nil, source: DEFAULT_SOURCE)
Evaluates the given block, reporting and swallowing any unhandled error. If no error is raised, returns the return value of the block. Otherwise, returns the result of fallback.call
, or nil
if fallback
is not specified.
# Will report a TypeError to all subscribers and return nil.
Rails.error.handle do
1 + '1'
end
Can be restricted to handle only specific error classes:
= Rails.error.handle(Redis::BaseError) { redis.get("tags") }
Options
-
:severity
- This value is passed along to subscribers to indicate how important the error report is. Can be:error
,:warning
, or:info
. Defaults to:warning
. -
:context
- Extra information that is passed along to subscribers. For example:Rails.error.handle(context: { section: "admin" }) do # ... end
-
:fallback
- A callable that provideshandle
‘s return value when an unhandled error is raised. For example:user = Rails.error.handle(fallback: -> { User.anonymous }) do User.find_by(params) end
-
:source
- This value is passed along to subscribers to indicate the source of the error. Subscribers can use this value to ignore certain errors. Defaults to"application"
.
# File 'activesupport/lib/active_support/error_reporter.rb', line 78
def handle(*error_classes, severity: :warning, context: {}, fallback: nil, source: DEFAULT_SOURCE) error_classes = DEFAULT_RESCUE if error_classes.empty? yield rescue *error_classes => error report(error, handled: true, severity: severity, context: context, source: source) fallback.call if fallback end
#record(*error_classes, severity: :error, context: {}, source: DEFAULT_SOURCE)
Evaluates the given block, reporting and re-raising any unhandled error. If no error is raised, returns the return value of the block.
# Will report a TypeError to all subscribers and re-raise it.
Rails.error.record do
1 + '1'
end
Can be restricted to handle only specific error classes:
= Rails.error.record(Redis::BaseError) { redis.get("tags") }
Options
-
:severity
- This value is passed along to subscribers to indicate how important the error report is. Can be:error
,:warning
, or:info
. Defaults to:error
. -
:context
- Extra information that is passed along to subscribers. For example:Rails.error.record(context: { section: "admin" }) do # ... end
-
:source
- This value is passed along to subscribers to indicate the source of the error. Subscribers can use this value to ignore certain errors. Defaults to"application"
.
# File 'activesupport/lib/active_support/error_reporter.rb', line 114
def record(*error_classes, severity: :error, context: {}, source: DEFAULT_SOURCE) error_classes = DEFAULT_RESCUE if error_classes.empty? yield rescue *error_classes => error report(error, handled: false, severity: severity, context: context, source: source) raise end
#report(error, handled: true, severity: handled ? :warning : :error, context: {}, source: DEFAULT_SOURCE)
# File 'activesupport/lib/active_support/error_reporter.rb', line 210
def report(error, handled: true, severity: handled ? :warning : :error, context: {}, source: DEFAULT_SOURCE) return if error.instance_variable_defined?(:@__rails_error_reported) ensure_backtrace(error) unless SEVERITIES.include?(severity) raise ArgumentError, "severity must be one of #{SEVERITIES.map(&:inspect).join(", ")}, got: #{severity.inspect}" end full_context = ActiveSupport::ExecutionContext.to_h.merge(context) disabled_subscribers = ActiveSupport::IsolatedExecutionState[self] @subscribers.each do |subscriber| unless disabled_subscribers&.any? { |s| s === subscriber } subscriber.report(error, handled: handled, severity: severity, context: full_context, source: source) end rescue => subscriber_error if logger logger.fatal( "Error subscriber raised an error: #{subscriber_error.} (#{subscriber_error.class})\n" + subscriber_error.backtrace.join("\n") ) else raise end end unless error.frozen? error.instance_variable_set(:@__rails_error_reported, true) end nil end
#set_context
# File 'activesupport/lib/active_support/error_reporter.rb', line 201
def set_context(...) ActiveSupport::ExecutionContext.set(...) end
#subscribe(subscriber)
# File 'activesupport/lib/active_support/error_reporter.rb', line 161
def subscribe(subscriber) unless subscriber.respond_to?(:report) raise ArgumentError, "Error subscribers must respond to #report" end @subscribers << subscriber end
#unexpected(error, severity: :warning, context: {}, source: DEFAULT_SOURCE)
Either report the given error when in production, or raise it when in development or test.
When called in production, after the error is reported, this method will return nil and execution will continue.
When called in development, the original error is wrapped in a different error class to ensure it’s not being rescued higher in the stack and will be surfaced to the developer.
This method is intended for reporting violated assertions about preconditions, or similar cases that can and should be gracefully handled in production, but that aren’t supposed to happen.
The error can be either an exception instance or a ::String
.
example:
def edit
if published?
Rails.error.unexpected("[BUG] Attempting to edit a published article, that shouldn't be possible")
return false
end
# ...
end
# File 'activesupport/lib/active_support/error_reporter.rb', line 145
def unexpected(error, severity: :warning, context: {}, source: DEFAULT_SOURCE) error = RuntimeError.new(error) if error.is_a?(String) if @debug_mode ensure_backtrace(error) raise UnexpectedError, "#{error.class.name}: #{error.}", error.backtrace, cause: error else report(error, handled: true, severity: severity, context: context, source: source) end end
#unsubscribe(subscriber)
# File 'activesupport/lib/active_support/error_reporter.rb', line 176
def unsubscribe(subscriber) @subscribers.delete_if { |s| subscriber === s } end