feat(sentry-types): Add metric protocol envelope support (#1022)

Add `Metric` protocol types and `trace_metric` envelope container serialization/deserialization in `sentry-types`.

Closes #1008
Closes [RUST-159](https://linear.app/getsentry/issue/RUST-159/add-trace-metric-protocol-models-and-envelope-item-container-support)

Co-authored-by: Joris Bayer <joris.bayer@sentry.io>
Co-authored-by: Lorenzo Cian <17258265+lcian@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -9,6 +9,8 @@
 ### New Features
 
 - Added a `Envelope::into_items` method, which returns an iterator over owned [`EnvelopeItem`s](https://docs.rs/sentry/0.46.2/sentry/protocol/enum.EnvelopeItem.html) in the [`Envelope`](https://docs.rs/sentry/0.46.2/sentry/struct.Envelope.html) ([#983](https://github.com/getsentry/sentry-rust/pull/983)).
+- Add SDK protocol support for sending `trace_metric` envelope items ([#1022](https://github.com/getsentry/sentry-rust/pull/1022)).
+- Add `Metric` and `MetricType` types representing [trace metrics](https://develop.sentry.dev/sdk/telemetry/metrics/) ([#1026](https://github.com/getsentry/sentry-rust/pull/1026)).
 - Expose transport utilities ([#949](https://github.com/getsentry/sentry-rust/pull/949))
 
 ### Fixes

sentry-types/src/protocol/envelope.rs

@@ -10,8 +10,8 @@ use crate::Dsn;
 use super::v7 as protocol;
 
 use protocol::{
-    Attachment, AttachmentType, ClientSdkInfo, DynamicSamplingContext, Event, Log, MonitorCheckIn,
-    SessionAggregates, SessionUpdate, Transaction,
+    Attachment, AttachmentType, ClientSdkInfo, DynamicSamplingContext, Event, Log, Metric,
+    MonitorCheckIn, SessionAggregates, SessionUpdate, Transaction,
 };
 
 /// Raised if a envelope cannot be parsed from a given input.
@@ -127,6 +127,10 @@ enum EnvelopeItemType {
     /// A container of Log items.
     #[serde(rename = "log")]
     LogsContainer,
+    /// A container of Metric items.
+    /// Serialized to a `trace_metric` envelope item.
+    #[serde(rename = "trace_metric")]
+    MetricsContainer,
 }
 
 /// An Envelope Item Header.
@@ -192,6 +196,8 @@ pub enum EnvelopeItem {
 pub enum ItemContainer {
     /// A list of logs.
     Logs(Vec<Log>),
+    /// A list of metrics.
+    Metrics(Vec<Metric>),
 }
 
 #[allow(clippy::len_without_is_empty, reason = "is_empty is not needed")]
@@ -200,20 +206,23 @@ impl ItemContainer {
     pub fn len(&self) -> usize {
         match self {
             Self::Logs(logs) => logs.len(),
+            Self::Metrics(metrics) => metrics.len(),
         }
     }
 
     /// The `type` of this item container, which corresponds to the `type` of the contained items.
     pub fn ty(&self) -> &'static str {
         match self {
             Self::Logs(_) => "log",
+            Self::Metrics(_) => "trace_metric",
         }
     }
 
     /// The `content-type` expected by Relay for this item container.
     pub fn content_type(&self) -> &'static str {
         match self {
             Self::Logs(_) => "application/vnd.sentry.items.log+json",
+            Self::Metrics(_) => "application/vnd.sentry.items.trace-metric+json",
         }
     }
 }
@@ -235,6 +244,12 @@ struct ItemsSerdeWrapper<'a, T: Clone> {
     items: Cow<'a, [T]>,
 }
 
+impl From<Vec<Metric>> for ItemContainer {
+    fn from(metrics: Vec<Metric>) -> Self {
+        Self::Metrics(metrics)
+    }
+}
+
 impl From<Event<'static>> for EnvelopeItem {
     fn from(event: Event<'static>) -> Self {
         EnvelopeItem::Event(event)
@@ -283,6 +298,12 @@ impl From<Vec<Log>> for EnvelopeItem {
     }
 }
 
+impl From<Vec<Metric>> for EnvelopeItem {
+    fn from(metrics: Vec<Metric>) -> Self {
+        EnvelopeItem::ItemContainer(metrics.into())
+    }
+}
+
 /// An Iterator over the items of an Envelope.
 #[derive(Clone)]
 pub struct EnvelopeItemIter<'s> {
@@ -506,6 +527,12 @@ impl Envelope {
                         let wrapper = ItemsSerdeWrapper { items: logs.into() };
                         serde_json::to_writer(&mut item_buf, &wrapper)?
                     }
+                    ItemContainer::Metrics(metrics) => {
+                        let wrapper = ItemsSerdeWrapper {
+                            items: metrics.into(),
+                        };
+                        serde_json::to_writer(&mut item_buf, &wrapper)?
+                    }
                 },
                 EnvelopeItem::Raw => {
                     continue;
@@ -677,6 +704,10 @@ impl Envelope {
                 serde_json::from_slice::<ItemsSerdeWrapper<_>>(payload)
                     .map(|x| EnvelopeItem::ItemContainer(ItemContainer::Logs(x.items.into())))
             }
+            EnvelopeItemType::MetricsContainer => {
+                serde_json::from_slice::<ItemsSerdeWrapper<_>>(payload)
+                    .map(|x| EnvelopeItem::ItemContainer(ItemContainer::Metrics(x.items.into())))
+            }
         }
         .map_err(EnvelopeError::InvalidItemPayload)?;
 
@@ -708,6 +739,7 @@ mod test {
     use std::time::{Duration, SystemTime};
 
     use protocol::Map;
+    use serde_json::Value;
     use time::format_description::well_known::Rfc3339;
     use time::OffsetDateTime;
 
@@ -1121,6 +1153,49 @@ some content
         assert_eq!(expected, serialized.as_bytes());
     }
 
+    #[test]
+    fn test_metric_container_header() {
+        let metrics: EnvelopeItem = vec![Metric {
+            r#type: protocol::MetricType::Counter,
+            name: "api.requests".into(),
+            value: 1.0,
+            timestamp: timestamp("2026-03-02T13:36:02.000Z"),
+            trace_id: "335e53d614474acc9f89e632b776cc28".parse().unwrap(),
+            span_id: None,
+            unit: None,
+            attributes: Map::new(),
+        }]
+        .into();
+
+        let mut envelope = Envelope::new();
+        envelope.add_item(metrics);
+
+        let expected = [
+            serde_json::json!({}),
+            serde_json::json!({
+                "type": "trace_metric",
+                "item_count": 1,
+                "content_type": "application/vnd.sentry.items.trace-metric+json"
+            }),
+            serde_json::json!({
+                "items": [{
+                    "type": "counter",
+                    "name": "api.requests",
+                    "value": 1.0,
+                    "timestamp": 1772458562,
+                    "trace_id": "335e53d614474acc9f89e632b776cc28"
+                }]
+            }),
+        ];
+
+        let serialized = to_str(envelope);
+        let actual = serialized
+            .lines()
+            .map(|line| serde_json::from_str::<Value>(line).expect("envelope has invalid JSON"));
+
+        assert!(actual.eq(expected.into_iter()));
+    }
+
     // Test all possible item types in a single envelope
     #[test]
     fn test_deserialize_serialized() {
@@ -1197,12 +1272,27 @@ some content
         ]
         .into();
 
+        let mut metric_attributes = Map::new();
+        metric_attributes.insert("route".into(), "/users".into());
+        let metrics: EnvelopeItem = vec![Metric {
+            r#type: protocol::MetricType::Distribution,
+            name: "response.time".to_owned(),
+            value: 123.4,
+            timestamp: timestamp("2022-07-26T14:51:14.296Z"),
+            trace_id: "335e53d614474acc9f89e632b776cc28".parse().unwrap(),
+            span_id: Some("d42cee9fc3e74f5c".parse().unwrap()),
+            unit: Some("millisecond".to_owned()),
+            attributes: metric_attributes,
+        }]
+        .into();
+
         let mut envelope: Envelope = Envelope::new();
         envelope.add_item(event);
         envelope.add_item(transaction);
         envelope.add_item(session);
         envelope.add_item(attachment);
         envelope.add_item(logs);
+        envelope.add_item(metrics);
 
         let serialized = to_str(envelope);
         let deserialized = Envelope::from_slice(serialized.as_bytes()).unwrap();

sentry-types/src/protocol/v7.rs

@@ -2368,6 +2368,45 @@ impl<'de> Deserialize<'de> for LogAttribute {
     }
 }
 
+/// The type of a [metric](https://develop.sentry.dev/sdk/telemetry/metrics/).
+#[derive(Serialize, Deserialize, Copy, Clone, Debug, PartialEq)]
+#[serde(rename_all = "lowercase")]
+#[non_exhaustive]
+pub enum MetricType {
+    /// A counter metric that only increments.
+    Counter,
+    /// A gauge metric that can go up and down.
+    Gauge,
+    /// A distribution metric for statistical spread measurements.
+    Distribution,
+}
+
+/// A single [metric](https://develop.sentry.dev/sdk/telemetry/metrics/).
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
+#[non_exhaustive]
+pub struct Metric {
+    /// The metric type.
+    pub r#type: MetricType,
+    /// The metric name. Uses dot separators for hierarchy.
+    pub name: String,
+    /// The numeric value.
+    pub value: f64,
+    /// The timestamp when recorded.
+    #[serde(with = "ts_seconds_float")]
+    pub timestamp: SystemTime,
+    /// The trace ID this metric is associated with.
+    pub trace_id: TraceId,
+    /// The span ID of the active span, if any.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub span_id: Option<SpanId>,
+    /// The measurement unit.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub unit: Option<String>,
+    /// Additional key-value attributes.
+    #[serde(default, skip_serializing_if = "Map::is_empty")]
+    pub attributes: Map<String, LogAttribute>,
+}
+
 /// An ID that identifies an organization in the Sentry backend.
 #[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq)]
 pub struct OrganizationId(u64);