Soft-deprecate Sentry.EventFilter (#608)

Author: whatyouhide

CHANGELOG.md

@@ -21,6 +21,10 @@
 - Make the `Sentry.HTTPClient.child_spec/0` callback optional
 - Add `:all` as a possible value of the `:metadata` configuration option for `Sentry.LoggerBackend`
 
+### Deprecations
+
+- Soft-deprecate `Sentry.EventFilter` in favour of `:before_send_event` callbacks.
+
 ## 8.1.0
 
 ### Various fixes & improvements

lib/sentry.ex

@@ -139,13 +139,13 @@ defmodule Sentry do
       to keep. Defaults to `100`. See `Sentry.Context.add_breadcrumb/1`.
 
     * `:before_send_event` (`t:before_send_event_callback/0`) - allows performing operations
-      on the event *before* it is sent. If the callback returns `nil` or `false`,
-      the event is not reported. If it returns an updated `Sentry.Event`, then
-      the updated event is used instead. See the [*Event Callbacks*
+      on the event *before* it is sent as well as filtering out the event altogether.
+      If the callback returns `nil` or `false`, the event is not reported. If it returns an
+      updated `Sentry.Event`, then the updated event is used instead. See the [*Event Callbacks*
       section](#module-event-callbacks) below for more information.
 
     * `:after_send_event` (`t:after_send_event_callback/0`) - callback that is called *after*
-      attempting to send an event.  The result of the HTTP call as well as the event will
+      attempting to send an event. The result of the HTTP call as well as the event will
       be passed as arguments. The return value of the callback is not returned. See the
       [*Event Callbacks* section](#module-event-callbacks) below for more information.
 
@@ -231,25 +231,12 @@ defmodule Sentry do
   ## Filtering Exceptions
 
   If you would like to prevent Sentry from sending certain exceptions, you can
-  use the `:filter` configuration option. It must be configured to be a module
-  that implements the `Sentry.EventFilter` behaviour.
-
-  A configuration like the one below prevents sending `Phoenix.Router.NoRouteError`
-  exceptions coming from `Sentry.Plug`, but allows other exceptions to be sent.
-
-      defmodule MyApp.SentryEventFilter do
-        @behaviour Sentry.EventFilter
-
-        @impl true
-        def exclude_exception?(%Phoenix.Router.NoRouteError{}, :plug), do: true
-        def exclude_exception?(_exception, _source), do: false
-      end
-
-      # In config/config.exs
-      config :sentry,
-        filter: MyApp.SentryEventFilter,
-        # other config...
+  use the `:before_send_event` configuration option. See the [*Event Callbacks*
+  section](#module-event-callbacks) below.
 
+  Before v9.0.0, the recommended way to filter out exceptions was to use a *filter*,
+  that is, a module implementing the `Sentry.EventFilter` behaviour. This is still supported,
+  but is not deprecated. See `Sentry.EventFilter` for more information.
 
   ## Event Callbacks
 

lib/sentry/event_filter.ex

@@ -4,6 +4,17 @@ defmodule Sentry.EventFilter do
 
   There's only one callback to implement, `c:exclude_exception?/2`.
 
+  > #### Soft-deprecated {: .warning}
+  >
+  > This behaviour is soft-deprecated in favor of filtering events through the
+  > `:before_send_event` callback functionality. `:before_send_event` is described in
+  > details in the documentation for the `Sentry` module. It's a more general
+  > mechanism to filter or modify events before sending them to Sentry. See below for
+  > an example of how to replace an event filter with a `:before_send_event` callback.
+  >
+  > In future major versions of this library, we might hard-deprecate or remove this
+  > behaviour altogether.
+
   ## Usage
 
   To use a custom event filter module, configure the `:filter` option
@@ -54,6 +65,38 @@ defmodule Sentry.EventFilter do
         end
       end
 
+  ## Replacing With `:before_send_event`
+
+  Let's look at an example of how to filter non-500 exceptions in a Plug app through
+  the `:before_send_event` callback. We can start with a module:
+
+      defmodule MyApp.SentryEventFilter do
+        def filter_non_500(%Sentry.Event{ __original_exception__: exception} = event) do
+          cond do
+            if Plug.Exception.status(exception) < 500 ->
+              false
+
+            # Fall back to the default event filter.
+            Sentry.DefaultEventFilter.exclude_exception?(exception, event.__source__) ->
+              false
+
+            true ->
+              event
+          end
+        end
+      end
+
+  Then, we can configure the `:before_send_event` callback.
+
+      config :sentry,
+        before_send_event: {MyApp.SentryEventFilter, :filter_non_500}
+
+  > #### Multiple Callbacks {: .tip}
+  >
+  > You can only have one `:before_send_event` callback. If you change the value
+  > of this configuration option, you'll *override* the previous callback. If you
+  > want to do multiple things in a `:before_send_event` callback, create a function
+  > that does all the things you need and register *that* as the callback.
   """
 
   @doc """