feat(sentry-core): Implement trace metric capture batching (#1026)

Basic metrics capture functionality. Follow-up PR will implement the rest.

Closes #1023
Closes [RUST-168](https://linear.app/getsentry/issue/RUST-168/implement-trace-metric-capture-and-batching-in-sentry-core)

Author: szokeasaurusrex

CHANGELOG.md

@@ -10,6 +10,8 @@
 
 - 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 `TraceMetric` and `TraceMetricType` types representing [trace metrics](https://develop.sentry.dev/sdk/telemetry/metrics/) ([#1026](https://github.com/getsentry/sentry-rust/pull/1026)).
+- Add trace metric capture and batching in `sentry-core`. Metrics can be captured via `Hub::capture_metric` and are batched and sent as `trace_metric` envelope items. Controlled by the `metrics` feature flag and `ClientOptions::enable_metrics` ([#1026](https://github.com/getsentry/sentry-rust/pull/1026)).
 - Expose transport utilities ([#949](https://github.com/getsentry/sentry-rust/pull/949))
 
 ### Fixes

sentry-core/Cargo.toml

@@ -25,6 +25,7 @@ client = ["rand"]
 test = ["client", "release-health"]
 release-health = []
 logs = []
+metrics = []
 
 [dependencies]
 log = { version = "0.4.8", optional = true, features = ["std"] }

sentry-core/src/batcher.rs

@@ -8,6 +8,8 @@ use crate::client::TransportArc;
 use crate::protocol::EnvelopeItem;
 use crate::Envelope;
 use sentry_types::protocol::v7::Log;
+#[cfg(feature = "metrics")]
+use sentry_types::protocol::v7::TraceMetric;
 
 // Flush when there's 100 items in the buffer
 const MAX_ITEMS: usize = 100;
@@ -40,6 +42,11 @@ impl Batch for Log {
     const TYPE_NAME: &str = "logs";
 }
 
+#[cfg(feature = "metrics")]
+impl Batch for TraceMetric {
+    const TYPE_NAME: &str = "metrics";
+}
+
 /// Accumulates items in the queue and submits them through the transport when one of the flushing
 /// conditions is met.
 pub(crate) struct Batcher<T: Batch> {

sentry-core/src/client.rs

@@ -12,7 +12,7 @@ use crate::protocol::SessionUpdate;
 use rand::random;
 use sentry_types::random_uuid;
 
-#[cfg(feature = "logs")]
+#[cfg(any(feature = "logs", feature = "metrics"))]
 use crate::batcher::Batcher;
 use crate::constants::SDK_INFO;
 use crate::protocol::{ClientSdkInfo, Event};
@@ -24,6 +24,8 @@ use crate::SessionMode;
 use crate::{ClientOptions, Envelope, Hub, Integration, Scope, Transport};
 #[cfg(feature = "logs")]
 use sentry_types::protocol::v7::Context;
+#[cfg(feature = "metrics")]
+use sentry_types::protocol::v7::TraceMetric;
 #[cfg(feature = "logs")]
 use sentry_types::protocol::v7::{Log, LogAttribute};
 
@@ -59,6 +61,8 @@ pub struct Client {
     session_flusher: RwLock<Option<SessionFlusher>>,
     #[cfg(feature = "logs")]
     logs_batcher: RwLock<Option<Batcher<Log>>>,
+    #[cfg(feature = "metrics")]
+    metrics_batcher: RwLock<Option<Batcher<TraceMetric>>>,
     #[cfg(feature = "logs")]
     default_log_attributes: Option<BTreeMap<String, LogAttribute>>,
     integrations: Vec<(TypeId, Arc<dyn Integration>)>,
@@ -91,13 +95,22 @@ impl Clone for Client {
             None
         });
 
+        #[cfg(feature = "metrics")]
+        let metrics_batcher = RwLock::new(if self.options.enable_metrics {
+            Some(Batcher::new(transport.clone()))
+        } else {
+            None
+        });
+
         Client {
             options: self.options.clone(),
             transport,
             #[cfg(feature = "release-health")]
             session_flusher,
             #[cfg(feature = "logs")]
             logs_batcher,
+            #[cfg(feature = "metrics")]
+            metrics_batcher,
             #[cfg(feature = "logs")]
             default_log_attributes: self.default_log_attributes.clone(),
             integrations: self.integrations.clone(),
@@ -176,6 +189,13 @@ impl Client {
             None
         });
 
+        #[cfg(feature = "metrics")]
+        let metrics_batcher = RwLock::new(if options.enable_metrics {
+            Some(Batcher::new(transport.clone()))
+        } else {
+            None
+        });
+
         #[allow(unused_mut)]
         let mut client = Client {
             options,
@@ -184,6 +204,8 @@ impl Client {
             session_flusher,
             #[cfg(feature = "logs")]
             logs_batcher,
+            #[cfg(feature = "metrics")]
+            metrics_batcher,
             #[cfg(feature = "logs")]
             default_log_attributes: None,
             integrations,
@@ -420,6 +442,10 @@ impl Client {
         if let Some(ref batcher) = *self.logs_batcher.read().unwrap() {
             batcher.flush();
         }
+        #[cfg(feature = "metrics")]
+        if let Some(ref batcher) = *self.metrics_batcher.read().unwrap() {
+            batcher.flush();
+        }
         if let Some(ref transport) = *self.transport.read().unwrap() {
             transport.flush(timeout.unwrap_or(self.options.shutdown_timeout))
         } else {
@@ -439,6 +465,8 @@ impl Client {
         drop(self.session_flusher.write().unwrap().take());
         #[cfg(feature = "logs")]
         drop(self.logs_batcher.write().unwrap().take());
+        #[cfg(feature = "metrics")]
+        drop(self.metrics_batcher.write().unwrap().take());
         let transport_opt = self.transport.write().unwrap().take();
         if let Some(transport) = transport_opt {
             sentry_debug!("client close; request transport to shut down");
@@ -493,6 +521,20 @@ impl Client {
 
         Some(log)
     }
+
+    /// Captures a trace metric and sends it to Sentry.
+    #[cfg(feature = "metrics")]
+    pub fn capture_metric(&self, metric: TraceMetric, _: &Scope) {
+        // TODO: Read scope
+        if let Some(batcher) = self
+            .metrics_batcher
+            .read()
+            .expect("metrics batcher lock could not be acquired")
+            .as_ref()
+        {
+            batcher.enqueue(metric);
+        }
+    }
 }
 
 // Make this unwind safe. It's not out of the box because of the

sentry-core/src/clientoptions.rs

@@ -172,6 +172,9 @@ pub struct ClientOptions {
     /// Determines whether captured structured logs should be sent to Sentry (defaults to false).
     #[cfg(feature = "logs")]
     pub enable_logs: bool,
+    /// Determines whether captured trace metrics should be sent to Sentry (defaults to true).
+    #[cfg(feature = "metrics")]
+    pub enable_metrics: bool,
     // Other options not documented in Unified API
     /// Disable SSL verification.
     ///
@@ -278,6 +281,9 @@ impl fmt::Debug for ClientOptions {
             .field("enable_logs", &self.enable_logs)
             .field("before_send_log", &before_send_log);
 
+        #[cfg(feature = "metrics")]
+        debug_struct.field("enable_metrics", &self.enable_metrics);
+
         debug_struct.field("user_agent", &self.user_agent).finish()
     }
 }
@@ -317,6 +323,8 @@ impl Default for ClientOptions {
             enable_logs: true,
             #[cfg(feature = "logs")]
             before_send_log: None,
+            #[cfg(feature = "metrics")]
+            enable_metrics: false,
         }
     }
 }

sentry-core/src/hub.rs

@@ -4,6 +4,8 @@
 
 use std::sync::{Arc, RwLock};
 
+#[cfg(feature = "metrics")]
+use crate::protocol::TraceMetric;
 use crate::protocol::{Event, Level, Log, LogAttribute, LogLevel, Map, SessionStatus};
 use crate::types::Uuid;
 use crate::{Integration, IntoBreadcrumbs, Scope, ScopeGuard};
@@ -255,4 +257,14 @@ impl Hub {
             client.capture_log(log, &top.scope);
         }}
     }
+
+    /// Captures a trace metric.
+    #[cfg(feature = "metrics")]
+    pub fn capture_metric(&self, metric: TraceMetric) {
+        with_client_impl! {{
+            let top = self.inner.with(|stack| stack.top().clone());
+            let Some(ref client) = top.client else { return };
+            client.capture_metric(metric, &top.scope);
+        }}
+    }
 }

sentry-core/src/lib.rs

@@ -136,7 +136,7 @@ pub use crate::transport::{Transport, TransportFactory};
 mod logger; // structured logging macros exported with `#[macro_export]`
 
 // client feature
-#[cfg(all(feature = "client", feature = "logs"))]
+#[cfg(all(feature = "client", any(feature = "logs", feature = "metrics")))]
 mod batcher;
 #[cfg(feature = "client")]
 mod client;