Add Integrable module (#1177)

* Add Sentry::Integrable module to simplify integration setup

* Allow subclass to override middleware's exception capturing method

* Use the new Integrable module in sentry-rails

* Use the new Integrable module in sentry-sidekiq

* Create EXTENSION.md

Author: st0012

EXTENSION.md

@@ -0,0 +1,51 @@
+## What's an extension?
+
+An extension is a gem built on top of the core Ruby SDK (`sentry-ruby`) that provides additional functionality or integration support to the users. For example, `sentry-rails` and `sentry-sidekiq` are SDK extensions that offer integration support with specific libraries. 
+
+## Sentry::Integrable
+
+You can write extensions for `sentry-ruby` any way you want to. But if you're going to build an extension for integration support, `sentry-ruby` provides a module called `Sentry::Integrable` that will save you some work.
+
+### Usage
+
+Let me use `sentry-rails` as our example.
+
+#### Register the extension
+
+```ruby
+require "sentry-ruby"
+
+# the integrable module needs to be required separately
+require "sentry/integrable" 
+
+module Sentry
+  # the module/class of the extension should be defined under the Sentry namespace
+  module Rails 
+    
+    # extend the module
+    extend Integrable 
+    
+    # use the register_integration method to register your extension to the SDK core
+    register_integration name: "rails", version: Sentry::Rails::VERSION
+  end
+end
+```
+
+Once the extension is registered, it will do 2 things for you:
+
+1. It'll generate `.capture_exception` and `.capture_message` methods for your extension. In our example, they'll be `Sentry::Rails.capture_exception` and `Sentry::Rails.capture_message`.
+2. It'll also generate the SDK meta for the extension, which is `{name: "sentry.ruby.rails", version: Sentry::Rails::VERSION}` in this case.
+
+#### Use the generated helpers
+
+All the integration-level exception/message should be captured via the newly generated helpers in the extension gem. This is because:
+
+- Those helpers will inject `{ integration: "integration_name" }` to the event hints. So you or the users can later identify each event's source in the `before_send` callback.
+- Events created from those helpers will have the integration meta as their SDK information.
+- In the future, we might also introduce more advanced integration-based features. And those features will rely on these helpers.
+
+### Future plan
+
+- Methods like `configure_integration` for generating integration-level config options, like `config.integration_name.option_name`.
+- Support integration-specific excluded exceptions list.
+

sentry-rails/lib/sentry/rails.rb

@@ -1,14 +1,12 @@
 require "sentry-ruby"
+require "sentry/integrable"
 require "sentry/rails/configuration"
 require "sentry/rails/railtie"
 require "sentry/rails/tracing"
 
 module Sentry
   module Rails
-    META = { "name" => "sentry.ruby.rails", "version" => Sentry::Rails::VERSION }.freeze
-  end
-
-  def self.sdk_meta
-    Sentry::Rails::META
+    extend Integrable
+    register_integration name: "rails", version: Sentry::Rails::VERSION
   end
 end

sentry-rails/lib/sentry/rails/active_job.rb

@@ -26,7 +26,7 @@ def capture_and_reraise_with_sentry(job, block)
         rescue_handler_result = rescue_with_handler(e)
         return rescue_handler_result if rescue_handler_result
 
-        Sentry.capture_exception(e, :extra => sentry_context(job))
+        Sentry::Rails.capture_exception(e, extra: sentry_context(job))
         raise e
       end
 

sentry-rails/lib/sentry/rails/capture_exceptions.rb

@@ -1,13 +1,19 @@
 module Sentry
   module Rails
     class CaptureExceptions < Sentry::Rack::CaptureExceptions
+      private
+
       def collect_exception(env)
         super || env["action_dispatch.exception"] || env["sentry.rescued_exception"]
       end
 
       def transaction_op
         "rails.request".freeze
       end
+
+      def capture_exception(exception)
+        Sentry::Rails.capture_exception(exception)
+      end
     end
   end
 end

sentry-rails/lib/sentry/rails/controller_methods.rb

@@ -3,13 +3,13 @@ module Rails
     module ControllerMethods
       def capture_message(message, options = {})
         with_request_scope do
-          Sentry.capture_message(message, **options)
+          Sentry::Rails.capture_message(message, **options)
         end
       end
 
       def capture_exception(exception, options = {})
         with_request_scope do
-          Sentry.capture_exception(exception, **options)
+          Sentry::Rails.capture_exception(exception, **options)
         end
       end
 

sentry-rails/lib/sentry/rails/overrides/streaming_reporter.rb

@@ -3,7 +3,7 @@ module Rails
     module Overrides
       module StreamingReporter
         def log_error(exception)
-          Sentry.capture_exception(exception)
+          Sentry::Rails.capture_exception(exception)
           super
         end
       end
@@ -14,7 +14,7 @@ def self.included(base)
         end
 
         def log_error_with_raven(exception)
-          Sentry.capture_exception(exception)
+          Sentry::Rails.capture_exception(exception)
           log_error_without_raven(exception)
         end
       end

sentry-rails/spec/sentry/rails/event_spec.rb

@@ -10,9 +10,9 @@
   end
 
   it "sets right SDK information" do
-    event_hash = Sentry.capture_message("foo").to_hash
+    event_hash = Sentry::Rails.capture_message("foo").to_hash
 
-    expect(event_hash[:sdk]).to eq("name" => "sentry.ruby.rails", "version" => Sentry::Rails::VERSION)
+    expect(event_hash[:sdk]).to eq(name: "sentry.ruby.rails", version: Sentry::Rails::VERSION)
   end
 
   context 'with an application stacktrace' do
@@ -29,7 +29,7 @@
       e
     end
 
-    let(:hash) { Sentry.capture_exception(exception).to_hash }
+    let(:hash) { Sentry::Rails.capture_exception(exception).to_hash }
 
     it 'marks in_app correctly' do
       frames = hash[:exception][:values][0][:stacktrace][:frames]

sentry-rails/spec/sentry/rails_spec.rb

@@ -87,6 +87,7 @@
 
       expect(event["exception"]["values"][0]["type"]).to eq("RuntimeError")
       expect(event["exception"]["values"][0]["value"]).to eq("An unhandled exception!")
+      expect(event["sdk"]).to eq("name" => "sentry.ruby.rails", "version" => Sentry::Rails::VERSION)
     end
 
     it "filters exception backtrace with custom BacktraceCleaner" do

sentry-ruby/lib/sentry-ruby.rb

@@ -40,6 +40,17 @@ def self.utc_now
     Time.now.utc
   end
 
+  class << self
+    def integrations
+      @integrations ||= {}
+    end
+
+    def register_integration(name, version)
+      meta = { name: "sentry.ruby.#{name}", version: version }.freeze
+      integrations[name.to_s] = meta
+    end
+  end
+
   class << self
     extend Forwardable
 

sentry-ruby/lib/sentry/client.rb

@@ -47,16 +47,18 @@ def capture_event(event, scope, hint = {})
       event
     end
 
-    def event_from_exception(exception)
+    def event_from_exception(exception, hint = {})
+      integration_meta = Sentry.integrations[hint[:integration]]
       return unless @configuration.exception_class_allowed?(exception)
 
-      Event.new(configuration: configuration).tap do |event|
+      Event.new(configuration: configuration, integration_meta: integration_meta).tap do |event|
         event.add_exception_interface(exception)
       end
     end
 
-    def event_from_message(message)
-      Event.new(configuration: configuration, message: message)
+    def event_from_message(message, hint = {})
+      integration_meta = Sentry.integrations[hint[:integration]]
+      Event.new(configuration: configuration, integration_meta: integration_meta, message: message)
     end
 
     def event_from_transaction(transaction)

sentry-ruby/lib/sentry/event.rb

@@ -20,15 +20,15 @@ class Event
     attr_accessor(*ATTRIBUTES)
     attr_reader :configuration, :request, :exception, :stacktrace
 
-    def initialize(configuration:, message: nil)
+    def initialize(configuration:, integration_meta: nil, message: nil)
       # this needs to go first because some setters rely on configuration
       @configuration = configuration
 
       # Set some simple default values
       @event_id      = SecureRandom.uuid.delete("-")
       @timestamp     = Sentry.utc_now.iso8601
       @platform      = :ruby
-      @sdk           = Sentry.sdk_meta
+      @sdk           = integration_meta || Sentry.sdk_meta
 
       @user          = {}
       @extra         = {}

sentry-ruby/lib/sentry/hub.rb

@@ -76,21 +76,21 @@ def start_transaction(transaction: nil, **options)
     def capture_exception(exception, **options, &block)
       return unless current_client
 
-      event = current_client.event_from_exception(exception)
+      options[:hint] ||= {}
+      options[:hint][:exception] = exception
+      event = current_client.event_from_exception(exception, options[:hint])
 
       return unless event
 
-      options[:hint] ||= {}
-      options[:hint] = options[:hint].merge(exception: exception)
       capture_event(event, **options, &block)
     end
 
     def capture_message(message, **options, &block)
       return unless current_client
 
       options[:hint] ||= {}
-      options[:hint] = options[:hint].merge(message: message)
-      event = current_client.event_from_message(message)
+      options[:hint][:message] = message
+      event = current_client.event_from_message(message, options[:hint])
       capture_event(event, **options, &block)
     end
 

sentry-ruby/lib/sentry/integrable.rb

@@ -0,0 +1,24 @@
+module Sentry
+  module Integrable
+    def register_integration(name:, version:)
+      Sentry.register_integration(name, version)
+      @integration_name = name
+    end
+
+    def integration_name
+      @integration_name
+    end
+
+    def capture_exception(exception, **options, &block)
+      options[:hint] ||= {}
+      options[:hint][:integration] = integration_name
+      Sentry.capture_exception(exception, **options, &block)
+    end
+
+    def capture_message(message, **options, &block)
+      options[:hint] ||= {}
+      options[:hint][:integration] = integration_name
+      Sentry.capture_message(message, **options, &block)
+    end
+  end
+end

sentry-ruby/lib/sentry/rack/capture_exceptions.rb

@@ -25,13 +25,13 @@ def call(env)
             finish_span(span, 500)
             raise # Don't capture Sentry errors
           rescue Exception => e
-            Sentry.capture_exception(e)
+            capture_exception(e)
             finish_span(span, 500)
             raise
           end
 
           exception = collect_exception(env)
-          Sentry.capture_exception(exception) if exception
+          capture_exception(exception) if exception
 
           finish_span(span, response[0])
 
@@ -49,6 +49,10 @@ def transaction_op
         "rack.request".freeze
       end
 
+      def capture_exception(exception)
+        Sentry.capture_exception(exception)
+      end
+
       def finish_span(span, status_code)
         span.set_http_status(status_code)
         span.finish

sentry-ruby/spec/sentry/integrable_spec.rb

@@ -0,0 +1,63 @@
+require "spec_helper"
+require "sentry/integrable"
+
+RSpec.describe Sentry::Integrable do
+  module Sentry
+    module FakeIntegration
+      extend Sentry::Integrable
+
+      register_integration name: "fake_integration", version: "0.1.0"
+    end
+  end
+
+  it "registers correct meta" do
+    meta = Sentry.integrations["fake_integration"]
+
+    expect(meta).to eq({ name: "sentry.ruby.fake_integration", version: "0.1.0" })
+  end
+
+  describe "helpers generation" do
+    before do
+      perform_basic_setup
+    end
+
+    let(:exception) { ZeroDivisionError.new("1/0") }
+    let(:message) { "test message" }
+
+    it "generates Sentry::FakeIntegration.capture_exception" do
+      hint = nil
+
+      Sentry.configuration.before_send = lambda do |event, h|
+        hint = h
+        event
+      end
+
+      Sentry::FakeIntegration.capture_exception(exception, hint: { additional_hint: "foo" })
+
+      expect(hint).to eq({ additional_hint: "foo", integration: "fake_integration", exception: exception })
+    end
+
+    it "generates Sentry::FakeIntegration.capture_exception" do
+      hint = nil
+
+      Sentry.configuration.before_send = lambda do |event, h|
+        hint = h
+        event
+      end
+
+      Sentry::FakeIntegration.capture_message(message, hint: { additional_hint: "foo" })
+
+      expect(hint).to eq({ additional_hint: "foo", integration: "fake_integration", message: message })
+    end
+
+    it "sets correct meta when the event is captured by integration helpers" do
+      event = Sentry::FakeIntegration.capture_message(message)
+      expect(event.sdk).to eq({ name: "sentry.ruby.fake_integration", version: "0.1.0" })
+    end
+
+    it "doesn't change the events captured by original helpers" do
+      event = Sentry.capture_message(message)
+      expect(event.sdk).to eq(Sentry.sdk_meta)
+    end
+  end
+end

sentry-sidekiq/lib/sentry-sidekiq.rb

@@ -1,17 +1,16 @@
 require "sidekiq"
 require "sentry-ruby"
+require "sentry/integrable"
 require "sentry/sidekiq/version"
 require "sentry/sidekiq/error_handler"
 require "sentry/sidekiq/sentry_context_middleware"
 # require "sentry/sidekiq/configuration"
 
 module Sentry
   module Sidekiq
-    META = { "name" => "sentry.ruby.sidekiq", "version" => Sentry::Sidekiq::VERSION }.freeze
-  end
+    extend Sentry::Integrable
 
-  def self.sdk_meta
-    Sentry::Sidekiq::META
+    register_integration name: "sidekiq", version: Sentry::Sidekiq::VERSION
   end
 end