[Errors] Centralized error reporting interface

[rsamoilov]

Description

Rage has multiple independent components that catch and log exceptions internally — controllers, background tasks, Cable connections, Cable channels, event subscribers, and SSE streams. Currently, there is no way to tell the framework where to forward these exceptions beyond the built-in logger.

In practice, most applications use an external error tracking service (e.g. Sentry, Bugsnag, Rollbar). Today, the only way to get Rage-caught exceptions into these services is to manually rescue errors in each component and forward them yourself. This is repetitive and easy to miss.

The goal of Rage::Errors is to provide a centralized hook that lets users tell Rage: "when you catch an exception, also report it here". This is not a general-purpose error reporting abstraction or a replacement for the error tracking service's SDK — it's a way for the framework to forward exceptions it already catches.

Proposed interface

Register one or more reporters — any object that responds to call:

# config/application.rb
Rage.configure do
  config.errors << SentryReporter.new
  config.errors << InternalMetricsReporter.new
end

Where a reporter looks like:

class SentryReporter
  def call(exception, context: {})
    Sentry.capture_exception(exception, extra: context)
  end
end

Users should also be able to report errors manually using the Rage::Errors interface:

Rage::Errors.report(exception)

Design considerations

These are open questions that should be addressed in the design proposal:

• Logging behavior when a reporter is set. The framework currently logs all caught exceptions. Should it continue to do so when a reporter is configured?
• Multiple reporters. The interface above supports multiple reporters. The implementation should iterate over all subscribers and call call on each. Consider what happens if one reporter raises an exception.
• Duplicate errors. Should the framework attempt to deduplicate errors before reporting?
• Reporting unraised exceptions. Rage::Errors.report(SomeError.new("...")) should work for manually created exceptions.
• Reporting interface Consider whether call should accept an optional severity/source argument.
• Integration points. Identify all the places in the codebase where Rage rescues exceptions (controllers, deferred tasks, Cable connections/channels, event subscribers, SSE streams) and ensure each one calls the reporting hook.

Before You Start

This issue requires a design proposal before implementation. Please open a discussion or comment on this issue with a high-level plan that outlines:

1. The public API (confirming or adjusting the interface above).
2. How reporters will be registered and invoked.
3. The list of integration points in the codebase where reporting will be added.
4. How the edge cases above will be handled.

PRs without prior design discussion are unlikely to be accepted.

Tips

• Search the codebase for rescue and Rage.logger.error to find all the places where Rage catches and logs exceptions — these are the integration points.
• Check the architecture doc that shows how Rage's core components interact with each other and outlines the design principles.
• For reference, see Rails' Rails.error API. Note that Rage::Errors has a different goal — it's not about reducing boilerplate or providing a standard reporting interface, it's about letting the framework forward exceptions it already catches.
• Feel free to ask any questions or request help in the comments below!

[Digvijay-x1]

Thanks for the feedback! I've revised the proposal according to your suggestions.

1. Public API

The user-facing API stays close to what you proposed:

# config/application.rb
Rage.configure do
  config.errors << SentryReporter.new
  config.errors << InternalMetricsReporter.new
end

Both reporter styles should be valid: a reporter who uses context and a simpler one who ignores it.

class SentryReporter
  def call(exception, context: {})
    Sentry.capture_exception(exception, extra: context)
  end
end

class SimpleReporter
  def call(exception)
    MyTracker.track(exception)
  end
end

Manual reporting:

Rage::Errors.report(exception)
Rage::Errors.report(SomeError.new("something went wrong"), context: { user_id: 42 })

2. Registration and Invocation

Rage::Errors keeps existing exception classes and adds reporter registry + dispatch:

module Rage::Errors
  # .....existing...

  @reporters = []

  class << self
    def <<(reporter)
      raise ArgumentError, "reporter must respond to #call" unless reporter.respond_to?(:call)

      index = @reporters.length
      @reporters << reporter

      args = Rage::Internal.build_arguments(
        reporter.method(:call),
        { context: "context" }
      )

      # Generate a compiled dispatch method for this reporter
      # e.g. def __report_0(exception, context)
      #        @reporters[0].call(exception, context: context)
      #      end
      # OR:  def __report_0(exception, context)
      #        @reporters[0].call(exception)
      #      end
      class_eval <<~RUBY, __FILE__, __LINE__ + 1
        def __report_#{index}(exception, context)
          @reporters[#{index}].call(exception, #{args})
        end
      RUBY

      self
    end

    def report(exception, context: {})
      return if @reporters.empty?

      exception.set_backtrace(caller) unless exception.backtrace

      @reporters.length.times do |i|
        begin
          __send__(:"__report_#{i}", exception, context)
        rescue => e
          Rage.logger.error("Error reporter #{@reporters[i].class} failed: #{e.class} (#{e.message})")
        end
      end
    end
  end
end

Rage::Configuration#errors simply delegates:

class Rage::Configuration
  def errors
    Rage::Errors
  end
end

3. Integration Points

Add Rage::Errors.report(e) next to existing framework catch+log sites:

1. lib/rage/application.rb (Exception => 500)
2. lib/rage/middleware/fiber_wrapper.rb
3. lib/rage/cable/cable.rb (on_open, on_message, on_close, on_shutdown)
4. lib/rage/cable/channel.rb (periodic timer fiber)
5. lib/rage/cable/adapters/redis.rb (RedisClient::Error poll-loop recoverable path)
6. lib/rage/deferred/task.rb (__perform failures)
7. lib/rage/events/subscriber.rb (__call failures for non-deferred subscribers)
8. lib/rage/sse/application.rb (start_stream failures)

For BadRequest (400) in lib/rage/application.rb, not reporting by default — it's malformed client input, not an app crash.

4. Deferred Retry Semantics and Duplicate Prevention

Deferred subscribers already re-raise into the deferred task flow. To avoid duplicate reporting, report deferred-subscriber failures in Deferred::Task only (not in Subscriber#__call when deferred).

5. Scope Boundaries

• User rescue_from: do not report; those are intentionally handled in app code.
• Telemetry tracer rescues: skip (internal framework noise).

6. Open Questions

1. Logging behavior when a reporter is set — Keep existing Rage.logger.error behavior unchanged. Reporter dispatch is additive, not a replacement.
2. Multiple reporters and reporter failures — Support multiple reporters. Wrap each invocation in its own rescue so one broken reporter does not block the rest.
3. Duplicate errors — No global deduplication in v1. Only handle the known deferred subscriber/task overlap by reporting at the deferred task layer.
4. Reporting unraised exceptions — Rage::Errors.report(SomeError.new("...")) is supported. If no backtrace exists, attach one with exception.set_backtrace(caller).
5. Reporting interface — call(exception) or call(exception, context: {}). Use Rage::Internal::build_arguments.
6. Integration points — Hook reporting into all framework catch+log paths listed above.

[rsamoilov]

lib/rage/application.rb (Exception => 500), source: "rage.controller", handled: false

What's the mental model for handled in your design? It seems it's false for framework-level exceptions but true for user-level reports. This makes sense, but I wonder what the use case for this flag is. It's also drastically different from Rails where handled is essentially always true unless the error is handled by #record, which doesn't exist in our implementation.

source: "rage.cable.connection"

This is also different from Rails where, I think, the default source is application. What's the use case for the component-based sources?

accepts_keyword_context = params.any? { |type, name| (type == :key || type == :keyreq) && name == :context } ||
params.any? { |type, _| type == :keyrest }
raise ArgumentError, "reporter #call must accept context: keyword" unless accepts_keyword_context

It's a bit different from Rage's dynamic keyword args approach where both of the following reporters would be valid:

class ErrorReporter1
  def call(exception, context: {})
  end
end

class ErrorReporter2
  def call(exception)
  end
end

You would need to use Rage::Internal::build_arguments to achieve this behaviour.

[Digvijay-x1]

Thank you @rsamoilov, for the feedback. I have updated the proposal. Below are the reasons why I included them in the first place.

What's the mental model for handled in your design? It seems it's false for framework-level exceptions but true for user-level reports. This makes sense, but I wonder what the use case for this flag is. It's also drastically different from Rails where handled is essentially always true unless the error is handled by #record, which doesn't exist in our implementation.

Yes, I agree that the handled argument is different from both Rails and Sentry. The handled was answering "Will the framework automatically recover from this?" true if Rage caught an exception and tries to retry, and false if Rage caught an exception and failed. I added this to give the user a branching option.

class SentryReporter
  def call(exception, context: {})
    if context[:handled] == false
      Sentry.capture_exception(exception, level: :fatal)
    else
      Sentry.capture_exception(exception, level: :warning)
    end
  end
end

I am currently removing it because of its limited use cases ( only for deferred tasks).

This is also different from Rails where, I think, the default source is application. What's the use case for the component-based sources?

if we have multiple reporters, maybe we want to route errors differently based on where they come from. Cable errors go to one Slack channel, controller errors go to another. Or you want to filter noise, e.g., "don't alert me on Redis reconnection errors.

Although the exception class and backtrace already tell us where the error is coming from. I added sources as a nice-to-have option.

It's a bit different from Rage's dynamic keyword args approach where both of the following reporters would be valid:

I wasn't aware of it. Thanks for letting me know :)