feat: support for before_send_log callback

Closes #909

Author: solnic

lib/sentry.ex

@@ -213,6 +213,17 @@ defmodule Sentry do
           (Sentry.Event.t(), result :: term() -> term())
           | {module(), function_name :: atom()}
 
+  @typedoc """
+  A callback to use with the `:before_send_log` configuration option.
+
+  If this is `{module, function_name}`, then `module.function_name(log_event)` will
+  be called, where `log_event` is of type `t:Sentry.LogEvent.t/0`.
+  """
+  @typedoc since: "12.0.0"
+  @type before_send_log_callback() ::
+          (Sentry.LogEvent.t() -> as_boolean(Sentry.LogEvent.t()))
+          | {module(), function_name :: atom()}
+
   @typedoc """
   The strategy to use when sending an event to Sentry.
   """

lib/sentry/client.ex

@@ -138,9 +138,13 @@ defmodule Sentry.Client do
   @doc """
   Sends a batch of log events to Sentry.
 
-  Log events are sent asynchronously and do not support callbacks or sampling.
+  Log events are sent asynchronously and do not support sampling.
   They are buffered and sent in batches according to the Sentry Logs Protocol.
 
+  If a `:before_send_log` callback is configured, it will be called for each log event.
+  If the callback returns `nil` or `false`, the log event is not sent. If it returns an
+  updated `Sentry.LogEvent`, that will be used instead.
+
   Returns `{:ok, envelope_id}` on success or `{:error, reason}` on failure.
   """
   @doc since: "12.0.0"
@@ -154,17 +158,49 @@ defmodule Sentry.Client do
         {:ok, ""}
 
       :not_collecting ->
-        client = Config.client()
+        log_events
+        |> run_before_send_log_callbacks()
+        |> do_send_log_events()
+    end
+  end
 
-        request_retries =
-          Application.get_env(:sentry, :request_retries, Transport.default_retries())
+  defp run_before_send_log_callbacks(log_events) do
+    callback = Config.before_send_log()
 
-        log_events
-        |> Envelope.from_log_events()
-        |> Transport.encode_and_post_envelope(client, request_retries)
+    if callback do
+      Enum.reduce(log_events, [], fn log_event, acc ->
+        case call_before_send_log(log_event, callback) do
+          %LogEvent{} = result -> [result | acc]
+          _ -> acc
+        end
+      end)
+      |> Enum.reverse()
+    else
+      log_events
     end
   end
 
+  defp call_before_send_log(log_event, function) when is_function(function, 1) do
+    function.(log_event)
+  end
+
+  defp call_before_send_log(log_event, {mod, fun}) do
+    apply(mod, fun, [log_event])
+  end
+
+  defp do_send_log_events([]), do: {:ok, ""}
+
+  defp do_send_log_events(log_events) do
+    client = Config.client()
+
+    request_retries =
+      Application.get_env(:sentry, :request_retries, Transport.default_retries())
+
+    log_events
+    |> Envelope.from_log_events()
+    |> Transport.encode_and_post_envelope(client, request_retries)
+  end
+
   defp sample_event(sample_rate) do
     cond do
       sample_rate == 1 -> :ok

lib/sentry/config.ex

@@ -603,6 +603,17 @@ defmodule Sentry.Config do
       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.
       """
+    ],
+    before_send_log: [
+      type: {:or, [{:fun, 1}, {:tuple, [:atom, :atom]}]},
+      type_doc: "`t:before_send_log_callback/0`",
+      doc: """
+      Allows performing operations on a log event *before* it is sent, as
+      well as filtering out the log event altogether.
+      If the callback returns `nil` or `false`, the log event is not reported. If it returns an
+      updated `Sentry.LogEvent`, then the updated log event is used instead.
+      *Available since v12.0.0*.
+      """
     ]
   ]
 
@@ -808,6 +819,10 @@ defmodule Sentry.Config do
   @spec max_log_events() :: non_neg_integer()
   def max_log_events, do: fetch!(:max_log_events)
 
+  @spec before_send_log() ::
+          (Sentry.LogEvent.t() -> Sentry.LogEvent.t() | nil | false) | {module(), atom()} | nil
+  def before_send_log, do: get(:before_send_log)
+
   @spec put_config(atom(), term()) :: :ok
   def put_config(key, value) when is_atom(key) do
     unless key in @valid_keys do

test/sentry/config_test.exs

@@ -243,6 +243,18 @@ defmodule Sentry.ConfigTest do
         Config.validate!(after_send_event: :not_a_function)
       end
     end
+
+    test ":before_send_log" do
+      assert Config.validate!(before_send_log: {MyMod, :my_fun})[:before_send_log] ==
+               {MyMod, :my_fun}
+
+      fun = & &1
+      assert Config.validate!(before_send_log: fun)[:before_send_log] == fun
+
+      assert_raise ArgumentError, ~r/invalid value for :before_send_log option/, fn ->
+        Config.validate!(before_send_log: :not_a_function)
+      end
+    end
   end
 
   describe "put_config/2" do

test/sentry/logger_handler/logs_test.exs

@@ -618,6 +618,159 @@ defmodule Sentry.LoggerHandler.LogsTest do
     end
   end
 
+  describe "before_send_log callback" do
+    test "allows modifying log events before sending", %{bypass: bypass, buffer: buffer} do
+      test_pid = self()
+
+      put_test_config(
+        before_send_log: fn log_event ->
+          %{log_event | attributes: Map.put(log_event.attributes, "custom_attr", "injected")}
+        end
+      )
+
+      Bypass.expect_once(bypass, "POST", "/api/1/envelope/", fn conn ->
+        {:ok, body, conn} = Plug.Conn.read_body(conn)
+        [_header, _item_header, item_body, _] = String.split(body, "\n")
+
+        item_body_map = decode!(item_body)
+        assert %{"items" => [log_event]} = item_body_map
+
+        assert log_event["attributes"]["custom_attr"] == %{
+                 "type" => "string",
+                 "value" => "injected"
+               }
+
+        send(test_pid, :envelope_sent)
+        Plug.Conn.resp(conn, 200, ~s<{"id": "test-123"}>)
+      end)
+
+      Logger.info("Test message")
+
+      assert_buffer_size(buffer, 1)
+
+      LogEventBuffer.flush(server: buffer)
+
+      assert_receive :envelope_sent, 1000
+    end
+
+    test "filters out log events when callback returns nil", %{bypass: bypass, buffer: buffer} do
+      put_test_config(
+        before_send_log: fn log_event ->
+          if String.contains?(log_event.body, "should_be_filtered") do
+            nil
+          else
+            log_event
+          end
+        end
+      )
+
+      test_pid = self()
+
+      Bypass.expect_once(bypass, "POST", "/api/1/envelope/", fn conn ->
+        {:ok, body, conn} = Plug.Conn.read_body(conn)
+        [_header, _item_header, item_body, _] = String.split(body, "\n")
+
+        item_body_map = decode!(item_body)
+        assert %{"items" => [log_event]} = item_body_map
+        assert log_event["body"] == "This message should pass"
+
+        send(test_pid, :envelope_sent)
+        Plug.Conn.resp(conn, 200, ~s<{"id": "test-123"}>)
+      end)
+
+      Logger.info("This message should_be_filtered")
+      Logger.info("This message should pass")
+
+      assert_buffer_size(buffer, 2)
+
+      LogEventBuffer.flush(server: buffer)
+
+      assert_receive :envelope_sent, 1000
+    end
+
+    test "filters out log events when callback returns false", %{bypass: bypass, buffer: buffer} do
+      put_test_config(
+        before_send_log: fn log_event ->
+          if String.contains?(log_event.body, "drop_me") do
+            false
+          else
+            log_event
+          end
+        end
+      )
+
+      test_pid = self()
+
+      Bypass.expect_once(bypass, "POST", "/api/1/envelope/", fn conn ->
+        {:ok, body, conn} = Plug.Conn.read_body(conn)
+        [_header, _item_header, item_body, _] = String.split(body, "\n")
+
+        item_body_map = decode!(item_body)
+        assert %{"items" => [log_event]} = item_body_map
+        assert log_event["body"] == "Keep this message"
+
+        send(test_pid, :envelope_sent)
+        Plug.Conn.resp(conn, 200, ~s<{"id": "test-123"}>)
+      end)
+
+      Logger.info("drop_me please")
+      Logger.info("Keep this message")
+
+      assert_buffer_size(buffer, 2)
+
+      LogEventBuffer.flush(server: buffer)
+
+      assert_receive :envelope_sent, 1000
+    end
+
+    test "supports MFA tuple callback format", %{bypass: bypass, buffer: buffer} do
+      test_pid = self()
+
+      put_test_config(before_send_log: {__MODULE__, :before_send_log_callback})
+
+      Bypass.expect_once(bypass, "POST", "/api/1/envelope/", fn conn ->
+        {:ok, body, conn} = Plug.Conn.read_body(conn)
+        [_header, _item_header, item_body, _] = String.split(body, "\n")
+
+        item_body_map = decode!(item_body)
+        assert %{"items" => [log_event]} = item_body_map
+
+        assert log_event["attributes"]["mfa_added"] == %{
+                 "type" => "string",
+                 "value" => "true"
+               }
+
+        send(test_pid, :envelope_sent)
+        Plug.Conn.resp(conn, 200, ~s<{"id": "test-123"}>)
+      end)
+
+      Logger.info("Test MFA callback")
+
+      assert_buffer_size(buffer, 1)
+
+      LogEventBuffer.flush(server: buffer)
+
+      assert_receive :envelope_sent, 1000
+    end
+
+    test "does not send any logs when all are filtered", %{buffer: buffer} do
+      put_test_config(before_send_log: fn _log_event -> nil end)
+
+      Logger.info("All messages filtered 1")
+      Logger.info("All messages filtered 2")
+
+      assert_buffer_size(buffer, 2)
+
+      LogEventBuffer.flush(server: buffer)
+
+      refute_receive _, 100
+    end
+  end
+
+  def before_send_log_callback(log_event) do
+    %{log_event | attributes: Map.put(log_event.attributes, "mfa_added", "true")}
+  end
+
   defp add_logs_handler(%{buffer: buffer}) do
     handler_name = :"sentry_logs_handler_#{System.unique_integer([:positive])}"