Background worker fails with fiber-aware mutexes

[sentry-junior]

Processes that replace Ruby's mutex implementation with a fiber-aware mutex can fail when Sentry dispatches an event through its default background worker. The failure prevents the event from being sent and logs:

FiberError: attempt to resume a transferring fiber
em-synchrony (1.0.6) lib/em-synchrony/thread.rb:56:in `resume'
em-synchrony (1.0.6) lib/em-synchrony/thread.rb:56:in `block in unlock'

Root cause

Sentry::BackgroundWorker uses Concurrent::ThreadPoolExecutor. On CRuby, concurrent-ruby protects that executor with ::Mutex; a fiber-aware replacement can schedule Fiber#resume while the worker crosses thread/fiber execution contexts. em-synchrony's mutex unlock path resumes its next waiter through EM.next_tick, which matches the observed stack.

Stock em-synchrony exposes EM::Synchrony::Thread::Mutex separately rather than globally replacing ::Mutex; this occurs in applications or dependencies that apply that replacement.

Reproduction conditions

• EventMachine with em-synchrony 1.0.6
• A process where Thread::Mutex / ::Mutex is replaced with a fiber-aware implementation
• Sentry's default background worker enabled
• Sentry.capture_exception called from the EventMachine process

Workaround

Set config.background_worker_threads = 0 for affected processes. This uses Concurrent::ImmediateExecutor and sends from the calling execution context.

Related: #2596 tracks broader concurrent-ruby and thread integration work.

Requested by Simon Zhong.

--

View Junior Session [Sentry]

[linear-code]

RUBY-209

[sentry-junior]

Additional consideration: EM reactor throughput

For EventMachine processes that cannot afford blocking network I/O on the reactor, background_worker_threads = 0 alone is a poor fit: capture then runs send_event → default HTTPTransport (Net::HTTP) on the calling fiber and can stall the reactor.

A custom transport_class alone also does not fix this issue. Enqueue still goes through BackgroundWorker / Concurrent::ThreadPoolExecutor before transport runs, so the fiber-aware mutex failure can still occur.

Together they address different layers:

1. config.background_worker_threads = 0 — avoid the thread-pool / fiber-mutex clash
2. config.transport.transport_class = ... — make the actual HTTP send EM-cooperative (fiber-yielding IO such as em-http-request + EM::Synchrony.sync), not blocking Net::HTTP and not another Ruby thread pool

Sketch:

Sentry.init do |config|
  config.background_worker_threads = 0
  config.transport.transport_class = EmHttpTransport
end

class EmHttpTransport < Sentry::HTTPTransport
  def do_request(endpoint, headers, body)
    # EM-native request; return a response duck-type with #code / headers / body
  end
end

Notes:

• Override do_request / send_data; do not treat transport as a replacement for the background worker pool
• Prefer fiber-yielding IO over bare EM.next_tick fire-and-forget (the latter skips rate-limit / error handling expected from send_data)
• Envelope serialize + gzip still run inline on the capture path (CPU); the network wait is what must yield
• Other SDK paths still use Mutex / threads (Hub, session flusher, log/metric buffers). If FiberError persists after this combo, a global Thread::Mutex patch remains a deeper risk

This is app-side plumbing, not first-class EventMachine support.

[sl0thentr0py]

I've created a reproduction for this issue: getsentry/repro#55

It accepts a real SENTRY_DSN, uses Sentry's HTTP transport, and includes a SENTRY_BACKGROUND_THREADS=0 comparison for the workaround. Instructions are in the README.

🤖 Generated with Claude Code

[sl0thentr0py]

After investigating a bit, this is my recommendation:

Do NOT globally replace Ruby’s Mutex with EventMachine::Synchrony::Thread::Mutex.
Use the synchrony mutex only for application-level state that is accessed exclusively by fibers on the EventMachine reactor thread.
Keep Ruby’s normal Mutex for anything that can be accessed by Sentry, Concurrent::ThreadPoolExecutor, EM.defer, or other Ruby threads.

Recommended configuration:

   require "sentry-ruby"
   require "eventmachine"
   require "em-synchrony"

   # Do NOT replace Mutex globally:
   #
   # Object.const_set(:Mutex, EventMachine::Synchrony::thread::Mutex)

   Sentry.init do |config|
     # ...
   end

   EM.synchrony do
     # ONLY use the patched Mutex inside EM blocks that are sure to run on the main reactor thread:
     fiber_mutex = EventMachine::Synchrony::thread::Mutex.new

     fiber_mutex.synchronize do
       # Work performed by sibling EventMachine fibers
     end

     # This enqueues the event; Sentry's normal worker sends it from a
     # regular Ruby thread.
     Sentry.capture_exception(StandardError.new("example"))
   end

I verified in the linked repro PR that if they don't do the global patch, Sentry and EM don't interfere with each other and work correctly.

As an addendum, from the maintainer of em-synchrony himself:

 Doing too much juggling between EM and threads is, well... a recipe for pain and suffering.