Notify users when their custom options are discarded (#2303)

* Notify users when their custom options are discarded

It should save users from some debugging if we can tell them what options
they pass are discarded and how they can fix it.

The warning is only enabled at debug level so it should not be too noisy.

* Update changelog

CHANGELOG.md

@@ -6,6 +6,8 @@
 
   Rails users will be able to use `bin/rails generate sentry` to generate their `config/initializers/sentry.rb` file.
 
+- Notify users when their custom options are discarded ([#2303](https://github.com/getsentry/sentry-ruby/pull/2303))
+
 ### Bug Fixes
 
 - Don't throw error on arbitrary arguments being passed to `capture_event` options [#2301](https://github.com/getsentry/sentry-ruby/pull/2301)

sentry-ruby/lib/sentry/hub.rb

@@ -193,7 +193,12 @@ def capture_event(event, **options, &block)
       elsif custom_scope = options[:scope]
         scope.update_from_scope(custom_scope)
       elsif !options.empty?
-        scope.update_from_options(**options)
+        unsupported_option_keys = scope.update_from_options(**options)
+
+        configuration.log_debug <<~MSG
+          Options #{unsupported_option_keys} are not supported and will not be applied to the event.
+          You may want to set them under the `extra` option.
+        MSG
       end
 
       event = current_client.capture_event(event, scope, hint)

sentry-ruby/lib/sentry/scope.rb

@@ -128,7 +128,7 @@ def update_from_scope(scope)
     # @param user [Hash]
     # @param level [String, Symbol]
     # @param fingerprint [Array]
-    # @return [void]
+    # @return [Array]
     def update_from_options(
       contexts: nil,
       extra: nil,
@@ -144,6 +144,9 @@ def update_from_options(
       self.user = user if user
       self.level = level if level
       self.fingerprint = fingerprint if fingerprint
+
+      # Returns unsupported option keys so we can notify users.
+      options.keys
     end
 
     # Sets the scope's rack_env attribute.

sentry-ruby/spec/sentry/hub_spec.rb

@@ -342,6 +342,14 @@
       end
     end
 
+    it "reminds users about unsupported options" do
+      expect do
+        subject.capture_event(event, unsupported: true)
+      end.not_to raise_error
+
+      expect(string_io.string).to include("Options [:unsupported] are not supported and will not be applied to the event.")
+    end
+
     context "when event is a transaction" do
       it "transaction.set_context merges and takes precedence over scope.set_context" do
         scope.set_context(:foo, { val: 42 })

sentry-ruby/spec/sentry/scope_spec.rb

@@ -339,7 +339,7 @@
 
   describe '#update_from_options' do
     it 'updates data from arguments' do
-      subject.update_from_options(
+      result = subject.update_from_options(
         contexts: { context: 1 },
         extra: { foo: 42 },
         tags: { tag: 2 },
@@ -354,12 +354,12 @@
       expect(subject.user).to eq({ name: 'jane' })
       expect(subject.level).to eq(:info)
       expect(subject.fingerprint).to eq('ABCD')
+      expect(result).to eq([])
     end
 
-    it 'does not throw when arbitrary options passed' do
-      expect do
-        subject.update_from_options(foo: 42)
-      end.not_to raise_error
+    it 'returns unsupported option keys' do
+      result = subject.update_from_options(foo: 42, bar: 43)
+      expect(result).to eq([:foo, :bar])
     end
   end
 end