Add support for sending transactions (#842)

Co-Authored-By: Andrea Leopardi <an.leopardi@gmail.com>

Author: solnic

lib/sentry.ex

@@ -362,6 +362,28 @@ defmodule Sentry do
     end
   end
 
+  def send_transaction(transaction, options \\ []) do
+    # TODO: remove on v11.0.0, :included_environments was deprecated in 10.0.0.
+    included_envs = Config.included_environments()
+
+    cond do
+      Config.test_mode?() ->
+        Client.send_transaction(transaction, options)
+
+      !Config.dsn() ->
+        # 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_transaction(transaction, options)
+
+      true ->
+        :ignored
+    end
+  end
+
   @doc """
   Captures a check-in built with the given `options`.
 

lib/sentry/client.ex

@@ -15,8 +15,9 @@ defmodule Sentry.Client do
     Event,
     Interfaces,
     LoggerUtils,
-    Transport,
-    Options
+    Options,
+    Transaction,
+    Transport
   }
 
   require Logger
@@ -99,14 +100,42 @@ defmodule Sentry.Client do
     client = Config.client()
 
     # This is a "private" option, only really used in testing.
-    request_retries =
-      Application.get_env(:sentry, :request_retries, Transport.default_retries())
+    request_retries = Application.get_env(:sentry, :request_retries, Transport.default_retries())
 
     client_report
     |> Envelope.from_client_report()
     |> Transport.encode_and_post_envelope(client, request_retries)
   end
 
+  def send_transaction(%Transaction{} = transaction, opts \\ []) do
+    opts = NimbleOptions.validate!(opts, Options.send_transaction_schema())
+
+    result_type = Keyword.get_lazy(opts, :result, &Config.send_result/0)
+    client = Keyword.get_lazy(opts, :client, &Config.client/0)
+    sample_rate = Keyword.get_lazy(opts, :sample_rate, &Config.sample_rate/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)
+
+    request_retries =
+      Keyword.get_lazy(opts, :request_retries, fn ->
+        Application.get_env(:sentry, :request_retries, Transport.default_retries())
+      end)
+
+    with :ok <- sample_event(sample_rate),
+         {:ok, %Transaction{} = transaction} <- maybe_call_before_send(transaction, before_send) do
+      send_result = encode_and_send(transaction, result_type, client, request_retries)
+      _ignored = maybe_call_after_send(transaction, send_result, after_send_event)
+      send_result
+    else
+      :unsampled ->
+        ClientReport.Sender.record_discarded_events(:sample_rate, [transaction])
+        :unsampled
+
+      :excluded ->
+        :excluded
+    end
+  end
+
   defp sample_event(sample_rate) do
     cond do
       sample_rate == 1 -> :ok
@@ -161,7 +190,7 @@ defmodule Sentry.Client do
     """
   end
 
-  defp maybe_call_after_send(%Event{} = event, result, callback) do
+  defp maybe_call_after_send(event, result, callback) do
     message = ":after_send_event must be an anonymous function or a {module, function} tuple"
 
     case callback do
@@ -205,6 +234,42 @@ defmodule Sentry.Client do
     end
   end
 
+  defp encode_and_send(
+         %Transaction{} = transaction,
+         _result_type = :sync,
+         client,
+         request_retries
+       ) do
+    case Sentry.Test.maybe_collect(transaction) do
+      :collected ->
+        {:ok, ""}
+
+      :not_collecting ->
+        send_result =
+          transaction
+          |> Envelope.from_transaction()
+          |> Transport.encode_and_post_envelope(client, request_retries)
+
+        send_result
+    end
+  end
+
+  defp encode_and_send(
+         %Transaction{} = transaction,
+         _result_type = :none,
+         client,
+         _request_retries
+       ) do
+    case Sentry.Test.maybe_collect(transaction) do
+      :collected ->
+        {:ok, ""}
+
+      :not_collecting ->
+        :ok = Transport.Sender.send_async(client, transaction)
+        {:ok, ""}
+    end
+  end
+
   @spec render_event(Event.t()) :: map()
   def render_event(%Event{} = event) do
     json_library = Config.json_library()
@@ -225,6 +290,19 @@ defmodule Sentry.Client do
     |> update_if_present(:threads, fn list -> Enum.map(list, &render_thread/1) end)
   end
 
+  @spec render_transaction(%Transaction{}) :: map()
+  def render_transaction(%Transaction{} = transaction) do
+    transaction
+    |> Transaction.to_payload()
+    |> Map.merge(%{
+      platform: "elixir",
+      sdk: %{
+        name: "sentry.elixir",
+        version: Application.spec(:sentry, :vsn)
+      }
+    })
+  end
+
   defp render_exception(%Interfaces.Exception{} = exception) do
     exception
     |> Map.from_struct()

lib/sentry/client_report/sender.ex

@@ -23,6 +23,7 @@ defmodule Sentry.ClientReport.Sender do
                | Sentry.CheckIn.t()
                | ClientReport.t()
                | Sentry.Event.t()
+               | Sentry.Transaction.t()
   def record_discarded_events(reason, event_items, genserver \\ __MODULE__)
       when is_list(event_items) do
     # We silently ignore events whose reasons aren't valid because we have to add it to the allowlist in Snuba

lib/sentry/envelope.ex

@@ -2,11 +2,22 @@ defmodule Sentry.Envelope do
   @moduledoc false
   # https://develop.sentry.dev/sdk/envelopes/
 
-  alias Sentry.{Attachment, CheckIn, ClientReport, Config, Event, UUID}
+  alias Sentry.{
+    Attachment,
+    CheckIn,
+    ClientReport,
+    Config,
+    Event,
+    Transaction,
+    UUID
+  }
 
   @type t() :: %__MODULE__{
           event_id: UUID.t(),
-          items: [Event.t() | Attachment.t() | CheckIn.t() | ClientReport.t(), ...]
+          items: [
+            Attachment.t() | CheckIn.t() | ClientReport.t() | Event.t() | Transaction.t(),
+            ...
+          ]
         }
 
   @enforce_keys [:event_id, :items]
@@ -46,13 +57,31 @@ defmodule Sentry.Envelope do
     }
   end
 
+  @doc """
+  Creates a new envelope containing a transaction with spans.
+  """
+  @spec from_transaction(Transaction.t()) :: t()
+  def from_transaction(%Transaction{} = transaction) do
+    %__MODULE__{
+      event_id: transaction.event_id,
+      items: [transaction]
+    }
+  end
+
   @doc """
   Returns the "data category" of the envelope's contents (to be used in client reports and more).
   """
   @doc since: "10.8.0"
-  @spec get_data_category(Attachment.t() | CheckIn.t() | ClientReport.t() | Event.t()) ::
+  @spec get_data_category(
+          Attachment.t()
+          | CheckIn.t()
+          | ClientReport.t()
+          | Event.t()
+          | Transaction.t()
+        ) ::
           String.t()
   def get_data_category(%Attachment{}), do: "attachment"
+  def get_data_category(%Transaction{}), do: "transaction"
   def get_data_category(%CheckIn{}), do: "monitor"
   def get_data_category(%ClientReport{}), do: "internal"
   def get_data_category(%Event{}), do: "error"
@@ -126,4 +155,15 @@ defmodule Sentry.Envelope do
         throw(error)
     end
   end
+
+  defp item_to_binary(json_library, %Transaction{} = transaction) do
+    case transaction |> Sentry.Client.render_transaction() |> Sentry.JSON.encode(json_library) do
+      {:ok, encoded_transaction} ->
+        header = ~s({"type":"transaction","length":#{byte_size(encoded_transaction)}})
+        [header, ?\n, encoded_transaction, ?\n]
+
+      {:error, _reason} = error ->
+        throw(error)
+    end
+  end
 end

lib/sentry/interfaces.ex

@@ -267,4 +267,47 @@ defmodule Sentry.Interfaces do
       :stacktrace
     ]
   end
+
+  defmodule Span do
+    @moduledoc """
+    The struct for the **span** interface.
+
+    See <https://develop.sentry.dev/sdk/event-payloads/spans>.
+    """
+
+    @moduledoc since: "11.0.0"
+
+    @typedoc since: "11.0.0"
+    @type t() :: %__MODULE__{
+            trace_id: String.t(),
+            span_id: String.t(),
+            start_timestamp: String.t(),
+            timestamp: String.t(),
+            parent_span_id: String.t(),
+            description: String.t(),
+            op: String.t(),
+            status: String.t(),
+            tags: map(),
+            data: map(),
+            origin: String.t()
+          }
+
+    @enforce_keys [:trace_id, :span_id, :start_timestamp, :timestamp]
+
+    defstruct @enforce_keys ++
+                [
+                  :parent_span_id,
+                  :description,
+                  :op,
+                  :status,
+                  :tags,
+                  :data,
+                  :origin
+                ]
+
+    @doc false
+    def to_payload(%__MODULE__{} = span) do
+      Map.from_struct(span)
+    end
+  end
 end

lib/sentry/options.ex

@@ -15,6 +15,14 @@ defmodule Sentry.Options do
         call ends up being successful or not.
       """
     ],
+    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*.
+      """
+    ],
     sample_rate: [
       type: :float,
       doc: """
@@ -38,14 +46,6 @@ defmodule Sentry.Options do
       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: [
@@ -206,6 +206,11 @@ defmodule Sentry.Options do
     @create_event_opts_schema
   end
 
+  @spec send_transaction_schema() :: NimbleOptions.t()
+  def send_transaction_schema do
+    @send_event_opts_schema
+  end
+
   @spec docs_for(atom()) :: String.t()
   def docs_for(type)