Introduction

This PR introduces a new feature to capture local variables when an exception is raised. For example, given this script:

a = 1
b = 0
a / b #=> This would cause ZeroDivisionError

The captured exception will contain the value of local variable a and b.

Here are some screenshots:

From this SDK's demo application

From my company's application with a real error

This feature needs to be activated with the new capture_exception_frame_locals config option:

Sentry.init do |config|
  config.capture_exception_frame_locals = true # default is false
end

So if you don't want to use it, it won't affect your application.

Reason

It's the dream, isn't it 😉

Limitations & Caveats

• Currently, this feature only works within the Sentry::CaptureExceptions middleware. Background job support will come later.
• For exceptions raised from non-app paths, the frame will be folded and you need to see the locals from the Full stacktrace view.
• Locals can contain sensitive data (e.g. user record's attributes).
  • Rails 6.0+ users can avoid this by configuring Rails.application.config.filter_parameters.
• It only captures locals when an exception is first raised. All local variables from later rescuing/re-raising will not be recorded.

Performance Impact

TL;DR:

• If you don't activate the feature, it doesn't cause extra overhead.
• In the context of web applications, the impact of this feature is ignorable. (See below)

Benchmark (with Ruby 2.7.4)

require 'benchmark/ips'

def raise_n_exceptions(n, with_sleep: false)
  n.times do |i|
    raise "exception: #{i}" rescue nil
  end
  sleep(0.05) if with_sleep
end

def raise_n_exceptions_with_tracepoint(n, with_sleep: false)
  TracePoint.new(:raise) do |tp|
    exception = tp.raised_exception

    next if exception.instance_variable_get(:@sentry_locals)

    locals = tp.binding.local_variables.each_with_object({}) do |local, result|
      result[local] = tp.binding.local_variable_get(local)
    end

    exception.instance_variable_set(:@sentry_locals, locals)
  end.enable do
    raise_n_exceptions(n, with_sleep: with_sleep)
  end
end

Benchmark.ips do |x|
  x.report("raise 50 exceptions") { raise_n_exceptions(50) }
  x.report("raise 50 exceptions with tracepoint") { raise_n_exceptions_with_tracepoint(50) }
  x.compare!
end

# simulate other workload with 50ms of sleep time
Benchmark.ips do |x|
  x.report("(with 50ms sleep) raise 50 exceptions") { raise_n_exceptions(50, with_sleep: true) }
  x.report("(with 50ms sleep) raise 50 exceptions with tracepoint") { raise_n_exceptions_with_tracepoint(50, with_sleep: true) }
  x.compare!
end

When the local-capturing TracePoint is enable, exception handling slows down significantly.

Warming up --------------------------------------
 raise 50 exceptions     1.919k i/100ms
raise 50 exceptions with tracepoint
                       537.000  i/100ms
Calculating -------------------------------------
 raise 50 exceptions     18.803k (± 2.1%) i/s -     94.031k
raise 50 exceptions with tracepoint
                          5.333k (± 3.8%) i/s -     26.850k

Comparison:
 raise 50 exceptions:    18803.0 i/s
raise 50 exceptions with tracepoint:     5332.8 i/s - 3.53x slower

However, our applications don't just raise exceptions and do nothing. So let's simulate some extra timespent on other stuff with sleep (just 50 ms):

Warming up --------------------------------------
(with 50ms sleep) raise 50 exceptions
                         1.000  i/100ms
(with 50ms sleep) raise 50 exceptions with tracepoint
                         1.000  i/100ms
Calculating -------------------------------------
(with 50ms sleep) raise 50 exceptions
                         19.032  (± 5.3%) i/s -     96.000
(with 50ms sleep) raise 50 exceptions with tracepoint
                         18.953  (± 5.3%) i/s -     95.000

Comparison:
(with 50ms sleep) raise 50 exceptions:       19.0 i/s
(with 50ms sleep) raise 50 exceptions with tracepoint:       19.0 i/s - same-ish: difference falls within error

Since Ruby's exception raising/rescuing are pretty fast, the extra overhead added by TracePoint isn't even observable in this case.

Future Development

If this approach is proved working, we can enhance it in 2 directions:

1. Add more information to the frame, e.g. instance variables.
2. Capture local variables for more frames.

The 2nd enhancement may be the most-desirable feature to add. However, its overhead may be significant because the SDK will need to walk through every frame for collecting local variables, and do that for every exception raised. So it's possible that we need to introduce it with extra configurations to reduce the overhead (e.g. only capture certain number of frames or certain exceptions).