Rename :before_send_event to :before_send (and hard-deprecate) (#649)

Author: whatyouhide

CHANGELOG.md

@@ -7,6 +7,7 @@
 - Add `~r"/test/"` to the default source code exclude patterns (see the `:source_code_exclude_patterns` option).
 - `:environment_name` now defaults to `production` (if it wasn't configured explicitly and if the `SENTRY_ENVIRONMENT` environment variable is not set).
 - Hard-deprecate `:included_environments`. To control whether to send events to Sentry, use the `:dsn` configuration option instead. `:included_environments` now emits a warning if used, but will still work until v11.0.0 of this library.
+- Hard-deprecate `:before_send_event` in favor of the new `:before_send`. This brings this SDK in line with all other Sentry SDKs.
 
 ## 9.1.0
 

lib/sentry.ex

@@ -99,7 +99,7 @@ defmodule Sentry do
   ## Filtering Exceptions
 
   If you would like to prevent Sentry from sending certain exceptions, you can
-  use the `:before_send_event` configuration option. See the [*Event Callbacks*
+  use the `:before_send` 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*,
@@ -108,14 +108,14 @@ defmodule Sentry do
 
   ## Event Callbacks
 
-  You can configure the `:before_send_event` and `:after_send_event` options to
-  customize what happens before and/or after sending an event. The `:before_send_event`
+  You can configure the `:before_send` and `:after_send_event` options to
+  customize what happens before and/or after sending an event. The `:before_send`
   callback must be of type `t:before_send_event_callback/0` and the `:after_send_event`
   callback must be of type `t:after_send_event_callback/0`. For example, you
   can set:
 
       config :sentry,
-        before_send_event: {MyModule, :before_send},
+        before_send: {MyModule, :before_send},
         after_send_event: {MyModule, :after_send}
 
   `MyModule` could look like this:
@@ -176,7 +176,7 @@ defmodule Sentry do
   require Logger
 
   @typedoc """
-  A callback to use with the `:before_send_event` configuration option.
+  A callback to use with the `:before_send` configuration option.
   configuration options.k
 
   If this is `{module, function_name}`, then `module.function_name(event)` will
@@ -294,7 +294,7 @@ defmodule Sentry do
     * `:sample_rate` - same as the global `:sample_rate` configuration, but applied only to
       this call. See the module documentation. *Available since v10.0.0*.
 
-    * `:before_send_event` - same as the global `:before_send_event` configuration, but
+    * `:before_send` - same as the global `:before_send` configuration, but
       applied only to this call. See the module documentation. *Available since v10.0.0*.
 
     * `:after_send_event` - same as the global `:after_send_event` configuration, but

lib/sentry/client.ex

@@ -19,7 +19,7 @@ defmodule Sentry.Client do
   def send_event(%Event{} = event, opts) when is_list(opts) do
     result_type = Keyword.get_lazy(opts, :result, &Config.send_result/0)
     sample_rate = Keyword.get_lazy(opts, :sample_rate, &Config.sample_rate/0)
-    before_send_event = Keyword.get_lazy(opts, :before_send_event, &Config.before_send_event/0)
+    before_send = Keyword.get_lazy(opts, :before_send, &Config.before_send/0)
     after_send_event = Keyword.get_lazy(opts, :after_send_event, &Config.after_send_event/0)
     client = Keyword.get_lazy(opts, :client, &Config.client/0)
 
@@ -30,7 +30,7 @@ defmodule Sentry.Client do
       end)
 
     result =
-      with {:ok, %Event{} = event} <- maybe_call_before_send(event, before_send_event),
+      with {:ok, %Event{} = event} <- maybe_call_before_send(event, before_send),
            :ok <- sample_event(sample_rate) do
         send_result = encode_and_send(event, result_type, client, request_retries)
         _ignored = maybe_call_after_send(event, send_result, after_send_event)
@@ -86,7 +86,7 @@ defmodule Sentry.Client do
 
   defp call_before_send(_event, other) do
     raise ArgumentError, """
-    :before_send_event must be an anonymous function or a {module, function} tuple, got: \
+    :before_send must be an anonymous function or a {module, function} tuple, got: \
     #{inspect(other)}\
     """
   end

lib/sentry/config.ex

@@ -71,7 +71,7 @@ defmodule Sentry.Config do
       doc: """
       The percentage of events to send to Sentry. A value of `0.0` will deny sending any events,
       and a value of `1.0` will send 100% of events. Sampling is applied
-      **after** the `:before_send_event` callback. See where [the Sentry
+      **after** the `:before_send` callback. See where [the Sentry
       documentation](https://develop.sentry.dev/sdk/sessions/#filter-order)
       suggests this. Must be between `0.0` and `1.0` (included).
       """
@@ -238,7 +238,7 @@ defmodule Sentry.Config do
   ]
 
   hook_opts_schema = [
-    before_send_event: [
+    before_send: [
       type: {:or, [{:fun, 1}, {:tuple, [:atom, :atom]}]},
       type_doc: "`t:before_send_event_callback/0`",
       doc: """
@@ -247,6 +247,16 @@ defmodule Sentry.Config do
       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.
+
+      `:before_send` is available *since v10.0.0*. Before, it was called `:before_send_event`.
+      """
+    ],
+    before_send_event: [
+      type: {:or, [{:fun, 1}, {:tuple, [:atom, :atom]}]},
+      type_doc: "`t:before_send_event_callback/0`",
+      deprecated: "Use :before_send instead.",
+      doc: """
+      Exactly the same as `:before_send`, but has been **deprecated since v10.0.0**.
       """
     ],
     after_send_event: [
@@ -299,6 +309,7 @@ defmodule Sentry.Config do
         |> normalize_included_environments()
         |> normalize_environment()
         |> assert_dsn_has_no_query_params!()
+        |> handle_deprecated_before_send()
 
       {:error, error} ->
         raise ArgumentError, """
@@ -413,8 +424,8 @@ defmodule Sentry.Config do
   @spec hackney_opts() :: keyword()
   def hackney_opts, do: fetch!(:hackney_opts)
 
-  @spec before_send_event() :: (Sentry.Event.t() -> Sentry.Event.t()) | {module(), atom()} | nil
-  def before_send_event, do: get(:before_send_event)
+  @spec before_send() :: (Sentry.Event.t() -> Sentry.Event.t()) | {module(), atom()} | nil
+  def before_send, do: get(:before_send)
 
   @spec after_send_event() ::
           (Sentry.Event.t(), term() -> Sentry.Event.t()) | {module(), atom()} | nil
@@ -463,6 +474,29 @@ defmodule Sentry.Config do
     end)
   end
 
+  # TODO: remove me on v11.0.0, :included_environments has been deprecated
+  # in v10.0.0.
+  defp handle_deprecated_before_send(opts) do
+    {before_send_event, opts} = Keyword.pop(opts, :before_send_event)
+
+    case Keyword.fetch(opts, :before_send) do
+      {:ok, _before_send} when not is_nil(before_send_event) ->
+        raise ArgumentError, """
+        you cannot configure both :before_send and :before_send_event. :before_send_event
+        is deprecated, so only use :before_send from now on.
+        """
+
+      {:ok, _before_send} ->
+        opts
+
+      :error when not is_nil(before_send_event) ->
+        Keyword.put(opts, :before_send, before_send_event)
+
+      :error ->
+        opts
+    end
+  end
+
   defp normalize_environment(config) do
     Keyword.update!(config, :environment_name, &to_string/1)
   end

lib/sentry/event_filter.ex

@@ -7,10 +7,10 @@ defmodule Sentry.EventFilter do
   > #### 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
+  > `:before_send` callback functionality. `:before_send` 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.
+  > an example of how to replace an event filter with a `:before_send` callback.
   >
   > In future major versions of this library, we might hard-deprecate or remove this
   > behaviour altogether.
@@ -65,10 +65,10 @@ defmodule Sentry.EventFilter do
         end
       end
 
-  ## Replacing With `:before_send_event`
+  ## Replacing With `:before_send`
 
   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:
+  the `:before_send` callback. We can start with a module:
 
       defmodule MyApp.SentryEventFilter do
         def filter_non_500(%Sentry.Event{original_exception: exception} = event) do
@@ -86,16 +86,16 @@ defmodule Sentry.EventFilter do
         end
       end
 
-  Then, we can configure the `:before_send_event` callback.
+  Then, we can configure the `:before_send` callback.
 
       config :sentry,
-        before_send_event: {MyApp.SentryEventFilter, :filter_non_500}
+        before_send: {MyApp.SentryEventFilter, :filter_non_500}
 
   > #### Multiple Callbacks {: .tip}
   >
-  > You can only have one `:before_send_event` callback. If you change the value
+  > You can only have one `:before_send` 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
+  > want to do multiple things in a `:before_send` callback, create a function
   > that does all the things you need and register *that* as the callback.
   """
 

pages/upgrade-10.x.md

@@ -26,6 +26,10 @@ Now, packaging source code is an active step that you have to take. The [`mix se
 
 Now, if you're not explicitly setting he `:environment_name` option in your config or setting the `SENTRY_ENVIRONMENT` environment variable, the environment will default to `production` (which is in line with the other Sentry SDKs).
 
+## Rename `:before_send_event` to `:before_send`
+
+To be in line with all other Sentry SDKs, we renamed the `:before_send_event` configuration option to `:before_send`. Just rename `:before_send_event` to `:before_send` in your configuration and potentially in any call where you pass it directly.
+
 ## Stop Using `:included_environments`
 
 We hard-deprecated `:included_environments`. It's a bit of a confusing option that essentially no other Sentry SDKs use. To control whether to send events to Sentry, use the `:dsn` configuration instead (if set then we send events, if not set then we don't send events). `:included_environments` will be removed in v11.0.0.

test/logger_backend_test.exs

@@ -339,7 +339,7 @@ defmodule Sentry.LoggerBackendTest do
     ref = make_ref()
 
     TestEnvironmentHelper.modify_env(:sentry,
-      before_send_event: fn event ->
+      before_send: fn event ->
         send(pid, {ref, event})
         false
       end

test/sentry/client_test.exs

@@ -82,7 +82,7 @@ defmodule Sentry.ClientTest do
       end
     end
 
-    test "calls anonymous :before_send_event callback", %{bypass: bypass} do
+    test "calls anonymous :before_send callback", %{bypass: bypass} do
       Bypass.expect(bypass, fn conn ->
         assert {:ok, body, conn} = Plug.Conn.read_body(conn)
 
@@ -96,7 +96,7 @@ defmodule Sentry.ClientTest do
 
       modify_env(
         :sentry,
-        before_send_event: fn event ->
+        before_send: fn event ->
           metadata = Map.new(Logger.metadata())
           {user_id, rest_metadata} = Map.pop(metadata, :user_id)
 
@@ -114,17 +114,55 @@ defmodule Sentry.ClientTest do
       assert {:ok, _} = Client.send_event(event, result: :sync)
     end
 
-    test "if :before_send_event callback returns falsey, the event is not sent" do
+    # TODO: Remove in v11.0.0, :before_send_event has been deprecated in v10.0.0.
+    test "still supports :before_send_event callback", %{bypass: bypass} do
+      Bypass.expect(bypass, fn conn ->
+        assert {:ok, body, conn} = Plug.Conn.read_body(conn)
+
+        event = TestHelpers.decode_event_from_envelope!(body)
+
+        assert event.extra == %{"key" => "value"}
+        assert event.user["id"] == 1
+
+        Plug.Conn.resp(conn, 200, ~s<{"id": "340"}>)
+      end)
+
+      stderr =
+        ExUnit.CaptureIO.capture_io(:stderr, fn ->
+          modify_env(
+            :sentry,
+            before_send_event: fn event ->
+              metadata = Map.new(Logger.metadata())
+              {user_id, rest_metadata} = Map.pop(metadata, :user_id)
+
+              %Event{
+                event
+                | extra: Map.merge(event.extra, rest_metadata),
+                  user: Map.put(event.user, :id, user_id)
+              }
+            end
+          )
+
+          event = Event.create_event([])
+          Logger.metadata(key: "value", user_id: 1)
+
+          assert {:ok, _} = Client.send_event(event, result: :sync)
+        end)
+
+      assert stderr =~ ":before_send_event option is deprecated. Use :before_send instead."
+    end
+
+    test "if :before_send callback returns falsey, the event is not sent" do
       defmodule CallbackModuleArithmeticError do
-        def before_send_event(event) do
+        def before_send(event) do
           case event.original_exception do
             %ArithmeticError{} -> false
             _ -> event
           end
         end
       end
 
-      modify_env(:sentry, before_send_event: {CallbackModuleArithmeticError, :before_send_event})
+      modify_env(:sentry, before_send: {CallbackModuleArithmeticError, :before_send})
 
       try do
         :rand.uniform() + "1"
@@ -138,13 +176,13 @@ defmodule Sentry.ClientTest do
       :code.purge(CallbackModuleArithmeticError)
     end
 
-    test "calls the :before_send_event callback before using the sample rate and sets the session" do
+    test "calls the :before_send callback before using the sample rate and sets the session" do
       test_pid = self()
       ref = make_ref()
       event = Event.create_event(source: :plug)
 
       modify_env(:sentry,
-        before_send_event: fn event ->
+        before_send: fn event ->
           send(test_pid, {ref, event})
           event
         end

test/sentry/config_test.exs

@@ -120,18 +120,35 @@ defmodule Sentry.ConfigTest do
       end
     end
 
-    test ":before_send_event" do
-      assert Config.validate!(before_send_event: {MyMod, :my_fun})[:before_send_event] ==
+    test ":before_send" do
+      assert Config.validate!(before_send: {MyMod, :my_fun})[:before_send] ==
                {MyMod, :my_fun}
 
       fun = & &1
-      assert Config.validate!(before_send_event: fun)[:before_send_event] == fun
+      assert Config.validate!(before_send: fun)[:before_send] == fun
 
-      assert_raise ArgumentError, ~r/invalid value for :before_send_event option/, fn ->
-        Config.validate!(before_send_event: :not_a_function)
+      assert_raise ArgumentError, ~r/invalid value for :before_send option/, fn ->
+        Config.validate!(before_send: :not_a_function)
       end
     end
 
+    # TODO: Remove in v11.0.0, we deprecated it in v10.0.0.
+    test ":before_send_event" do
+      assert ExUnit.CaptureIO.capture_io(:stderr, fn ->
+               assert Config.validate!(before_send_event: {MyMod, :my_fun})[:before_send] ==
+                        {MyMod, :my_fun}
+             end) =~ ":before_send_event option is deprecated. Use :before_send instead."
+
+      ExUnit.CaptureIO.capture_io(:stderr, fn ->
+        assert_raise ArgumentError, ~r/you cannot configure both :before_send and/, fn ->
+          assert Config.validate!(
+                   before_send_event: {MyMod, :my_fun},
+                   before_send: {MyMod, :my_fun}
+                 )
+        end
+      end)
+    end
+
     test ":after_send_event" do
       assert Config.validate!(after_send_event: {MyMod, :my_fun})[:after_send_event] ==
                {MyMod, :my_fun}

test/sentry/logger_handler_test.exs

@@ -328,7 +328,7 @@ defmodule Sentry.LoggerHandlerTest do
     ref = make_ref()
 
     TestEnvironmentHelper.modify_env(:sentry,
-      before_send_event: fn event ->
+      before_send: fn event ->
         send(pid, {ref, event})
         false
       end