wip(metrics): add Metrics support

Author: solnic

lib/sentry.ex

@@ -234,6 +234,17 @@ defmodule Sentry do
           (Sentry.LogEvent.t() -> as_boolean(Sentry.LogEvent.t()))
           | {module(), function_name :: atom()}
 
+  @typedoc """
+  A callback to use with the `:before_send_metric` configuration option.
+
+  If this is `{module, function_name}`, then `module.function_name(metric)` will
+  be called, where `metric` is of type `t:Sentry.Metric.t/0`.
+  """
+  @typedoc since: "13.0.0"
+  @type before_send_metric_callback() ::
+          (Sentry.Metric.t() -> as_boolean(Sentry.Metric.t()))
+          | {module(), function_name :: atom()}
+
   @typedoc """
   The strategy to use when sending an event to Sentry.
   """

lib/sentry/client.ex

@@ -15,6 +15,7 @@ defmodule Sentry.Client do
     Event,
     Interfaces,
     LoggerUtils,
+    Metric,
     Options,
     TelemetryProcessor,
     Transaction,
@@ -144,6 +145,49 @@ defmodule Sentry.Client do
     end
   end
 
+  @spec send_metric(Metric.t()) :: :ok
+  def send_metric(%Metric{} = metric) do
+    result_type = Config.send_result()
+
+    case result_type do
+      :sync ->
+        # Sync mode (used in tests): send directly via transport
+        case Sentry.Test.maybe_collect_metrics([metric]) do
+          :collected ->
+            :ok
+
+          :not_collecting ->
+            if Config.dsn() do
+              client = Config.client()
+
+              request_retries =
+                Application.get_env(:sentry, :request_retries, Transport.default_retries())
+
+              metric
+              |> List.wrap()
+              |> Envelope.from_metric_events()
+              |> Transport.encode_and_post_envelope(client, request_retries)
+            end
+
+            :ok
+        end
+
+      :none ->
+        # Buffered mode (production): add to TelemetryProcessor
+        if Config.telemetry_processor_category?(:metric) do
+          case TelemetryProcessor.add(metric) do
+            {:ok, {:rate_limited, data_category}} ->
+              ClientReport.Sender.record_discarded_events(:ratelimit_backoff, data_category)
+
+            :ok ->
+              :ok
+          end
+        end
+
+        :ok
+    end
+  end
+
   defp sample_event(sample_rate) do
     cond do
       sample_rate == 1 -> :ok

lib/sentry/config.ex

@@ -396,6 +396,17 @@ defmodule Sentry.Config do
       *Available since 12.0.0*.
       """
     ],
+    enable_metrics: [
+      type: :boolean,
+      default: true,
+      doc: """
+      Whether to enable sending metric events to Sentry. When enabled, the SDK will
+      capture and send metrics (counters, gauges, distributions) according to the
+      [Sentry Metrics Protocol](https://develop.sentry.dev/sdk/telemetry/metrics/).
+      Use `Sentry.Metrics` functions to record metrics.
+      *Available since 13.0.0*.
+      """
+    ],
     logs: [
       type: :keyword_list,
       default: [],
@@ -434,8 +445,8 @@ defmodule Sentry.Config do
       ]
     ],
     telemetry_processor_categories: [
-      type: {:list, {:in, [:error, :check_in, :transaction, :log]}},
-      default: [:log],
+      type: {:list, {:in, [:error, :check_in, :transaction, :log, :metric]}},
+      default: [:log, :metric],
       doc: """
       List of event categories that should be processed through the TelemetryProcessor.
       Categories in this list use the TelemetryProcessor's ring buffer and weighted
@@ -447,6 +458,7 @@ defmodule Sentry.Config do
         * `:check_in` - Cron check-ins (high priority, batch_size=1)
         * `:transaction` - Performance transactions (medium priority, batch_size=1)
         * `:log` - Log entries (low priority, batch_size=100, 5s timeout)
+        * `:metric` - Metric events (low priority, batch_size=100, 5s timeout)
 
       *Available since 12.0.0*.
       """
@@ -702,6 +714,17 @@ defmodule Sentry.Config do
       (potentially-updated) `Sentry.LogEvent`, then the updated log event is used instead.
       *Available since v12.0.0*.
       """
+    ],
+    before_send_metric: [
+      type: {:or, [nil, {:fun, 1}, {:tuple, [:atom, :atom]}]},
+      type_doc: "`t:before_send_metric_callback/0`",
+      doc: """
+      Allows performing operations on a metric *before* it is sent, as
+      well as filtering out the metric altogether.
+      If the callback returns `nil` or `false`, the metric is not reported. If it returns a
+      (potentially-updated) `Sentry.Metric`, then the updated metric is used instead.
+      *Available since v13.0.0*.
+      """
     ]
   ]
 
@@ -905,6 +928,9 @@ defmodule Sentry.Config do
   @spec enable_logs?() :: boolean()
   def enable_logs?, do: fetch!(:enable_logs)
 
+  @spec enable_metrics?() :: boolean()
+  def enable_metrics?, do: fetch!(:enable_metrics)
+
   @spec logs() :: keyword()
   def logs, do: fetch!(:logs)
 
@@ -937,6 +963,10 @@ defmodule Sentry.Config do
           (Sentry.LogEvent.t() -> Sentry.LogEvent.t() | nil | false) | {module(), atom()} | nil
   def before_send_log, do: get(:before_send_log)
 
+  @spec before_send_metric() ::
+          (Sentry.Metric.t() -> Sentry.Metric.t() | nil | false) | {module(), atom()} | nil
+  def before_send_metric, do: get(:before_send_metric)
+
   @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

@@ -10,6 +10,8 @@ defmodule Sentry.Envelope do
     Event,
     LogBatch,
     LogEvent,
+    Metric,
+    MetricBatch,
     Transaction,
     UUID
   }
@@ -22,6 +24,7 @@ defmodule Sentry.Envelope do
             | ClientReport.t()
             | Event.t()
             | LogBatch.t()
+            | MetricBatch.t()
             | Transaction.t(),
             ...
           ]
@@ -94,6 +97,25 @@ defmodule Sentry.Envelope do
     }
   end
 
+  @doc """
+  Creates a new envelope containing metric events.
+
+  According to the Sentry Metrics Protocol, metrics are sent in batches
+  within a single envelope item with content type `application/vnd.sentry.items.trace-metric+json`.
+  All metric events are wrapped in a single item with `{ items: [...] }`.
+  """
+  @doc since: "13.0.0"
+  @spec from_metric_events([Metric.t()]) :: t()
+  def from_metric_events(metrics) when is_list(metrics) do
+    # Create a single metric batch item that wraps all metrics
+    metric_batch = %MetricBatch{metrics: metrics}
+
+    %__MODULE__{
+      event_id: UUID.uuid4_hex(),
+      items: [metric_batch]
+    }
+  end
+
   @doc """
   Returns the "data category" of the envelope's contents (to be used in client reports and more).
   """
@@ -104,6 +126,7 @@ defmodule Sentry.Envelope do
           | ClientReport.t()
           | Event.t()
           | LogBatch.t()
+          | MetricBatch.t()
           | Transaction.t()
         ) ::
           String.t()
@@ -113,17 +136,19 @@ defmodule Sentry.Envelope do
   def get_data_category(%ClientReport{}), do: "internal"
   def get_data_category(%Event{}), do: "error"
   def get_data_category(%LogBatch{}), do: "log_item"
+  def get_data_category(%MetricBatch{}), do: "trace_metric"
 
   @doc """
   Returns the total number of payload items in the envelope.
 
-  For log envelopes, this counts individual log events within the LogBatch.
+  For log and metric envelopes, this counts individual items within the batch.
   For other envelope types, each item counts as 1.
   """
   @spec item_count(t()) :: non_neg_integer()
   def item_count(%__MODULE__{items: items}) do
     Enum.reduce(items, 0, fn
       %LogBatch{log_events: log_events}, acc -> acc + length(log_events)
+      %MetricBatch{metrics: metrics}, acc -> acc + length(metrics)
       _other, acc -> acc + 1
     end)
   end
@@ -228,4 +253,24 @@ defmodule Sentry.Envelope do
         throw(error)
     end
   end
+
+  defp item_to_binary(json_library, %MetricBatch{metrics: metrics}) do
+    items = Enum.map(metrics, &Metric.to_map/1)
+    payload = %{items: items}
+
+    case Sentry.JSON.encode(payload, json_library) do
+      {:ok, encoded_payload} ->
+        header = %{
+          "type" => "trace_metric",
+          "item_count" => length(items),
+          "content_type" => "application/vnd.sentry.items.trace-metric+json"
+        }
+
+        {:ok, encoded_header} = Sentry.JSON.encode(header, json_library)
+        [encoded_header, ?\n, encoded_payload, ?\n]
+
+      {:error, _reason} = error ->
+        throw(error)
+    end
+  end
 end

lib/sentry/metric.ex

@@ -0,0 +1,122 @@
+defmodule Sentry.Metric do
+  @moduledoc """
+  Represents a metric that can be sent to Sentry.
+
+  Metrics follow the Sentry Metrics Protocol as defined in:
+  <https://develop.sentry.dev/sdk/telemetry/metrics/>
+
+  This module is used by `Sentry.Metrics` to create and send metric data to Sentry.
+  """
+  @moduledoc since: "13.0.0"
+
+  alias Sentry.Config
+
+  @type metric_type :: :counter | :gauge | :distribution
+
+  @typedoc """
+  A metric struct.
+  """
+  @type t :: %__MODULE__{
+          type: metric_type(),
+          name: String.t(),
+          value: number(),
+          timestamp: float(),
+          trace_id: String.t() | nil,
+          span_id: String.t() | nil,
+          unit: String.t() | nil,
+          attributes: map()
+        }
+
+  @enforce_keys [:type, :name, :value, :timestamp]
+  defstruct [
+    :type,
+    :name,
+    :value,
+    :timestamp,
+    :trace_id,
+    :span_id,
+    :unit,
+    attributes: %{}
+  ]
+
+  @sdk_version Mix.Project.config()[:version]
+
+  @doc """
+  Attaches default attributes to a metric.
+
+  This adds Sentry-specific attributes like environment, release, SDK info, and server name.
+  Per the Sentry Metrics spec, default attributes should be attached before the
+  `before_send_metric` callback is applied (step 5 before step 6).
+  """
+  @spec attach_default_attributes(t()) :: t()
+  def attach_default_attributes(%__MODULE__{} = metric) do
+    default_attrs = %{
+      "sentry.sdk.name" => "sentry.elixir",
+      "sentry.sdk.version" => @sdk_version
+    }
+
+    # Add optional attributes if configured
+    default_attrs =
+      default_attrs
+      |> maybe_put_attr("sentry.environment", Config.environment_name())
+      |> maybe_put_attr("sentry.release", Config.release())
+      |> maybe_put_attr("server.address", Config.server_name())
+
+    # Merge with user attributes (user attributes take precedence)
+    %{metric | attributes: Map.merge(default_attrs, metric.attributes)}
+  end
+
+  defp maybe_put_attr(attrs, _key, nil), do: attrs
+  defp maybe_put_attr(attrs, key, value), do: Map.put(attrs, key, value)
+
+  @doc """
+  Converts a metric to a map suitable for JSON encoding.
+
+  The output matches the Sentry metrics schema with top-level fields: timestamp, type, name,
+  value, unit, trace_id, span_id, and attributes. The attributes are formatted with type
+  information as required by the protocol.
+  """
+  @spec to_map(t()) :: %{optional(atom()) => term()}
+  def to_map(%__MODULE__{} = metric) do
+    %{
+      timestamp: metric.timestamp,
+      type: to_string(metric.type),
+      name: metric.name,
+      value: metric.value,
+      attributes: format_attributes(metric.attributes)
+    }
+    |> maybe_put(:unit, metric.unit)
+    |> maybe_put(:trace_id, metric.trace_id)
+    |> maybe_put(:span_id, metric.span_id)
+  end
+
+  defp maybe_put(map, _key, nil), do: map
+  defp maybe_put(map, key, value), do: Map.put(map, key, value)
+
+  ## Helpers
+
+  # Format attributes to the protocol format with type information
+  defp format_attributes(attributes) when is_map(attributes) do
+    Enum.into(attributes, %{}, fn {key, value} ->
+      safe_value = sanitize_attribute_value(value)
+      {to_string(key), %{value: safe_value, type: attribute_type(safe_value)}}
+    end)
+  end
+
+  # Converts values to JSON-safe attribute types.
+  # Primitives (string, boolean, integer, float) pass through unchanged.
+  # Atoms are converted to strings. All other types (structs, maps, lists,
+  # tuples, PIDs, etc.) are converted to their inspect() representation.
+  # Note: is_boolean must come before is_atom since true/false are atoms
+  defp sanitize_attribute_value(value) when is_binary(value), do: value
+  defp sanitize_attribute_value(value) when is_boolean(value), do: value
+  defp sanitize_attribute_value(value) when is_atom(value), do: Atom.to_string(value)
+  defp sanitize_attribute_value(value) when is_integer(value), do: value
+  defp sanitize_attribute_value(value) when is_float(value), do: value
+  defp sanitize_attribute_value(value), do: inspect(value)
+
+  defp attribute_type(value) when is_boolean(value), do: "boolean"
+  defp attribute_type(value) when is_integer(value), do: "integer"
+  defp attribute_type(value) when is_float(value), do: "double"
+  defp attribute_type(_value), do: "string"
+end

lib/sentry/metric_batch.ex

@@ -0,0 +1,18 @@
+defmodule Sentry.MetricBatch do
+  @moduledoc """
+  A batch of metric events to be sent in a single envelope item.
+
+  According to the Sentry Metrics Protocol, metrics are sent in batches
+  within a single envelope item with content type `application/vnd.sentry.items.trace-metric+json`.
+  """
+  @moduledoc since: "13.0.0"
+
+  alias Sentry.Metric
+
+  @type t() :: %__MODULE__{
+          metrics: [Metric.t()]
+        }
+
+  @enforce_keys [:metrics]
+  defstruct [:metrics]
+end