Add exception mechanism set handled/unhandled (#677)

Closes #666.

Author: whatyouhide

lib/sentry/client.ex

@@ -234,6 +234,7 @@ defmodule Sentry.Client do
   defp render_exception(%Interfaces.Exception{} = exception) do
     exception
     |> Map.from_struct()
+    |> update_if_present(:mechanism, &Map.from_struct/1)
     |> update_if_present(:stacktrace, fn %Interfaces.Stacktrace{frames: frames} ->
       %{frames: Enum.map(frames, &Map.from_struct/1)}
     end)

lib/sentry/event.ex

@@ -254,6 +254,13 @@ defmodule Sentry.Event do
       `:message` option is present. This is not present by default. See
       `Sentry.capture_message/2`. *Available since v10.1.0*.
       """
+    ],
+
+    ## Internal options
+    handled: [
+      type: :boolean,
+      default: true,
+      doc: false
     ]
   ]
 
@@ -330,6 +337,7 @@ defmodule Sentry.Event do
     exception = Keyword.get(opts, :exception)
     stacktrace = Keyword.get(opts, :stacktrace)
     source = Keyword.get(opts, :event_source)
+    handled? = Keyword.fetch!(opts, :handled)
 
     event = %__MODULE__{
       attachments: attachments_context,
@@ -338,7 +346,7 @@ defmodule Sentry.Event do
       culprit: culprit_from_stacktrace(Keyword.get(opts, :stacktrace, [])),
       environment: Config.environment_name(),
       event_id: UUID.uuid4_hex(),
-      exception: List.wrap(coerce_exception(exception, stacktrace, message)),
+      exception: List.wrap(coerce_exception(exception, stacktrace, message, handled?)),
       extra: extra,
       fingerprint: Keyword.fetch!(opts, :fingerprint),
       level: Keyword.fetch!(opts, :level),
@@ -403,11 +411,13 @@ defmodule Sentry.Event do
   # If we have a message with a stacktrace, but no exceptions, for now we store the stacktrace in
   # the "threads" interface and we don't fill in the "exception" interface altogether. This might
   # be eventually fixed in Sentry itself: https://github.com/getsentry/sentry/issues/61239
-  defp coerce_exception(_exception = nil, _stacktrace_or_nil, message) when is_binary(message) do
+  defp coerce_exception(_exception = nil, _stacktrace_or_nil, message, _handled?)
+       when is_binary(message) do
     nil
   end
 
-  defp coerce_exception(exception, stacktrace_or_nil, _message) when is_exception(exception) do
+  defp coerce_exception(exception, stacktrace_or_nil, _message, handled?)
+       when is_exception(exception) do
     stacktrace =
       if is_list(stacktrace_or_nil) do
         %Interfaces.Stacktrace{frames: stacktrace_to_frames(stacktrace_or_nil)}
@@ -416,11 +426,12 @@ defmodule Sentry.Event do
     %Interfaces.Exception{
       type: inspect(exception.__struct__),
       value: Exception.message(exception),
-      stacktrace: stacktrace
+      stacktrace: stacktrace,
+      mechanism: %Interfaces.Exception.Mechanism{handled: handled?}
     }
   end
 
-  defp coerce_exception(_exception = nil, stacktrace, _message = nil) do
+  defp coerce_exception(_exception = nil, stacktrace, _message = nil, _handled?) do
     unless is_nil(stacktrace) do
       raise ArgumentError,
             "cannot provide a :stacktrace option without an exception or a message, got: #{inspect(stacktrace)}"

lib/sentry/interfaces.ex

@@ -113,6 +113,28 @@ defmodule Sentry.Interfaces do
     defstruct [:message, :params, :formatted]
   end
 
+  defmodule Exception.Mechanism do
+    @moduledoc """
+    The struct for the **exception mechanism** to be used within exceptions.
+
+    See `Sentry.Interfaces.Exception`.
+    """
+
+    @moduledoc since: "10.2.0"
+
+    @typedoc since: "10.2.0"
+    @type t() :: %__MODULE__{
+            type: String.t(),
+            handled: boolean() | nil,
+            data: map() | nil,
+            synthetic: boolean() | nil,
+            help_link: String.t() | nil,
+            meta: map() | nil
+          }
+
+    defstruct [:handled, :data, :synthetic, :help_link, :meta, type: "generic"]
+  end
+
   defmodule Exception do
     @moduledoc """
     The struct for the **exception** interface.
@@ -127,11 +149,12 @@ defmodule Sentry.Interfaces do
             type: String.t(),
             value: String.t(),
             module: String.t() | nil,
-            stacktrace: Sentry.Interfaces.Stacktrace.t() | nil
+            stacktrace: Sentry.Interfaces.Stacktrace.t() | nil,
+            mechanism: Sentry.Interfaces.Exception.Mechanism.t() | nil
           }
 
     @enforce_keys [:type, :value]
-    defstruct [:type, :value, :module, :stacktrace]
+    defstruct [:type, :value, :module, :stacktrace, :mechanism]
   end
 
   defmodule Stacktrace.Frame do

lib/sentry/logger_backend.ex

@@ -138,7 +138,8 @@ defmodule Sentry.LoggerBackend do
       # If the crash reason is an exception, we want to report the exception itself
       # for better event reporting.
       {exception, stacktrace} when is_exception(exception) and is_list(stacktrace) ->
-        Sentry.capture_exception(exception, Keyword.put(opts, :stacktrace, stacktrace))
+        opts = Keyword.merge(opts, stacktrace: stacktrace, handled: false)
+        Sentry.capture_exception(exception, opts)
 
       # If the crash reason is a {reason, stacktrace} tuple, then we can report
       # the originally-logged message (as a message) and include the stacktrace in

lib/sentry/logger_handler.ex

@@ -171,7 +171,8 @@ defmodule Sentry.LoggerHandler do
     case Map.new(report) do
       %{report: %{reason: {exception, stacktrace}}}
       when is_exception(exception) and is_list(stacktrace) ->
-        Sentry.capture_exception(exception, Keyword.put(sentry_opts, :stacktrace, stacktrace))
+        sentry_opts = Keyword.merge(sentry_opts, stacktrace: stacktrace, handled: false)
+        Sentry.capture_exception(exception, sentry_opts)
 
       %{report: %{reason: {reason, stacktrace}}} when is_list(stacktrace) ->
         sentry_opts = Keyword.put(sentry_opts, :stacktrace, stacktrace)
@@ -219,7 +220,8 @@ defmodule Sentry.LoggerHandler do
          %__MODULE__{}
        )
        when is_exception(exception) and is_list(stacktrace) do
-    Sentry.capture_exception(exception, Keyword.put(sentry_opts, :stacktrace, stacktrace))
+    sentry_opts = Keyword.merge(sentry_opts, stacktrace: stacktrace, handled: false)
+    Sentry.capture_exception(exception, sentry_opts)
   end
 
   defp log_from_crash_reason({reason, stacktrace}, string_message, sentry_opts, %__MODULE__{})

lib/sentry/plug_capture.ex

@@ -137,7 +137,13 @@ defmodule Sentry.PlugCapture do
         exception
       end
 
-    _ = Sentry.capture_exception(exception, stacktrace: stacktrace, event_source: :plug)
+    _ =
+      Sentry.capture_exception(exception,
+        stacktrace: stacktrace,
+        event_source: :plug,
+        handled: false
+      )
+
     :ok
   end
 

test/event_test.exs

@@ -180,7 +180,22 @@ defmodule Sentry.EventTest do
       assert event.exception == [
                %Interfaces.Exception{
                  type: "RuntimeError",
-                 value: "foo"
+                 value: "foo",
+                 mechanism: %Interfaces.Exception.Mechanism{handled: true}
+               }
+             ]
+    end
+
+    test "fills in the exception interface with the :handled option" do
+      assert %Event{} =
+               event =
+               Event.create_event(exception: %RuntimeError{message: "foo"}, handled: false)
+
+      assert event.exception == [
+               %Interfaces.Exception{
+                 type: "RuntimeError",
+                 value: "foo",
+                 mechanism: %Interfaces.Exception.Mechanism{handled: false}
                }
              ]
     end