sentry-ruby 4.0.1 → 4.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 732989200a2cbf0a935c386cf84037d655332953ea2fef828099fbf68b756ab9
-  data.tar.gz: 4aecc66958496eede273d4cc4b2e3861e0ce7eb3cf769912a4a6675efeba693e
+  metadata.gz: a99aa0cd23f84ac85fe92aeff13f70aabb29f8b4f7e5239b48806f66e9af5376
+  data.tar.gz: bb5c2b32b2086f913fd6e8f55566b9a6bb6331aae414922e65696e4eb87457fe
 SHA512:
-  metadata.gz: 798be41100ec3c8eb09039f9432df02fd0de323427fd0d8bf6d9ced8f7b39d420e972c6006bcb4490002e32f03acfad2311b8ddab826c6927bd53b2a7316c7cb
-  data.tar.gz: 78cc7ec6d5c1a7f6603f9f2e4917b26e12ad5b13c0387a00645282acf8c910518c4132c171e2c9a8311f11e82afa3eb0454d2102bf48abd4c44d6625fd4ce4cf
+  metadata.gz: 70c330fa68f5a42588f7dfa815b7e2276b508de5c3a606c058d37afff5ef3b50ba3c3071cbb51356fd859c97ca19ffdd95a986931e4f54b752ad2b11b352feae
+  data.tar.gz: 0d0dde39080876a24f52256c503778226ae53bf0a668ba55503ae6c76bb4d0731b1cb7c775029fd2ec258c5e4eacbcb679272d7dd9495831ac1f6b77d56124ff

data/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 4.1.4
+
+- Fix headers serialization for sentry-ruby [#1197](https://github.com/getsentry/sentry-ruby/pull/1197) (by @moofkit)
+- Support capturing "sentry-trace" header from the middleware [#1205](https://github.com/getsentry/sentry-ruby/pull/1205)
+- Document public APIs on the Sentry module [#1208](https://github.com/getsentry/sentry-ruby/pull/1208)
+- Check the argument type of capture_exception and capture_event helpers [#1209](https://github.com/getsentry/sentry-ruby/pull/1209)
+
+## 4.1.3
+
+- rm reference to old constant (from Rails v2.2) [#1184](https://github.com/getsentry/sentry-ruby/pull/1184)
+- Use copied env in events [#1186](https://github.com/getsentry/sentry-ruby/pull/1186)
+  - Fixes [#1183](https://github.com/getsentry/sentry-ruby/issues/1183)
+- Refactor RequestInterface [#1187](https://github.com/getsentry/sentry-ruby/pull/1187)
+- Supply event hint to async callback when possible [#1189](https://github.com/getsentry/sentry-ruby/pull/1189)
+  - Fixes [#1188](https://github.com/getsentry/sentry-ruby/issues/1188)
+- Refactor stacktrace parsing and increase test coverage [#1190](https://github.com/getsentry/sentry-ruby/pull/1190)
+- Sentry.send_event should also take a hint [#1192](https://github.com/getsentry/sentry-ruby/pull/1192)
+
+## 4.1.2
+
+- before_send callback shouldn't be applied to transaction events [#1167](https://github.com/getsentry/sentry-ruby/pull/1167)
+- Transaction improvements [#1170](https://github.com/getsentry/sentry-ruby/pull/1170)
+- Support Ruby 3 [#1172](https://github.com/getsentry/sentry-ruby/pull/1172)
+- Add Integrable module [#1177](https://github.com/getsentry/sentry-ruby/pull/1177)
+
+## 4.1.1
+
+- Fix NoMethodError when sending is not allowed [#1161](https://github.com/getsentry/sentry-ruby/pull/1161)
+- Add notification for users who still use deprecated middlewares [#1160](https://github.com/getsentry/sentry-ruby/pull/1160)
+- Improve top-level api safety [#1162](https://github.com/getsentry/sentry-ruby/pull/1162)
+
+## 4.1.0
+
+- Separate rack integration [#1138](https://github.com/getsentry/sentry-ruby/pull/1138)
+  - Fixes [#1136](https://github.com/getsentry/sentry-ruby/pull/1136)
+- Fix event sampling [#1144](https://github.com/getsentry/sentry-ruby/pull/1144)
+- Merge & rename 2 Rack middlewares [#1147](https://github.com/getsentry/sentry-ruby/pull/1147)
+  - Fixes [#1153](https://github.com/getsentry/sentry-ruby/pull/1153)
+  - Removed `Sentry::Rack::Tracing` middleware and renamed `Sentry::Rack::CaptureException` to `Sentry::Rack::CaptureExceptions`.
+- Deep-copy spans [#1148](https://github.com/getsentry/sentry-ruby/pull/1148)
+- Move span recorder related code from Span to Transaction [#1149](https://github.com/getsentry/sentry-ruby/pull/1149)
+- Check SDK initialization before running integrations [#1151](https://github.com/getsentry/sentry-ruby/pull/1151)
+  - Fixes [#1145](https://github.com/getsentry/sentry-ruby/pull/1145)
+- Refactor transport [#1154](https://github.com/getsentry/sentry-ruby/pull/1154)
+- Implement non-blocking event sending [#1155](https://github.com/getsentry/sentry-ruby/pull/1155)
+  - Added `background_worker_threads` configuration option.
+
+### Noticeable Changes
+
+#### Middleware Changes
+
+`Sentry::Rack::Tracing` is now removed. And `Sentry::Rack::CaptureException` has been renamed to `Sentry::Rack::CaptureExceptions`.
+
+#### Events Are Sent Asynchronously
+
+`sentry-ruby` now sends events asynchronously by default. The functionality works like this: 
+
+1. When the SDK is initialized, a `Sentry::BackgroundWorker` will be initialized too.
+2. When an event is passed to `Client#capture_event`, instead of sending it directly with `Client#send_event`, we'll let the worker do it.
+3. The worker will have a number of threads. And the one of the idle threads will pick the job and call `Client#send_event`.
+    - If all the threads are busy, new jobs will be put into a queue, which has a limit of 30.
+    - If the queue size is exceeded, new events will be dropped.
+
+However, if you still prefer to use your own async approach, that's totally fine. If you have `config.async` set, the worker won't initialize a thread pool and won't be used either.
+
+This functionality also introduces a new `background_worker_threads` config option. It allows you to decide how many threads should the worker hold. By default, the value will be the number of the processors your machine has. For example, if your machine has 4 processors, the value would be 4.
+
+Of course, you can always override the value to fit your use cases, like
+
+```ruby
+config.background_worker_threads = 5 # the worker will have 5 threads for sending events
+```
+
+You can also disable this new non-blocking behaviour by giving a `0` value:
+
+```ruby
+config.background_worker_threads = 0 # all events will be sent synchronously
+```
+
 ## 4.0.1
 
 - Add rake integration: [1137](https://github.com/getsentry/sentry-ruby/pull/1137)

data/Gemfile

@@ -5,10 +5,10 @@ gemspec
 
 gem "rake", "~> 12.0"
 gem "rspec", "~> 3.0"
-gem "codecov"
+gem "codecov", "0.2.12"
 
 gem "pry"
-gem "rack"
+gem "rack" unless ENV["WITHOUT_RACK"] == "1"
 
 gem "benchmark-ips"
 gem "benchmark_driver"

data/README.md

@@ -94,7 +94,7 @@ Sentry.init do |config|
 end
 ```
 
-To lean more about performance monitoring, please visit the [official documentation](https://docs.sentry.io/platforms/ruby/performance).
+To learn more about performance monitoring, please visit the [official documentation](https://docs.sentry.io/platforms/ruby/performance).
 
 ### Usage
 
@@ -115,8 +115,7 @@ Sentry.init do |config|
   end
 end
 
-use Sentry::Rack::Tracing # this needs to be placed first
-use Sentry::Rack::CaptureException
+use Sentry::Rack::CaptureExceptions
 ```
 
 Otherwise, Sentry you can always use the capture helpers manually
@@ -140,13 +139,13 @@ We also provide integrations with popular frameworks/libraries with the related
 
 You're all set - but there's a few more settings you may want to know about too!
 
-#### async
+#### Blocking v.s. Non-blocking
 
-When an error or message occurs, the notification is immediately sent to Sentry. Sentry can be configured to send asynchronously:
+**Before version 4.1.0**, `sentry-ruby` sends every event immediately. But it can be configured to send asynchronously:
 
 ```ruby
-config.async = lambda { |event|
-  Thread.new { Sentry.send_event(event) }
+config.async = lambda { |event, hint|
+  Thread.new { Sentry.send_event(event, hint) }
 }
 ```
 
@@ -155,17 +154,52 @@ Using a thread to send events will be adequate for truly parallel Ruby platforms
 Note that the naive example implementation has a major drawback - it can create an infinite number of threads. We recommend creating a background job, using your background job processor, that will send Sentry notifications in the background.
 
 ```ruby
-config.async = lambda { |event| SentryJob.perform_later(event) }
+config.async = lambda { |event, hint| SentryJob.perform_later(event, hint) }
 
 class SentryJob < ActiveJob::Base
   queue_as :default
 
-  def perform(event)
-    Sentry.send_event(event)
+  def perform(event, hint)
+    Sentry.send_event(event, hint)
   end
 end
 ```
 
+
+**After version 4.1.0**, `sentry-ruby` sends events asynchronously by default. The functionality works like this: 
+
+1. When the SDK is initialized, a `Sentry::BackgroundWorker` will be initialized too.
+2. When an event is passed to `Client#capture_event`, instead of sending it directly with `Client#send_event`, we'll let the worker do it.
+3. The worker will have a number of threads. And the one of the idle threads will pick the job and call `Client#send_event`.
+  - If all the threads are busy, new jobs will be put into a queue, which has a limit of 30.
+  - If the queue size is exceeded, new events will be dropped.
+
+However, if you still prefer to use your own async approach, that's totally fine. If you have `config.async` set, the worker won't initialize a thread pool and won't be used either.
+
+##### About `Sentry::BackgroundWorker`
+
+- The worker is built on top of the [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) gem's [ThreadPoolExecutor](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ThreadPoolExecutor.html), which is also used by Rails ActiveJob's async adapter. This should minimize the risk of messing up client applications with our own thread pool implementaion.
+
+This functionality also introduces a new `background_worker_threads` config option. It allows you to decide how many threads should the worker hold. By default, the value will be the number of the processors your machine has. For example, if your machine has 4 processors, the value would be 4.
+
+Of course, you can always override the value to fit your use cases, like
+
+```ruby
+config.background_worker_threads = 5 # the worker will have 5 threads for sending events
+```
+
+You can also disable this new non-blocking behaviour by giving a `0` value:
+
+```ruby
+config.background_worker_threads = 0 # all events will be sent synchronously
+```
+
+If you want to send a particular event immediately, you can use event hints to do it:
+
+```ruby
+Sentry.capture_message("send me now!", hint: { background: false })
+```
+
 #### Contexts
 
 In sentry-ruby, every event will inherit their contextual data from the current scope. So you can enrich the event's data by configuring the current scope like:
@@ -191,7 +225,6 @@ Or use top-level setters
 Sentry.set_user(id: 1, email: "test@example.com")
 Sentry.set_tags(tag_1: "foo", tag_2: "bar")
 Sentry.set_extras(order_number: 1234, tickets_count: 4)
-
 ```
 
 Or build up a temporary scope for local information:
@@ -222,3 +255,4 @@ Sentry.capture_exception(exception, tags: {foo: "bar"})
 * [Bug Tracker](https://github.com/getsentry/sentry-ruby/issues)
 * [Forum](https://forum.sentry.io/)
 - [Discord](https://discord.gg/ez5KZN7)
+

data/lib/sentry-ruby.rb

@@ -1,7 +1,9 @@
 require "forwardable"
+require "time"
 
 require "sentry/version"
 require "sentry/core_ext/object/deep_dup"
+require "sentry/utils/argument_checking_helper"
 require "sentry/configuration"
 require "sentry/logger"
 require "sentry/event"
@@ -9,7 +11,7 @@ require "sentry/transaction_event"
 require "sentry/span"
 require "sentry/transaction"
 require "sentry/hub"
-require "sentry/rack"
+require "sentry/background_worker"
 
 def safely_require(lib)
   begin
@@ -19,6 +21,7 @@ def safely_require(lib)
 end
 
 safely_require "sentry/rake"
+safely_require "sentry/rack"
 
 module Sentry
   class Error < StandardError
@@ -38,11 +41,27 @@ module Sentry
     Time.now.utc
   end
 
+  class << self
+    # Returns a hash that contains all the integrations that have been registered to the main SDK.
+    def integrations
+      @integrations ||= {}
+    end
+
+    # Registers the SDK integration with its name and version.
+    def register_integration(name, version)
+      meta = { name: "sentry.ruby.#{name}", version: version }.freeze
+      integrations[name.to_s] = meta
+    end
+  end
+
   class << self
     extend Forwardable
 
+    def_delegators :get_current_client, :configuration, :send_event
     def_delegators :get_current_scope, :set_tags, :set_extras, :set_user
 
+    attr_accessor :background_worker
+
     def init(&block)
       config = Configuration.new
       yield(config)
@@ -51,28 +70,22 @@ module Sentry
       hub = Hub.new(client, scope)
       Thread.current[THREAD_LOCAL] = hub
       @main_hub = hub
+      @background_worker = Sentry::BackgroundWorker.new(config)
     end
 
+    # Returns the main thread's active hub.
     def get_main_hub
       @main_hub
     end
 
-    def logger
-      configuration.logger
-    end
-
-    def add_breadcrumb(breadcrumb, &block)
-      get_current_scope.breadcrumbs.record(breadcrumb, &block)
-    end
-
-    def configuration
-      get_current_client.configuration
-    end
-
-    def get_current_client
-      get_current_hub.current_client
+    # Takes an instance of Sentry::Breadcrumb and stores it to the current active scope.
+    def add_breadcrumb(breadcrumb)
+      get_current_scope.breadcrumbs.record(breadcrumb)
     end
 
+    # Returns the current active hub.
+    # If the current thread doesn't have an active hub, it will clone the main thread's active hub,
+    # stores it in the current thread, and then returns it.
     def get_current_hub
       # we need to assign a hub to the current thread if it doesn't have one yet
       #
@@ -82,44 +95,81 @@ module Sentry
       Thread.current[THREAD_LOCAL] || clone_hub_to_current_thread
     end
 
-    def clone_hub_to_current_thread
-      Thread.current[THREAD_LOCAL] = get_main_hub.clone
+    # Returns the current active client.
+    def get_current_client
+      get_current_hub&.current_client
     end
 
+    # Returns the current active scope.
     def get_current_scope
-      get_current_hub.current_scope
+      get_current_hub&.current_scope
     end
 
-    def with_scope(&block)
-      get_current_hub.with_scope(&block)
+    # Clones the main thread's active hub and stores it to the current thread.
+    def clone_hub_to_current_thread
+      Thread.current[THREAD_LOCAL] = get_main_hub.clone
     end
 
+    # Takes a block and yields the current active scope.
+    #
+    # ```ruby
+    # Sentry.configure_scope do |scope|
+    #   scope.set_tags(foo: "bar")
+    # end
+    #
+    # Sentry.capture_message("test message") # this event will have tags { foo: "bar" }
+    # ```
+    #
     def configure_scope(&block)
-      get_current_hub.configure_scope(&block)
-    end
-
-    def send_event(event)
-      get_current_client.send_event(event)
-    end
-
-    def capture_event(event)
-      get_current_hub.capture_event(event)
+      get_current_hub&.configure_scope(&block)
+    end
+
+    # Takes a block and yields a temporary scope.
+    # The temporary scope will inherit all the attributes from the current active scope and replace it to be the active
+    # scope inside the block. For example:
+    #
+    # ```ruby
+    # Sentry.configure_scope do |scope|
+    #   scope.set_tags(foo: "bar")
+    # end
+    #
+    # Sentry.capture_message("test message") # this event will have tags { foo: "bar" }
+    #
+    # Sentry.with_scope do |temp_scope|
+    #   temp_scope.set_tags(foo: "baz")
+    #   Sentry.capture_message("test message 2") # this event will have tags { foo: "baz" }
+    # end
+    #
+    # Sentry.capture_message("test message 3") # this event will have tags { foo: "bar" }
+    # ```
+    #
+    def with_scope(&block)
+      get_current_hub&.with_scope(&block)
     end
 
+    # Takes an exception and reports it to Sentry via the currently active hub.
     def capture_exception(exception, **options, &block)
-      get_current_hub.capture_exception(exception, **options, &block)
+      get_current_hub&.capture_exception(exception, **options, &block)
     end
 
+    # Takes a message string and reports it to Sentry via the currently active hub.
     def capture_message(message, **options, &block)
-      get_current_hub.capture_message(message, **options, &block)
+      get_current_hub&.capture_message(message, **options, &block)
     end
 
+    # Takes an instance of Sentry::Event and dispatches it to the currently active hub.
+    def capture_event(event)
+      get_current_hub&.capture_event(event)
+    end
+
+    # Takes or initializes a new Sentry::Transaction and makes a sampling decision for it.
     def start_transaction(**options)
-      get_current_hub.start_transaction(**options)
+      get_current_hub&.start_transaction(**options)
     end
 
+    # Returns the id of the lastly reported Sentry::Event.
     def last_event_id
-      get_current_hub.last_event_id
+      get_current_hub&.last_event_id
     end
 
     def sys_command(command)
@@ -128,5 +178,13 @@ module Sentry
 
       result.strip
     end
+
+    def initialized?
+      !!@main_hub
+    end
+
+    def logger
+      configuration.logger
+    end
   end
 end

data/lib/sentry/background_worker.rb

@@ -0,0 +1,37 @@
+require "concurrent/executor/thread_pool_executor"
+require "concurrent/executor/immediate_executor"
+
+module Sentry
+  class BackgroundWorker
+    attr_reader :max_queue, :number_of_threads
+
+    def initialize(configuration)
+      @max_queue = 30
+      @number_of_threads = configuration.background_worker_threads
+
+      @executor =
+        if configuration.async
+          configuration.logger.debug(LOGGER_PROGNAME) { "config.async is set, BackgroundWorker is disabled" }
+          Concurrent::ImmediateExecutor.new
+        elsif @number_of_threads == 0
+          configuration.logger.debug(LOGGER_PROGNAME) { "config.background_worker_threads is set to 0, all events will be sent synchronously" }
+          Concurrent::ImmediateExecutor.new
+        else
+          configuration.logger.debug(LOGGER_PROGNAME) { "initialized a background worker with #{@number_of_threads} threads" }
+
+          Concurrent::ThreadPoolExecutor.new(
+            min_threads: 0,
+            max_threads: @number_of_threads,
+            max_queue: @max_queue,
+            fallback_policy: :discard
+          )
+        end
+    end
+
+    def perform(&block)
+      @executor.post do
+        block.call
+      end
+    end
+  end
+end