# This is a combination of 6 commits.

# This is the 1st commit message:

feat(metrics): Add trace metric enrichment with default and user attributes (RUST-169)

Add metric enrichment in sentry-core so emitted trace metrics include:

- Trace/span association: trace_id from active span or propagation
  context, span_id from active span when not explicitly set.
- Default SDK attributes: sentry.environment, sentry.release,
  sentry.sdk.name, sentry.sdk.version, and server.address.
- User PII attributes (user.id, user.name, user.email) gated by
  send_default_pii.
- before_send_metric callback for filtering/modifying metrics.

Attribute merges use or_insert to preserve explicitly set metric
attributes, matching the behavior specified in
https://develop.sentry.dev/sdk/telemetry/metrics/#default-attributes
and https://develop.sentry.dev/sdk/telemetry/metrics/#user-attributes.

Scope and client enrichment logic is based on the approach from #997.

Co-authored-by: Joris Bayer <joris.bayer@sentry.io>

Closes #1024
Closes [RUST-169](https://linear.app/getsentry/issue/RUST-169/add-trace-metric-default-and-user-attribute-enrichment-in-sentry-core)

Author: szokeasaurusrex

sentry-core/src/client.rs

@@ -1,6 +1,6 @@
 use std::any::TypeId;
 use std::borrow::Cow;
-#[cfg(feature = "logs")]
+#[cfg(any(feature = "logs", feature = "metrics"))]
 use std::collections::BTreeMap;
 use std::fmt;
 use std::panic::RefUnwindSafe;
@@ -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(all(feature = "metrics", not(feature = "logs")))]
+use sentry_types::protocol::v7::LogAttribute;
 #[cfg(feature = "metrics")]
 use sentry_types::protocol::v7::Metric;
 #[cfg(feature = "logs")]
@@ -65,6 +67,8 @@ pub struct Client {
     metrics_batcher: RwLock<Option<Batcher<Metric>>>,
     #[cfg(feature = "logs")]
     default_log_attributes: Option<BTreeMap<String, LogAttribute>>,
+    #[cfg(feature = "metrics")]
+    default_metric_attributes: BTreeMap<Cow<'static, str>, LogAttribute>,
     integrations: Vec<(TypeId, Arc<dyn Integration>)>,
     pub(crate) sdk_info: ClientSdkInfo,
 }
@@ -113,6 +117,8 @@ impl Clone for Client {
             metrics_batcher,
             #[cfg(feature = "logs")]
             default_log_attributes: self.default_log_attributes.clone(),
+            #[cfg(feature = "metrics")]
+            default_metric_attributes: self.default_metric_attributes.clone(),
             integrations: self.integrations.clone(),
             sdk_info: self.sdk_info.clone(),
         }
@@ -208,13 +214,18 @@ impl Client {
             metrics_batcher,
             #[cfg(feature = "logs")]
             default_log_attributes: None,
+            #[cfg(feature = "metrics")]
+            default_metric_attributes: Default::default(),
             integrations,
             sdk_info,
         };
 
         #[cfg(feature = "logs")]
         client.cache_default_log_attributes();
 
+        #[cfg(feature = "metrics")]
+        client.cache_default_metric_attributes();
+
         client
     }
 
@@ -269,6 +280,28 @@ impl Client {
         self.default_log_attributes = Some(attributes);
     }
 
+    #[cfg(feature = "metrics")]
+    fn cache_default_metric_attributes(&mut self) {
+        let always_present_attributes = [
+            ("sentry.sdk.name", &self.sdk_info.name),
+            ("sentry.sdk.version", &self.sdk_info.version),
+        ]
+        .into_iter()
+        .map(|(name, value)| (name.into(), value.as_str().into()));
+
+        let maybe_present_attributes = [
+            ("sentry.environment", &self.options.environment),
+            ("sentry.release", &self.options.release),
+            ("server.address", &self.options.server_name),
+        ]
+        .into_iter()
+        .filter_map(|(name, value)| value.clone().map(|value| (name.into(), value.into())));
+
+        self.default_metric_attributes = maybe_present_attributes
+            .chain(always_present_attributes)
+            .collect();
+    }
+
     pub(crate) fn get_integration<I>(&self) -> Option<&I>
     where
         I: Integration,
@@ -524,15 +557,34 @@ impl Client {
 
     /// Captures a metric and sends it to Sentry.
     #[cfg(feature = "metrics")]
-    pub fn capture_metric(&self, metric: Metric, _: &Scope) {
-        if let Some(batcher) = self
-            .metrics_batcher
-            .read()
-            .expect("metrics batcher lock could not be acquired")
-            .as_ref()
-        {
-            batcher.enqueue(metric);
+    pub fn capture_metric(&self, metric: Metric, scope: &Scope) {
+        if let Some(metric) = self.prepare_metric(metric, scope) {
+            if let Some(batcher) = self
+                .metrics_batcher
+                .read()
+                .expect("metrics batcher lock could not be acquired")
+                .as_ref()
+            {
+                batcher.enqueue(metric);
+            }
+        }
+    }
+
+    /// Prepares a metric to be sent, setting the `trace_id` and other default attributes, and
+    /// processing it through `before_send_metric`.
+    #[cfg(feature = "metrics")]
+    fn prepare_metric(&self, mut metric: Metric, scope: &Scope) -> Option<Metric> {
+        scope.apply_to_metric(&mut metric, self.options.send_default_pii);
+
+        for (key, val) in &self.default_metric_attributes {
+            metric.attributes.entry(key.clone()).or_insert(val.clone());
         }
+
+        if let Some(ref func) = self.options.before_send_metric {
+            metric = func(metric)?;
+        }
+
+        Some(metric)
     }
 }
 

sentry-core/src/clientoptions.rs

@@ -7,6 +7,8 @@ use crate::constants::USER_AGENT;
 use crate::performance::TracesSampler;
 #[cfg(feature = "logs")]
 use crate::protocol::Log;
+#[cfg(feature = "metrics")]
+use crate::protocol::Metric;
 use crate::protocol::{Breadcrumb, Event};
 use crate::types::Dsn;
 use crate::{Integration, IntoDsn, TransportFactory};
@@ -175,6 +177,9 @@ pub struct ClientOptions {
     /// Determines whether captured metrics should be sent to Sentry (defaults to false).
     #[cfg(feature = "metrics")]
     pub enable_metrics: bool,
+    /// Callback that is executed for each Metric before sending.
+    #[cfg(feature = "metrics")]
+    pub before_send_metric: Option<BeforeCallback<Metric>>,
     // Other options not documented in Unified API
     /// Disable SSL verification.
     ///
@@ -235,6 +240,12 @@ impl fmt::Debug for ClientOptions {
             struct BeforeSendLog;
             self.before_send_log.as_ref().map(|_| BeforeSendLog)
         };
+        #[cfg(feature = "metrics")]
+        let before_send_metric = {
+            #[derive(Debug)]
+            struct BeforeSendMetric;
+            self.before_send_metric.as_ref().map(|_| BeforeSendMetric)
+        };
         #[derive(Debug)]
         struct TransportFactory;
 
@@ -282,7 +293,9 @@ impl fmt::Debug for ClientOptions {
             .field("before_send_log", &before_send_log);
 
         #[cfg(feature = "metrics")]
-        debug_struct.field("enable_metrics", &self.enable_metrics);
+        debug_struct
+            .field("enable_metrics", &self.enable_metrics)
+            .field("before_send_metric", &before_send_metric);
 
         debug_struct.field("user_agent", &self.user_agent).finish()
     }
@@ -325,6 +338,8 @@ impl Default for ClientOptions {
             before_send_log: None,
             #[cfg(feature = "metrics")]
             enable_metrics: false,
+            #[cfg(feature = "metrics")]
+            before_send_metric: None,
         }
     }
 }

sentry-core/src/performance.rs

@@ -586,6 +586,15 @@ impl TransactionOrSpan {
             TransactionOrSpan::Span(span) => span.finish(),
         }
     }
+
+    /// Get the span ID of this [`TransactionOrSpan`].
+    #[cfg(feature = "metrics")]
+    pub(crate) fn span_id(&self) -> SpanId {
+        match self {
+            TransactionOrSpan::Transaction(transaction) => transaction.get_trace_context().span_id,
+            TransactionOrSpan::Span(span) => span.get_span_id(),
+        }
+    }
 }
 
 #[derive(Debug)]

sentry-core/src/scope/noop.rs

@@ -2,6 +2,8 @@ use std::fmt;
 
 #[cfg(feature = "logs")]
 use crate::protocol::Log;
+#[cfg(feature = "metrics")]
+use crate::protocol::Metric;
 use crate::protocol::{Context, Event, Level, User, Value};
 use crate::TransactionOrSpan;
 
@@ -119,6 +121,14 @@ impl Scope {
         minimal_unreachable!();
     }
 
+    /// Applies the contained scoped data to fill a trace metric.
+    #[cfg(feature = "metrics")]
+    pub fn apply_to_metric(&self, metric: &mut Metric, send_default_pii: bool) {
+        let _metric = metric;
+        let _send_default_pii = send_default_pii;
+        minimal_unreachable!();
+    }
+
     /// Set the given [`TransactionOrSpan`] as the active span for this scope.
     pub fn set_span(&mut self, span: Option<TransactionOrSpan>) {
         let _ = span;

sentry-core/src/scope/real.rs

@@ -6,11 +6,15 @@ use std::sync::Mutex;
 use std::sync::{Arc, PoisonError, RwLock};
 
 use crate::performance::TransactionOrSpan;
+#[cfg(feature = "logs")]
+use crate::protocol::Log;
+#[cfg(any(feature = "logs", feature = "metrics"))]
+use crate::protocol::LogAttribute;
+#[cfg(feature = "metrics")]
+use crate::protocol::Metric;
 use crate::protocol::{
     Attachment, Breadcrumb, Context, Event, Level, TraceContext, Transaction, User, Value,
 };
-#[cfg(feature = "logs")]
-use crate::protocol::{Log, LogAttribute};
 #[cfg(feature = "release-health")]
 use crate::session::Session;
 use crate::{Client, SentryTrace, TraceHeader, TraceHeadersIter};
@@ -399,6 +403,28 @@ impl Scope {
         }
     }
 
+    /// Applies the contained scoped data to a trace metric, setting the `trace_id`, `span_id`,
+    /// and certain default attributes. User PII attributes are only attached when
+    /// `send_default_pii` is `true`.
+    #[cfg(feature = "metrics")]
+    pub fn apply_to_metric(&self, metric: &mut Metric, send_default_pii: bool) {
+        metric.trace_id = (*self.span)
+            .as_ref()
+            .map(|span| span.get_trace_context().trace_id)
+            .unwrap_or(self.propagation_context.trace_id);
+
+        metric.span_id = self.get_span().map(|ts| ts.span_id());
+
+        let should_add_user_attributes = send_default_pii && !metric.has_any_user_attributes();
+
+        if let Some(user) = should_add_user_attributes
+            .then_some(self.user.as_deref())
+            .flatten()
+        {
+            metric.apply_user_attributes(user);
+        }
+    }
+
     /// Set the given [`TransactionOrSpan`] as the active span for this scope.
     pub fn set_span(&mut self, span: Option<TransactionOrSpan>) {
         self.span = Arc::new(span);
@@ -444,3 +470,48 @@ impl Scope {
         }
     }
 }
+
+#[cfg(feature = "metrics")]
+trait MetricExt {
+    fn insert_attribute<K, V>(&mut self, key: K, value: V)
+    where
+        K: Into<Cow<'static, str>>,
+        V: Into<Value>;
+
+    fn attribute(&self, key: &str) -> Option<&LogAttribute>;
+
+    /// Applies user attributes from provided [`User`].
+    fn apply_user_attributes(&mut self, user: &User) {
+        [
+            ("user.id", user.id.as_deref()),
+            ("user.name", user.username.as_deref()),
+            ("user.email", user.email.as_deref()),
+        ]
+        .into_iter()
+        .flat_map(|(attribute, value)| value.map(|v| (attribute, v)))
+        .for_each(|(attribute, value)| self.insert_attribute(attribute, value));
+    }
+
+    /// Checks if any user attributes are on this metric
+    fn has_any_user_attributes(&self) -> bool {
+        ["user.id", "user.name", "user.email"]
+            .into_iter()
+            .any(|key| self.attribute(key).is_some())
+    }
+}
+
+#[cfg(feature = "metrics")]
+impl MetricExt for Metric {
+    fn insert_attribute<K, V>(&mut self, key: K, value: V)
+    where
+        K: Into<Cow<'static, str>>,
+        V: Into<Value>,
+    {
+        self.attributes
+            .insert(key.into(), LogAttribute(value.into()));
+    }
+
+    fn attribute(&self, key: &str) -> Option<&LogAttribute> {
+        self.attributes.get(key)
+    }
+}