Slightly re-haul how we document options (#778)

Co-authored-by: Andrea Leopardi <[email protected]>

Author: savhappy

lib/sentry.ex

@@ -16,6 +16,9 @@ defmodule Sentry do
       [*Setup with Plug and Phoenix* guide](setup-with-plug-and-phoenix.html), and the
       `Sentry.PlugCapture` and `Sentry.PlugContext` modules.
 
+    * Through integrations for various ecosystem tools, like [Oban](oban-integration.html)
+      or [Quantum](quantum-integration.html).
+
   ## Usage
 
   Add the following to your production configuration:
@@ -65,9 +68,11 @@ defmodule Sentry do
 
   ## Configuration
 
-  You can configure Sentry through the application environment. Configure
-  the following keys under the `:sentry` application. For example, you can
-  do this in `config/config.exs`:
+  *See also the [official Sentry
+  documentation](https://docs.sentry.io/platforms/elixir/configuration/).*
+
+  You can configure Sentry through the application environment, under the `:sentry` application.
+  For example, you can do this in `config/config.exs`:
 
       # config/config.exs
       config :sentry,
@@ -174,7 +179,7 @@ defmodule Sentry do
   > with `:source_code_exclude_patterns`.
   """
 
-  alias Sentry.{CheckIn, Client, ClientError, Config, Event, LoggerUtils}
+  alias Sentry.{CheckIn, Client, ClientError, Config, Event, LoggerUtils, Options}
 
   require Logger
 
@@ -224,13 +229,15 @@ defmodule Sentry do
   and is not `nil`. See the [*Configuration* section](#module-configuration)
   in the module documentation.
 
-  The `opts` argument is passed as the second argument to `send_event/2`.
+  ## Options
+
+  #{Options.docs_for(:capture_exception)}
   """
-  @spec capture_exception(Exception.t(), keyword()) :: send_result
-  def capture_exception(exception, opts \\ []) do
+  @spec capture_exception(Exception.t(), keyword()) :: send_result()
+  def capture_exception(exception, options \\ []) do
     filter_module = Config.filter()
-    event_source = Keyword.get(opts, :event_source)
-    {send_opts, create_event_opts} = Client.split_send_event_opts(opts)
+    event_source = Keyword.get(options, :event_source)
+    {send_opts, create_event_opts} = Options.split_send_event_options(options)
 
     if filter_module.exclude_exception?(exception, event_source) do
       :excluded
@@ -263,7 +270,9 @@ defmodule Sentry do
   @doc """
   Reports a message to Sentry.
 
-  `opts` argument is passed as the second argument to `send_event/2`.
+  ## Options
+
+  #{Options.docs_for(:capture_message)}
 
   ## Interpolation (since v10.1.0)
 
@@ -289,7 +298,7 @@ defmodule Sentry do
     {send_opts, create_event_opts} =
       opts
       |> Keyword.put(:message, message)
-      |> Client.split_send_event_opts()
+      |> Options.split_send_event_options()
 
     event = Event.create_event(create_event_opts)
     send_event(event, send_opts)
@@ -302,9 +311,13 @@ defmodule Sentry do
   information about an exception, a message, or any other event that you want to
   report. To manually build events, see the functions in `Sentry.Event`.
 
+  This function doesn't build the event for you, it only *sends* it. Most of the time,
+  you'll want to use `capture_exception/2` or `capture_message/2`. To manually create events,
+  see `Sentry.Event.create_event/1`.
+
   ## Options
 
-  #{NimbleOptions.docs(Client.send_events_opts_schema())}
+  #{Options.docs_for(:send_event)}
 
   > #### Async Send {: .error}
   >
@@ -321,7 +334,7 @@ defmodule Sentry do
   > use cases, use `capture_exception/2` or `capture_message/2`.
   """
   @spec send_event(Event.t(), keyword()) :: send_result
-  def send_event(event, opts \\ []) do
+  def send_event(event, options \\ []) do
     # TODO: remove on v11.0.0, :included_environments was deprecated in 10.0.0.
     included_envs = Config.included_environments()
 
@@ -332,14 +345,16 @@ defmodule Sentry do
 
       # If we're in test mode, let's send the event down the pipeline anyway.
       Config.test_mode?() ->
-        Client.send_event(event, opts)
+        Client.send_event(event, options)
 
       !Config.dsn() ->
-        _opts = Client.validate_options!(opts)
+        # We still validate options even if we're not sending the event. This aims at catching
+        # configuration issues during development instead of only when deploying to production.
+        _options = NimbleOptions.validate!(options, Options.send_event_schema())
         :ignored
 
       included_envs == :all or to_string(Config.environment_name()) in included_envs ->
-        Client.send_event(event, opts)
+        Client.send_event(event, options)
 
       true ->
         :ignored
@@ -366,10 +381,6 @@ defmodule Sentry do
   > to Sentry and will instead return `:ignored`. This behaviour is consistent with
   > the rest of the SDK (such as `capture_exception/2`).
 
-  ## Options
-
-  This functions supports all the options mentioned in `Sentry.CheckIn.new/1`.
-
   ## Examples
 
   Say you have a GenServer which periodically sends a message to itself to execute some

lib/sentry/client.ex

@@ -14,80 +14,15 @@ defmodule Sentry.Client do
     Event,
     Interfaces,
     LoggerUtils,
-    Transport
+    Transport,
+    Options
   }
 
   require Logger
 
   # Max message length per https://github.com/getsentry/sentry/blob/0fcec33ac94ad81a205f86f208072b0f57b39ff4/src/sentry/conf/server.py#L1021
   @max_message_length 8_192
 
-  # The docs for the options here are generated in the Sentry module, so you can refer to types
-  # and functions and so on like if you were writing these docs in the Sentry module itself.
-  send_event_opts_schema = [
-    result: [
-      type: {:in, [:sync, :none]},
-      doc: """
-      Allows specifying how the result should be returned. The possible values are:
-
-      * `:sync` - Sentry will make an API call synchronously (including retries) and will
-        return `{:ok, event_id}` if successful.
-
-      * `:none` - Sentry will send the event in the background, in a *fire-and-forget*
-        fashion. The function will return `{:ok, ""}` regardless of whether the API
-        call ends up being successful or not.
-      """
-    ],
-    sample_rate: [
-      type: :float,
-      doc: """
-      Same as the global `:sample_rate` configuration, but applied only to
-      this call. See the module documentation. *Available since v10.0.0*.
-      """
-    ],
-    before_send: [
-      type: {:or, [{:fun, 1}, {:tuple, [:atom, :atom]}]},
-      type_doc: "`t:before_send_event_callback/0`",
-      doc: """
-      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: [
-      type: {:or, [{:fun, 2}, {:tuple, [:atom, :atom]}]},
-      type_doc: "`t:after_send_event_callback/1`",
-      doc: """
-      Same as the global `:after_send_event` configuration, but
-      applied only to this call. See the module documentation. *Available since v10.0.0*.
-      """
-    ],
-    client: [
-      type: :atom,
-      type_doc: "`t:module/0`",
-      doc: """
-      Same as the global `:client` configuration, but
-      applied only to this call. See the module documentation. *Available since v10.0.0*.
-      """
-    ],
-
-    # Private options, only used in testing.
-    request_retries: [
-      type: {:list, :integer},
-      doc: false
-    ]
-  ]
-
-  @send_event_opts_schema NimbleOptions.new!(send_event_opts_schema)
-  @send_event_opts_keys Keyword.keys(send_event_opts_schema)
-
-  @spec send_events_opts_schema() :: NimbleOptions.t()
-  def send_events_opts_schema, do: @send_event_opts_schema
-
-  @spec split_send_event_opts(keyword()) :: {keyword(), keyword()}
-  def split_send_event_opts(options) when is_list(options) do
-    Keyword.split(options, @send_event_opts_keys)
-  end
-
   @spec send_check_in(CheckIn.t(), keyword()) ::
           {:ok, check_in_id :: String.t()} | {:error, term()}
   def send_check_in(%CheckIn{} = check_in, opts) when is_list(opts) do
@@ -116,7 +51,7 @@ defmodule Sentry.Client do
           | :unsampled
           | :excluded
   def send_event(%Event{} = event, opts) when is_list(opts) do
-    opts = validate_options!(opts)
+    opts = NimbleOptions.validate!(opts, Options.send_event_schema())
 
     result_type = Keyword.get_lazy(opts, :result, &Config.send_result/0)
     sample_rate = Keyword.get_lazy(opts, :sample_rate, &Config.sample_rate/0)
@@ -160,11 +95,6 @@ defmodule Sentry.Client do
     end
   end
 
-  @spec validate_options!(keyword()) :: keyword()
-  def validate_options!(opts) when is_list(opts) do
-    NimbleOptions.validate!(opts, @send_event_opts_schema)
-  end
-
   defp sample_event(sample_rate) do
     cond do
       sample_rate == 1 -> :ok

lib/sentry/event.ex

@@ -8,7 +8,7 @@ defmodule Sentry.Event do
   See <https://develop.sentry.dev/sdk/event-payloads>.
   """
 
-  alias Sentry.{Attachment, Config, Interfaces, Sources, UUID}
+  alias Sentry.{Attachment, Config, Interfaces, Sources, UUID, Options}
 
   @sdk %Interfaces.SDK{
     name: "sentry-elixir",
@@ -147,139 +147,7 @@ defmodule Sentry.Event do
     |> Map.drop([:original_exception, :source, :attachments, :integration_meta])
   end
 
-  create_event_opts_schema = [
-    exception: [
-      type: {:custom, __MODULE__, :__validate_exception__, [:exception]},
-      type_doc: "`t:Exception.t/0`",
-      doc: """
-      This is the exception that gets reported in the
-      `:exception` field of `t:t/0`. The term passed here also ends up unchanged in the
-      `:original_exception` field of `t:t/0`. This option is **required** unless the
-      `:message` option is present. Not present by default.
-      """
-    ],
-    stacktrace: [
-      type:
-        {:list,
-         {:or,
-          [
-            {:tuple, [:atom, :atom, :any, :keyword_list]},
-            {:tuple, [:any, :any, :keyword_list]}
-          ]}},
-      type_doc: "`t:Exception.stacktrace/0`",
-      doc: """
-      The exception's stacktrace. This can also be used with messages (`:message`). Not
-      present by default.
-      """
-    ],
-    message: [
-      type: :string,
-      doc: """
-      A message to report. The string can contain interpolation markers (`%s`). In that
-      case, you can pass the `:interpolation_parameters` option as well to fill
-      in those parameters. See `Sentry.capture_message/2` for more information on
-      message interpolation. Not present by default.
-      """
-    ],
-    extra: [
-      type: {:map, {:or, [:atom, :string]}, :any},
-      type_doc: "`t:Sentry.Context.extra/0`",
-      default: %{},
-      doc: """
-      Map of extra context, which gets merged with the current context
-      (see `Sentry.Context.set_extra_context/1`). If fields collide, the ones
-      in the map passed through this option have precedence over the ones in
-      the context.
-      """
-    ],
-    user: [
-      type: :map,
-      type_doc: "`t:Sentry.Context.user_context/0`",
-      default: %{},
-      doc: """
-      Map of user context, which gets merged with the current context
-      (see `Sentry.Context.set_user_context/1`). If fields collide, the ones
-      in the map passed through this option have precedence over the ones in
-      the context.
-      """
-    ],
-    tags: [
-      type: {:map, {:or, [:atom, :string]}, :any},
-      type_doc: "`t:Sentry.Context.tags/0`",
-      default: %{},
-      doc: """
-      Map of tags context, which gets merged with the current context (see
-      `Sentry.Context.set_tags_context/1`) and with the `:tags` option in the global
-      Sentry configuration. If fields collide, the ones in the map passed through
-      this option have precedence over the ones in the context, which have precedence
-      over the ones in the configuration.
-      """
-    ],
-    request: [
-      type: :map,
-      type_doc: "`t:Sentry.Context.request_context/0`",
-      default: %{},
-      doc: """
-      Map of request context, which gets merged with the current context
-      (see `Sentry.Context.set_request_context/1`). If fields collide, the ones
-      in the map passed through this option have precedence over the ones in
-      the context.
-      """
-    ],
-    breadcrumbs: [
-      type: {:list, {:or, [:keyword_list, :map]}},
-      type_doc: "list of `t:keyword/0` or `t:Sentry.Context.breadcrumb/0`",
-      default: [],
-      doc: """
-      List of breadcrumbs. This list gets **prepended** to the list
-      in the context (see `Sentry.Context.add_breadcrumb/1`).
-      """
-    ],
-    level: [
-      type: {:in, [:fatal, :error, :warning, :info, :debug]},
-      type_doc: "`t:level/0`",
-      default: :error,
-      doc: """
-      The level of the event.
-      """
-    ],
-    fingerprint: [
-      type: {:list, :string},
-      default: ["{{ default }}"],
-      doc: """
-      List of the fingerprint for grouping this event.
-      """
-    ],
-    event_source: [
-      type: :atom,
-      doc: """
-      The source of the event. This fills in the `:source` field of the
-      returned struct. This is not present by default.
-      """
-    ],
-    interpolation_parameters: [
-      type: {:list, :any},
-      doc: """
-      The parameters to use for message interpolation. This is only used if the
-      `:message` option is present. This is not present by default. See
-      `Sentry.capture_message/2`. *Available since v10.1.0*.
-      """
-    ],
-    integration_meta: [
-      type: :map,
-      default: %{},
-      doc: false
-    ],
-
-    ## Internal options
-    handled: [
-      type: :boolean,
-      default: true,
-      doc: false
-    ]
-  ]
-
-  @create_event_opts_schema NimbleOptions.new!(create_event_opts_schema)
+  @create_event_opts_schema Options.create_event_schema()
 
   @doc """
   Creates an event struct out of collected context and options.
@@ -461,12 +329,11 @@ defmodule Sentry.Event do
   @doc """
   Transforms an exception to a Sentry event.
 
-  This essentially defers to `create_event/1`, inferring some options from
-  the given `exception`.
+  This essentially defers to `create_event/1`.
 
   ## Options
 
-  This function takes the same options as `create_event/1`.
+  This function takes the same options as `create_event/1`, except for the `:exception` option.
   """
   @spec transform_exception(Exception.t(), keyword()) :: t()
   def transform_exception(exception, opts) when is_exception(exception) and is_list(opts) do