Introduce Logs handler for structured logging

Author: solnic

lib/sentry/application.ex

@@ -34,6 +34,13 @@ defmodule Sentry.Application do
         []
       end
 
+    maybe_log_event_buffer =
+      if Config.enabled_logs?() do
+        [Sentry.LogEventBuffer]
+      else
+        []
+      end
+
     children =
       [
         {Registry, keys: :unique, name: Sentry.Transport.SenderRegistry},
@@ -48,6 +55,7 @@ defmodule Sentry.Application do
       ] ++
         maybe_http_client_spec ++
         maybe_span_storage ++
+        maybe_log_event_buffer ++
         maybe_rate_limiter() ++
         [Sentry.Transport.SenderPool]
 

lib/sentry/client.ex

@@ -14,6 +14,7 @@ defmodule Sentry.Client do
     Envelope,
     Event,
     Interfaces,
+    LogEvent,
     LoggerUtils,
     Options,
     Transaction,
@@ -134,6 +135,36 @@ defmodule Sentry.Client do
     end
   end
 
+  @doc """
+  Sends a batch of log events to Sentry.
+
+  Log events are sent asynchronously and do not support callbacks or sampling.
+  They are buffered and sent in batches according to the Sentry Logs Protocol.
+
+  Returns `{:ok, envelope_id}` on success or `{:error, reason}` on failure.
+  """
+  @doc since: "12.0.0"
+  @spec send_log_events([LogEvent.t()]) ::
+          {:ok, envelope_id :: String.t()} | {:error, ClientError.t()}
+  def send_log_events([]), do: {:ok, ""}
+
+  def send_log_events(log_events) when is_list(log_events) do
+    case Sentry.Test.maybe_collect_logs(log_events) do
+      :collected ->
+        {:ok, ""}
+
+      :not_collecting ->
+        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
+  end
+
   defp sample_event(sample_rate) do
     cond do
       sample_rate == 1 -> :ok

lib/sentry/config.ex

@@ -362,6 +362,27 @@ defmodule Sentry.Config do
       """,
       default: [],
       keys: integrations_schema
+    ],
+    enabled_logs: [
+      type: :boolean,
+      default: false,
+      doc: """
+      Whether to enable sending log events to Sentry. When enabled, the SDK will
+      capture and send structured log events according to the
+      [Sentry Logs Protocol](https://develop.sentry.dev/sdk/telemetry/logs/).
+      Use `Sentry.LogsHandler` to capture log events from Erlang's `:logger`.
+      """
+    ],
+    max_log_events: [
+      type: :non_neg_integer,
+      default: 100,
+      doc: """
+      The maximum number of log events to buffer before flushing to Sentry.
+      Log events are buffered and sent in batches to reduce network overhead.
+      When the buffer reaches this size, it will be flushed immediately.
+      Otherwise, logs are flushed every 5 seconds. Only applies when `:enabled_logs`
+      is `true`.
+      """
     ]
   ]
 
@@ -778,6 +799,12 @@ defmodule Sentry.Config do
        not is_nil(fetch!(:traces_sample_rate))) or not is_nil(get(:traces_sampler))
   end
 
+  @spec enabled_logs?() :: boolean()
+  def enabled_logs?, do: fetch!(:enabled_logs)
+
+  @spec max_log_events() :: non_neg_integer()
+  def max_log_events, do: fetch!(:max_log_events)
+
   @spec put_config(atom(), term()) :: :ok
   def put_config(key, value) when is_atom(key) do
     unless key in @valid_keys do

lib/sentry/envelope.ex

@@ -8,14 +8,26 @@ defmodule Sentry.Envelope do
     ClientReport,
     Config,
     Event,
+    LogEvent,
     Transaction,
     UUID
   }
 
+  @typep log_batch() :: %{
+           __struct__: :log_batch,
+           log_events: [LogEvent.t()]
+         }
+
   @type t() :: %__MODULE__{
           event_id: UUID.t(),
           items: [
-            Attachment.t() | CheckIn.t() | ClientReport.t() | Event.t() | Transaction.t(),
+            Attachment.t()
+            | CheckIn.t()
+            | ClientReport.t()
+            | Event.t()
+            | log_batch()
+            | LogEvent.t()
+            | Transaction.t(),
             ...
           ]
         }
@@ -68,6 +80,28 @@ defmodule Sentry.Envelope do
     }
   end
 
+  @doc """
+  Creates a new envelope containing log events.
+
+  According to the Sentry Logs Protocol, log events are sent in batches
+  within a single envelope item with content_type "application/vnd.sentry.items.log+json".
+  All log events are wrapped in a single item with { items: [...] }.
+  """
+  @doc since: "11.0.0"
+  @spec from_log_events([LogEvent.t()]) :: t()
+  def from_log_events(log_events) when is_list(log_events) do
+    # Create a single log batch item that wraps all log events
+    log_batch = %{
+      __struct__: :log_batch,
+      log_events: log_events
+    }
+
+    %__MODULE__{
+      event_id: UUID.uuid4_hex(),
+      items: [log_batch]
+    }
+  end
+
   @doc """
   Returns the "data category" of the envelope's contents (to be used in client reports and more).
   """
@@ -77,6 +111,8 @@ defmodule Sentry.Envelope do
           | CheckIn.t()
           | ClientReport.t()
           | Event.t()
+          | log_batch()
+          | LogEvent.t()
           | Transaction.t()
         ) ::
           String.t()
@@ -85,6 +121,7 @@ defmodule Sentry.Envelope do
   def get_data_category(%CheckIn{}), do: "monitor"
   def get_data_category(%ClientReport{}), do: "internal"
   def get_data_category(%Event{}), do: "error"
+  def get_data_category(%{__struct__: :log_batch}), do: "log_item"
 
   @doc """
   Encodes the envelope into its binary representation.
@@ -166,4 +203,24 @@ defmodule Sentry.Envelope do
         throw(error)
     end
   end
+
+  defp item_to_binary(json_library, %{__struct__: :log_batch, log_events: log_events}) do
+    items = Enum.map(log_events, &LogEvent.to_map/1)
+    payload = %{items: items}
+
+    case Sentry.JSON.encode(payload, json_library) do
+      {:ok, encoded_payload} ->
+        header = %{
+          "type" => "log",
+          "item_count" => length(items),
+          "content_type" => "application/vnd.sentry.items.log+json"
+        }
+
+        {:ok, encoded_header} = Sentry.JSON.encode(header, json_library)
+        [encoded_header, ?\n, encoded_payload, ?\n]
+
+      {:error, _reason} = error ->
+        throw(error)
+    end
+  end
 end