Merge pull request #402 from getsentry/plug-capture

PlugCapture and PlugContext

Author: mitchellhenke

.formatter.exs

@@ -1,4 +1,5 @@
 [
+  import_deps: [:plug],
   inputs: [
     "lib/**/*.ex",
     "config/*.exs",

CHANGELOG.md

@@ -13,6 +13,9 @@
   * Change default event send type to :none instead of :async (#341)
   * Make hackney an optional dependency, and simplify Sentry.HTTPClient behaviour (#400)
   * Use Logger.metadata for Sentry.Context, no longer return metadata values on set_* functions, and rename `set_http_context` to `set_request_context`
+  * Move excluded exceptions from Sentry.Plug to Sentry.DefaultEventFilter
+  * Remove Sentry.Plug and Sentry.Phoenix.Endpoint in favor of Sentry.PlugContext and Sentry.PlugCapture
+  * Remove feedback form rendering and configuration
 
 ## 7.2.4 (2020-03-09)
 

README.md

@@ -2,18 +2,10 @@
 
 [![Build Status](https://img.shields.io/travis/getsentry/sentry-elixir.svg?style=flat)](https://travis-ci.org/getsentry/sentry-elixir)
 [![hex.pm version](https://img.shields.io/hexpm/v/sentry.svg?style=flat)](https://hex.pm/packages/sentry)
-
-The Official Sentry Client for Elixir which provides a simple API to capture exceptions, automatically handle Plug Exceptions and provides a backend for the Elixir Logger.
-
 [Documentation](https://hexdocs.pm/sentry/readme.html)
 
-## Note on upgrading from Sentry 6.x to 7.x
-
-Elixir 1.7 and Erlang/OTP 21 significantly changed how errors are transmitted (See "Erlang/OTP logger integration" [here](https://elixir-lang.org/blog/2018/07/25/elixir-v1-7-0-released/)).  Sentry integrated heavily with Erlang's `:error_logger` module, but it is no longer the suggested path towards handling errors.
+The Official Sentry Client for Elixir which provides a simple API to capture exceptions, automatically handle Plug Exceptions and provides a backend for the Elixir Logger. This documentation represents unreleased features, for documentation on the current release, see [here](https://hexdocs.pm/sentry/readme.html).
 
-Sentry 7.x requires Elixir 1.7 and Sentry 6.x will be maintained for applications running prior versions.  Documentation for Sentry 6.x can be found [here](https://hexdocs.pm/sentry/6.4.2/readme.html).
-
-If you would like to upgrade a project to use Sentry 7.x, see [here](https://gist.github.com/mitchellhenke/4ab6dd8d0ebeaaf9821fb625e0037a4d).
 
 ## Installation
 
@@ -30,26 +22,67 @@ defp deps do
 end
 ```
 
-### Setup with Plug or Phoenix
+### Setup with Plug and Phoenix
+Capturing errors in Plug applications is done with `Sentry.PlugContext` and `Sentry.PlugCapture`. `Sentry.PlugContext` adds contextual metadata from the current request which is then included in errors that are captured and reported by `Sentry.PlugCapture`.
 
-In your Plug.Router or Phoenix.Router, add the following lines:
+If you are using Phoenix, first add `Sentry.PlugCapture` above the `use Phoenix.Endpoint` line in your endpoint file. `Sentry.PlugContext` should be added below `Plug.Parsers`.
 
 ```diff
- # lib/my_app_web/router.ex
- defmodule MyAppWeb.Router do
-   use MyAppWeb, :router
-+  use Plug.ErrorHandler
-+  use Sentry.Plug
+ defmodule MyAppWeb.Endpoint
++  use Sentry.PlugCapture
+   use Phoenix.Endpoint, otp_app: :my_app
+   # ...
+   plug Plug.Parsers,
+     parsers: [:urlencoded, :multipart, :json],
+     pass: ["*/*"],
+     json_decoder: Phoenix.json_library()
+
++  plug Sentry.PlugContext
 ```
 
-If you are using Phoenix, you can also include [Sentry.Phoenix.Endpoint](https://hexdocs.pm/sentry/Sentry.Phoenix.Endpoint.html) in your Endpoint. This module captures errors occurring in the Phoenix pipeline before the request reaches the Router:
+If you are in a non-Phoenix Plug application, add `Sentry.PlugCapture` at the top of your Plug application, and add `Sentry.PlugContext` below `Plug.Parsers` (if it is in your stack).
 
 ```diff
- use Phoenix.Endpoint, otp_app: :my_app
-+use Sentry.Phoenix.Endpoint
+ defmodule MyApp.Router do
++  use Sentry.PlugCapture
+   use Plug.Router
+   # ...
+   plug Plug.Parsers,
+     parsers: [:urlencoded, :multipart]
++  plug Sentry.PlugContext
 ```
 
-More information on why this may be necessary can be found here: https://github.com/getsentry/sentry-elixir/issues/229 and https://github.com/phoenixframework/phoenix/issues/2791
+#### Capturing User Feedback
+
+If you would like to capture user feedback as described [here](https://docs.sentry.io/enriching-error-data/user-feedback), the `Sentry.get_last_event_id_and_source()` function can be used to see if Sentry has sent an event within the current Plug process, and the source of that event. `:plug` will be the source for events coming from `Sentry.PlugCapture`. The options described in the Sentry documentation linked above can be encoded into the response as well.
+
+An example Phoenix application setup that wanted to display the user feedback form on 500 responses on requests accepting HTML could look like:
+
+```elixir
+defmodule MyAppWeb.ErrorView do
+  # ...
+  def render("500.html", _assigns) do
+    case Sentry.get_last_event_id_and_source() do
+      {event_id, :plug} when is_binary(event_id) ->
+        opts =
+          # can do %{eventId: event_id, title: "My custom title"}
+          %{eventId: event_id}
+          |> Jason.encode!()
+
+        ~E"""
+          <script src="https://browser.sentry-cdn.com/5.9.1/bundle.min.js" integrity="sha384-/x1aHz0nKRd6zVUazsV6CbQvjJvr6zQL2CHbQZf3yoLkezyEtZUpqUNnOLW9Nt3v" crossorigin="anonymous"></script>
+          <script>
+            Sentry.init({ dsn: '<%= Sentry.Config.dsn() %>' });
+            Sentry.showReportDialog(<%= raw opts %>)
+          </script>
+        """
+
+      _ ->
+        "Error"
+    end
+  # ...
+  end
+```
 
 ### Capture Crashed Process Exceptions
 

config/test.exs

@@ -9,3 +9,5 @@ config :sentry,
 
 config :ex_unit,
   assert_receive_timeout: 500
+
+config :phoenix, :json_library, Jason

lib/sentry.ex

@@ -126,6 +126,25 @@ defmodule Sentry do
     end
   end
 
+  @doc """
+  Puts the last event ID sent to the server for the current process in
+  the process dictionary.
+  """
+  @spec put_last_event_id_and_source(String.t()) :: {String.t(), atom() | nil} | nil
+  def put_last_event_id_and_source(event_id, source \\ nil) when is_binary(event_id) do
+    Process.put(:sentry_last_event_id_and_source, {event_id, source})
+  end
+
+  @doc """
+  Gets the last event ID sent to the server from the process dictionary.
+  Since it uses the process dictionary, it will only return the last event
+  ID sent within the current process.
+  """
+  @spec get_last_event_id_and_source() :: {String.t(), atom() | nil} | nil
+  def get_last_event_id_and_source do
+    Process.get(:sentry_last_event_id_and_source)
+  end
+
   @doc """
   Reports a message to Sentry.
 

lib/sentry/client.ex

@@ -119,6 +119,10 @@ defmodule Sentry.Client do
           maybe_log_result(result)
         end
 
+        if match?({:ok, _}, result) do
+          Sentry.put_last_event_id_and_source(event.event_id, event.event_source)
+        end
+
         result
 
       {:error, error} ->

lib/sentry/default_event_filter.ex

@@ -3,5 +3,11 @@ defmodule Sentry.DefaultEventFilter do
 
   @moduledoc false
 
+  def exclude_exception?(%x{}, :plug) when x in [Phoenix.Router.NoRouteError] do
+    true
+  end
+
+  def exclude_exception?(%FunctionClauseError{function: :do_match, arity: 4}, :plug), do: true
+
   def exclude_exception?(_, _), do: false
 end

lib/sentry/event_filter.ex

@@ -3,10 +3,10 @@ defmodule Sentry.EventFilter do
   This module defines a Behaviour for filtering Sentry events.
   There is one callback to implement. The first argument will be
   the exception reported, and the second is the source. Events
-  from `Sentry.Plug` will have :plug as a source, `Sentry.Phoenix.Endpoint`
-  will have `:endpoint` and events from `Sentry.LoggerBackend` will have
-  `:logger` as the source. A custom source can also be specified by passing
-  the `event_source` option to `Sentry.capture_exception/2`.
+  from `Sentry.PlugCapture` will have :plug as a source and events from
+  `Sentry.LoggerBackend` will have `:logger` as the source. A custom
+  source can also be specified by passing the `event_source` option
+  to `Sentry.capture_exception/2`.
 
   As an example, if you wanted to exclude any `ArithmeticError` exceptions:
 
@@ -16,6 +16,8 @@ defmodule Sentry.EventFilter do
         def exclude_exception?(%ArithmeticError{}, _source), do: true
         def exclude_exception?(_exception, _source), do: false
       end
+
+  Sentry uses `Sentry.DefaultEventFilter` by default.
   """
 
   @doc """

lib/sentry/phoenix_endpoint.ex

@@ -0,0 +1,53 @@
+if Code.ensure_loaded?(Plug) do
+  defmodule Sentry.PlugCapture do
+    @moduledoc """
+    Provides basic functionality to handle and send errors occurring within
+    Plug applications, including Phoenix.
+    It is intended for usage with `Sentry.PlugContext`.
+
+    #### Usage
+    In a Phoenix application, it is important to use this module before
+    the Phoenix endpoint itself. It should be added to your endpoint.ex:
+
+
+        defmodule MyApp.Endpoint
+          use Sentry.PlugCapture
+          use Phoenix.Endpoint, otp_app: :my_app
+          # ...
+        end
+
+    In a Plug application, it can be added below your router:
+
+        defmodule MyApp.PlugRouter do
+          use Plug.Router
+          use Sentry.PlugCapture
+          # ...
+        end
+    """
+    defmacro __using__(_opts) do
+      quote do
+        @before_compile Sentry.PlugCapture
+      end
+    end
+
+    defmacro __before_compile__(_) do
+      quote do
+        defoverridable call: 2
+
+        def call(conn, opts) do
+          try do
+            super(conn, opts)
+          rescue
+            e in Plug.Conn.WrapperError ->
+              Sentry.capture_exception(e.reason, stacktrace: e.stack, event_source: :plug)
+              Plug.Conn.WrapperError.reraise(e)
+
+            e ->
+              Sentry.capture_exception(e, stacktrace: __STACKTRACE__, event_source: :plug)
+              :erlang.raise(:error, e, __STACKTRACE__)
+          end
+        end
+      end
+    end
+  end
+end