feat(spans): Infer descriptions via sentry-conventions (#6093)

loewenheim · web-flow · commit 1bdefc8aabd5 · 2026-06-22T08:22:23.000Z
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+**Features**:
+
+- Infer span descriptions via `sentry-conventions`. ([#6093](https://github.com/getsentry/relay/pull/6093))
+
 **Bug Fixes**:
 
 - Wider type support for OTel log bodies. ([#6106](https://github.com/getsentry/relay/pull/6106))
diff --git a/relay-conventions/build/build.rs b/relay-conventions/build/build.rs
@@ -1,6 +1,8 @@
 mod attributes;
+mod description;
 mod measurements;
 mod name;
+mod template;
 
 use std::collections::BTreeMap;
 use std::env;
@@ -11,6 +13,7 @@ use std::path::{Path, PathBuf};
 use walkdir::WalkDir;
 
 const ATTRIBUTE_DIR: &str = "sentry-conventions/model/attributes";
+const DESCRIPTION_DIR: &str = "sentry-conventions/model/description";
 const MEASUREMENT_DIR: &str = "sentry-conventions/model/measurements";
 const NAME_DIR: &str = "sentry-conventions/model/name";
 
@@ -20,6 +23,7 @@ fn main() {
     write_attribute_rs(&crate_dir);
     write_measurement_rs(&crate_dir);
     write_name_rs(&crate_dir);
+    write_description_rs(&crate_dir);
 
     // Ideally this would only run when compiling for tests, but #[cfg(test)] doesn't seem to work
     // here.
@@ -128,6 +132,29 @@ fn write_name_rs(crate_dir: &Path) {
     writeln!(&mut out_file, "{}", output).unwrap();
 }
 
+fn write_description_rs(crate_dir: &Path) {
+    let descriptions = WalkDir::new(crate_dir.join(DESCRIPTION_DIR))
+        .into_iter()
+        .flat_map(|file| {
+            let file = file.unwrap();
+            if file.file_type().is_file()
+                && let Some(ext) = file.path().extension()
+                && ext.to_str() == Some("json")
+            {
+                let contents = std::fs::read_to_string(file.path()).unwrap();
+                Some(serde_json::from_str::<description::Description>(&contents).unwrap())
+            } else {
+                None
+            }
+        });
+
+    let out_path = Path::new(&env::var("OUT_DIR").unwrap()).join("description_fn.rs");
+    let mut out_file = BufWriter::new(File::create(&out_path).unwrap());
+    let output = description::description_file_output(descriptions);
+
+    writeln!(&mut out_file, "{}", output).unwrap();
+}
+
 fn write_measurement_rs(crate_dir: &Path) {
     use measurements::{
         Measurement, format_constant, measurement_attribute_pair, write_replacement_fn,
diff --git a/relay-conventions/build/description.rs b/relay-conventions/build/description.rs
@@ -0,0 +1,111 @@
+use proc_macro2::TokenStream;
+use quote::quote;
+use serde::Deserialize;
+
+use crate::template::{TemplatePart, parse_template_into_parts};
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct Operation {
+    pub ops: Vec<String>,
+    pub templates: Vec<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct Description {
+    pub operations: Vec<Operation>,
+}
+
+/// Returns a `TokenStream` representing Rust code defining a `description_for_op_and_attributes` method.
+/// This method constructs a description for the given op and attributes based on the span description
+/// conventions defined in the `sentry-conventions` repository.
+///
+/// Some clippy lints are explicitly allowed, when fixing them would complicate the codegen.
+pub fn description_file_output(descriptions: impl Iterator<Item = Description>) -> TokenStream {
+    let operations = descriptions.flat_map(|description| description.operations);
+
+    let match_arms = operations.map(|Operation { ops, templates }| {
+        let (templates_with_attributes, literal_template)  = match templates.split_last() {
+            Some((last, init)) if !last.contains("{{")=> (init, Some(last.as_str())),
+            _ => (&templates[..], None),
+        };
+
+        let conditional_attribute_blocks = templates_with_attributes.iter().map(|template| {
+            let parts = parse_template_into_parts(template);
+            if !parts.iter().any(|part| matches!(part, TemplatePart::Attribute(_, _))) {
+                panic!("templates before the final template must contain attributes (bad template: {})", template);
+            }
+
+            // First, each attribute becomes a let clause for our if block.
+            let if_clauses = parts.iter().flat_map(|part| {
+                if let TemplatePart::Attribute(name, ident) = part {
+                    Some(quote! {
+                        let Some(#ident @ (Val::String(_) | Val::Bool(_) | Val::U64(_) | Val::I64(_) | Val::F64(_))) = attributes.get_value(#name)
+                    })
+                } else {
+                    None
+                }
+            });
+
+            // Then, construct the format string and argument list for a `format!` call to produce the name.
+            let format_string = parts.iter().map(|part| match part {
+                TemplatePart::Literal(l) => *l,
+                TemplatePart::Attribute(_, _) => "{}",
+            }).collect::<String>();
+            let format_args = parts.iter().flat_map(|part| {
+                if let TemplatePart::Attribute(_, ident) = part {
+                    Some(quote! { DisplayVal(#ident) })
+                } else {
+                    None
+                }
+            });
+
+            Some(quote! {
+                if #(#if_clauses)&&* {
+                    return Some(format!(#format_string, #(#format_args),*));
+                };
+            })
+        });
+
+        let literal_name_fallback = match literal_template {
+            Some(literal_template) => quote! { Some(#literal_template.to_owned()) },
+            None => quote! { None },
+        };
+
+        // Assemble the match arm, with `ops` forming the match clause and the match body checking
+        // each template in turn before falling back to a literal (zero-attribute) template.
+        quote! {
+            #(#ops)|* => {
+                #(#conditional_attribute_blocks)*
+                #literal_name_fallback
+            }
+        }
+    });
+
+    quote! {
+        use relay_protocol::{Getter, Val};
+        use std::fmt;
+        use std::fmt::Display;
+
+        pub fn description_for_op_and_attributes(op: &str, attributes: &impl Getter) -> Option<String> {
+            match op {
+                #(#match_arms)*
+                _ => None
+            }
+        }
+
+        struct DisplayVal<'a>(Val<'a>);
+
+        impl Display for DisplayVal<'_> {
+            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+                match self.0 {
+                    Val::Bool(b) => write!(f, "{b}"),
+                    Val::I64(i) => write!(f, "{i}"),
+                    Val::U64(u) => write!(f, "{u}"),
+                    Val::F64(fl) => write!(f, "{fl}"),
+                    Val::String(s) => f.write_str(s),
+                    Val::HexId(_) | Val::Array(_) | Val::Object(_) => Ok(()),
+                }
+            }
+        }
+    }
+}
diff --git a/relay-conventions/build/name.rs b/relay-conventions/build/name.rs
@@ -1,8 +1,9 @@
-use pest::Parser;
-use proc_macro2::{Ident, TokenStream};
-use quote::{format_ident, quote};
+use proc_macro2::TokenStream;
+use quote::quote;
 use serde::Deserialize;
 
+use crate::template::{TemplatePart, parse_template_into_parts};
+
 #[derive(Debug, Clone, Deserialize)]
 pub struct Operation {
     pub ops: Vec<String>,
@@ -116,41 +117,3 @@ pub fn name_file_output(names: impl Iterator<Item = Name>) -> TokenStream {
         }
     }
 }
-
-enum TemplatePart<'a> {
-    Literal(&'a str),
-    Attribute(&'a str, Ident),
-}
-
-fn parse_template_into_parts(template: &'_ str) -> Vec<TemplatePart<'_>> {
-    let Ok(mut parsed) = TemplateParser::parse(Rule::root, template) else {
-        // This panic (at build time) will make it obvious if the sentry-conventions submodule ever
-        // contains an invalid template.
-        panic!(
-            "sentry_conventions contained unparseable template \"{}\"",
-            template
-        );
-    };
-    let root = parsed.next().unwrap();
-    root.into_inner()
-        .enumerate()
-        .filter_map(|(i, part)| {
-            Some(match part.as_rule() {
-                Rule::text => TemplatePart::Literal(part.as_str()),
-                Rule::attribute_name => {
-                    TemplatePart::Attribute(part.as_str(), format_ident!("attribute_{}", i))
-                }
-                Rule::EOI => return None,
-                Rule::root | Rule::attribute => unreachable!(),
-            })
-        })
-        .collect()
-}
-
-mod parser {
-    #[derive(pest_derive::Parser)]
-    #[grammar = "../build/name_template.pest"]
-    pub struct TemplateParser;
-}
-
-use self::parser::{Rule, TemplateParser};
diff --git a/relay-conventions/build/name_description_template.pest b/relay-conventions/build/name_description_template.pest
diff --git a/relay-conventions/build/template.rs b/relay-conventions/build/template.rs
@@ -0,0 +1,41 @@
+use pest::Parser;
+use proc_macro2::Ident;
+use quote::format_ident;
+
+pub enum TemplatePart<'a> {
+    Literal(&'a str),
+    Attribute(&'a str, Ident),
+}
+
+pub fn parse_template_into_parts(template: &'_ str) -> Vec<TemplatePart<'_>> {
+    let Ok(mut parsed) = TemplateParser::parse(Rule::root, template) else {
+        // This panic (at build time) will make it obvious if the sentry-conventions submodule ever
+        // contains an invalid template.
+        panic!(
+            "sentry_conventions contained unparseable template \"{}\"",
+            template
+        );
+    };
+    let root = parsed.next().unwrap();
+    root.into_inner()
+        .enumerate()
+        .filter_map(|(i, part)| {
+            Some(match part.as_rule() {
+                Rule::text => TemplatePart::Literal(part.as_str()),
+                Rule::attribute_name => {
+                    TemplatePart::Attribute(part.as_str(), format_ident!("attribute_{}", i))
+                }
+                Rule::EOI => return None,
+                Rule::root | Rule::attribute => unreachable!(),
+            })
+        })
+        .collect()
+}
+
+mod parser {
+    #[derive(pest_derive::Parser)]
+    #[grammar = "../build/name_description_template.pest"]
+    pub struct TemplateParser;
+}
+
+use self::parser::{Rule, TemplateParser};
diff --git a/relay-conventions/src/lib.rs b/relay-conventions/src/lib.rs
@@ -53,6 +53,8 @@
 //!
 //! ### I want to reference an attribute in Relay but it's not defined in `sentry-conventions`, what should I do?
 //! **Always** define it in `sentry-conventions` before using it in Relay. This makes sure we have proper
+
+use std::fmt;
 pub mod attributes {
     //! Attribute constant definitions.
     #![allow(rustdoc::bare_urls)]
@@ -79,9 +81,16 @@ pub mod interpolate {
     include!(concat!(env!("OUT_DIR"), "/interpolation_fns.rs"));
 }
 
+pub mod name {
+    include!(concat!(env!("OUT_DIR"), "/name_fn.rs"));
+}
+
+pub mod description {
+    include!(concat!(env!("OUT_DIR"), "/description_fn.rs"));
+}
+
 include!(concat!(env!("OUT_DIR"), "/attribute_map.rs"));
 include!(concat!(env!("OUT_DIR"), "/canonical_fn.rs"));
-include!(concat!(env!("OUT_DIR"), "/name_fn.rs"));
 include!(concat!(env!("OUT_DIR"), "/measurement_replacement_fn.rs"));
 
 /// Whether an attribute should be PII-strippable/should be subject to datascrubbers
diff --git a/relay-spans/src/description.rs b/relay-spans/src/description.rs
@@ -1,38 +1,44 @@
 use relay_conventions::attributes::*;
+use relay_conventions::description::description_for_op_and_attributes;
 use relay_event_schema::protocol::Attributes;
-use relay_protocol::{Annotated, Value};
+use relay_protocol::{Annotated, Getter, Val};
 
 /// Derives a description for a V2 span, based on its name
 /// and attributes.
 ///
-/// For now, this tries the following steps, in order:
-/// - returns the span's name if its [`SENTRY__ORIGIN`] attribute is `"manual"`
-/// - returns the span's [`DB__QUERY__TEXT`] attribute if it exists
-/// - returns a combination of the span's [`HTTP__REQUEST__METHOD`] and
-///   [`URL__FULL`] attributes, if they both exists.
-///
-/// In the future, this logic will be partly moved to and extended in `sentry-conventions`.
+/// For now, this attempts to return the following values, in order:
+/// - the span's name if its [`SENTRY__ORIGIN`] attribute is `"manual"`
+/// - a name constructed following the rules defined in sentry-conventions
+/// - `None`
 pub fn derive_description_for_v2_span(
     attributes: &Attributes,
     name: &Annotated<String>,
 ) -> Option<String> {
-    if attributes
+    let origin = attributes
         .get_value(SENTRY__ORIGIN)
-        .and_then(|o| o.as_str())
-        == Some("manual")
-    {
-        return name.value().cloned();
-    }
+        .and_then(|o| o.as_str());
 
-    if let Some(&Value::String(db_query)) = attributes.get_value(DB__QUERY__TEXT).as_ref() {
-        return Some(db_query.clone());
-    }
+    let name = name.as_str();
 
-    if let Some(&Value::String(method)) = attributes.get_value(HTTP__REQUEST__METHOD).as_ref()
-        && let Some(&Value::String(url)) = attributes.get_value(URL__FULL).as_ref()
+    if let Some(name) = name
+        && origin == Some("manual")
     {
-        return Some(format!("{method} {url}"));
+        return Some(name.to_owned());
     }
 
-    None
+    let op = attributes.get_value(SENTRY__OP)?.as_str()?;
+
+    description_for_op_and_attributes(op, &AttributeGetter(attributes))
+}
+
+/// A custom getter for [`Attributes`] which only resolves values based on the attribute name.
+///
+/// This [`Getter`] does not implement nested traversals, which is the behaviour required for
+/// [`description_for_op_and_attributes`].
+struct AttributeGetter<'a>(&'a Attributes);
+
+impl<'a> Getter for AttributeGetter<'a> {
+    fn get_value(&self, path: &str) -> Option<Val<'_>> {
+        self.0.get_value(path).map(|value| value.into())
+    }
 }
diff --git a/relay-spans/src/name.rs b/relay-spans/src/name.rs
@@ -1,5 +1,5 @@
 use relay_conventions::attributes::{SENTRY__DESCRIPTION, SENTRY__OP, SENTRY__ORIGIN};
-use relay_conventions::name_for_op_and_attributes;
+use relay_conventions::name::name_for_op_and_attributes;
 use relay_event_schema::protocol::Attributes;
 use relay_protocol::{Getter, Val};
 
