relay_conventions/

lib.rs

//! Relay's interface to [`sentry-conventions`](https://github.com/getsentry/sentry-conventions).
//!
//! This crate contains the `sentry-conventions` repository as a git submodule.
//!
//! # Attributes
//!
//! Attribute definitions in `sentry-conventions` are parsed at build time. For each attribute, this crate exposes:
//! * A constant whose value is the attribute's key in `sentry-conventions`. This constant has a deprecation tag if
//!   the attribute is marked as deprecated in `sentry-conventions`, leading to a compiler warning if it's used anyway.
//! * A record of the attribute's relevant parameters (PII status, backfilling normalizing behavior). These records can
//!   be queried using the [`attribute_info`] function.
//!
//! ## Attribute normalization
//! Deprecated attributes can have their `_status` set to `null`, `"backfill"`, or `"normalize"` in `sentry-conventions`.
//! These values affect how Relay normalizes the attribute:
//! * `null`: The attribute is left unchanged.
//! * `"backfill"`: The attribute's value is _copied_ to the replacement attribute, but an existing value for the
//!   replacement attribute is not overwritten. Thus, if the replacement attribute is already present, nothing happens.
//! * `"normalize"`: The attribute's value is _moved_ to the replacement attribute, but an existing value for the
//!   replacement attribute is not overwritten. Thus, if the replacement attribute is already present, _the deprecated
//!   attribute is deleted_.
//!
//! This normalization step runs before other steps (user agent detection, category
//! detection, …) that depend on specific attributes. Therefore, those other normalizations only need to check the
//! values of non-deprecated attributes.
//!
//! # FAQ
//!
//! ### I've changed something in `sentry-conventions`, how do I get Relay to pick it up?
//! Relay parses `sentry-conventions` at compile time, so any change requires a PR to Relay and needs to be deployed.
//!
//! In Relay, Update the `sentry-conventions` submodule:
//! ```bash
//! cd relay-conventions/sentry-conventions
//! git checkout main
//! git pull
//! ```
//! Then open a PR with your change.
//!
//! ### Why is my deprecated attribute not being rewritten to the current name?
//! Make sure the attribute's `deprecation["_status"]` field is set to either `"backfill"` or `"normalize"`,
//! depending on what you want to happen (see above). If this is set correctly and it's still not working,
//! verify the behaviour with an integration test and open an issue.
//!
//! ### After updating `sentry-conventions` I get a warning about a deprecated constant, what should I do?
//! This means that Relay is reading or writing an attribute that is deprecated in the new conventions version.
//!
//! * If the attribute has a replacement and is set to `"backfill"` or `"normalize"`, you can just replace the constant
//!   with the current version and normalization takes care of the rest.
//! * If the attribute has a replacement but no `"backfill"` or `"normalize"`, consider changing that in `sentry-conventions`.
//!   Unless there is a good reason not to, you probably want the attribute to be rewritten.
//! * Otherwise, we may have to decide what to do on a case-by-case basis.
//!
//! ### 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)]
    #![allow(non_upper_case_globals)]
    include!(concat!(env!("OUT_DIR"), "/attribute_consts.rs"));

    mod not_yet_defined {
        pub const SENTRY__EVENT__SERIALIZED_REQUEST: &str = "sentry.event.serialized_request";

        // TODO(buenaflor): Add as sentry convention once mobile SDKs can migrate to it.
        // Tracking issue: https://github.com/getsentry/sentry-conventions/issues/318
        pub const APP__VITALS__START__VALUE: &str = "app.vitals.start.value";
    }
    pub use self::not_yet_defined::*;
}

pub mod measurements {
    //! Measurement constant definitions.
    #![allow(non_upper_case_globals)]
    include!(concat!(env!("OUT_DIR"), "/measurement_consts.rs"));
}

pub mod interpolate {
    //! Functions for interpolating attribute keys with placeholders.
    #![allow(non_snake_case)]
    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"), "/measurement_replacement_fn.rs"));

/// Whether an attribute should be scrubbed.
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
pub enum ApplyScrubbing {
    /// The attribute will be stripped by default.
    Auto,
    /// The attribute will only be stripped when addressed with a specific path selector, but generic
    /// selectors such as `$string` do not apply.
    Manual,
    /// The attribute cannot be stripped at all.
    Never,
}

/// The name of the replacement of a deprecated attribute.
#[derive(Clone, Copy)]
pub enum ReplacementName {
    /// The replacement attribute has a fixed name,
    /// i.e., doesn't contain a placeholder.
    Static(&'static str),
    /// The replacement attribute contains a placeholder.
    ///
    /// This means its name can't be used "as-is"; a value
    /// has to be inserted into the placeholder. The contained
    /// function performs this insertion.
    Dynamic(fn(&str) -> String),
}

impl fmt::Debug for ReplacementName {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Static(arg0) => f.debug_tuple("Static").field(arg0).finish(),
            Self::Dynamic(_) => f.debug_tuple("Dynamic").finish(),
        }
    }
}

/// Under which names an attribute should be saved.
#[derive(Debug, Clone, Copy)]
pub enum WriteBehavior {
    /// Save the attribute under its current name.
    ///
    /// This is the only choice for attributes that aren't deprecated.
    CurrentName,
    /// Save the attribute under its replacement name instead.
    NewName(ReplacementName),
    /// Save the attribute under both its current name and
    /// its replacement name.
    BothNames(ReplacementName),
}

/// Information about an attribute, as defined in `sentry-conventions`.
#[derive(Debug, Clone)]
pub struct AttributeInfo {
    /// How this attribute should be saved.
    pub write_behavior: WriteBehavior,
    /// Whether this attribute can contain PII.
    pub apply_scrubbing: ApplyScrubbing,
    /// Other attribute names that alias to this attribute.
    pub aliases: &'static [&'static str],
}

/// Returns information about an attribute, as defined in `sentry-conventions`.
///
/// If the matched attribute contains a placeholder (`<key>`), the second returned
/// value is the part of the attribute key that was inserted for the placeholder.
pub fn attribute_info_with_fragment(key: &str) -> Option<(&'static AttributeInfo, Option<&str>)> {
    ATTRIBUTES.find(key)
}

/// Returns information about an attribute, as defined in `sentry-conventions`.
pub fn attribute_info(key: &str) -> Option<&'static AttributeInfo> {
    attribute_info_with_fragment(key).map(|(info, _)| info)
}

/// Special path segment in attribute keys that matches any value.
const PLACEHOLDER_SEGMENT: &str = "<key>";

struct Node<T: 'static> {
    info: Option<T>,
    children: phf::Map<&'static str, Node<T>>,
}

impl<T> Node<T> {
    fn find<'a>(&self, key: &'a str) -> Option<(&T, Option<&'a str>)> {
        if key.is_empty() {
            return self.info.as_ref().map(|info| (info, None));
        }
        let (prefix, suffix) = key.split_once('.').unwrap_or((key, ""));

        // First try a literal lookup.
        // If the prefix is `"<key>"`, we skip this and fall through
        // to the second attempt.
        if prefix != PLACEHOLDER_SEGMENT
            && let Some(info) = self
                .children
                .get(prefix)
                .and_then(|child| child.find(suffix))
        {
            return Some(info);
        }

        // If the literal lookup doesn't succeed, try a placeholder
        // lookup and bubble up the current `prefix` if it succeeds.
        if let Some((info, _)) = self
            .children
            .get(PLACEHOLDER_SEGMENT)
            .and_then(|child| child.find(suffix))
        {
            return Some((info, Some(prefix)));
        }
        None
    }
}

#[cfg(test)]
mod tests {
    use std::collections::HashMap;

    use phf::phf_map;
    use relay_protocol::{Annotated, Value};

    use super::*;

    #[test]
    fn test_http_response_content_length() {
        let info = attribute_info("http.response_content_length").unwrap();

        insta::assert_debug_snapshot!(info, @r#"
        AttributeInfo {
            write_behavior: BothNames(
                Static(
                    "http.response.body.size",
                ),
            ),
            apply_scrubbing: Manual,
            aliases: [
                "http.response.body.size",
                "http.response.header.content-length",
            ],
        }
        "#);
    }

    #[test]
    fn test_url_path_parameter() {
        // See https://github.com/getsentry/sentry-conventions/blob/d80504a40ba3a0a23eb746e2608425cf8d8e68bf/model/attributes/url/url__path__parameter__%5Bkey%5D.json.
        let (info, fragment) = attribute_info_with_fragment("url.path.parameter.'id=123'").unwrap();
        assert_eq!(fragment, Some("'id=123'"));

        insta::assert_debug_snapshot!(info, @r#"
        AttributeInfo {
            write_behavior: CurrentName,
            apply_scrubbing: Auto,
            aliases: [
                "params.<key>",
                "url.path.params.<key>",
            ],
        }
        "#);
    }

    /// Tests that `cls.source.<key>` is rewritten to `browser.web_vital.cls.source.<key>`.
    #[test]
    fn test_cls_source_key() {
        let (info, fragment) = attribute_info_with_fragment("cls.source.foobar").unwrap();

        let WriteBehavior::BothNames(ReplacementName::Dynamic(name_fn)) = info.write_behavior
        else {
            unreachable!();
        };

        assert_eq!(
            name_fn(fragment.unwrap()),
            "browser.web_vital.cls.source.foobar"
        );
    }

    const ROOT: Node<u8> = Node {
        info: None,
        children: phf_map! {
            "foo" => Node {
                info: Some(1),
                children: phf_map!{}
            },
            "<key>" =>  Node {
                info: None,
                children: phf_map!{
                    "bar" => Node {
                        info: Some(2),
                        children: phf_map! {}
                    }
                }
            }
        },
    };

    #[test]
    fn test_hypothetical() {
        assert_eq!(ROOT.find("foo.bar"), Some((&2, Some("foo"))));
        assert_eq!(ROOT.find("<key>.bar"), Some((&2, Some("<key>"))));
    }

    mod test_name_fn {
        include!(concat!(env!("OUT_DIR"), "/test_name_fn.rs"));
    }
    use test_name_fn::name_for_op_and_attributes;

    #[test]
    fn only_literal_template() {
        let attributes: HashMap<&str, Value> = HashMap::new();
        assert_eq!(
            name_for_op_and_attributes("op_with_literal_name", |name| attributes.get(name))
                .unwrap(),
            "literal name"
        );
    }

    #[test]
    fn multiple_ops_same_template() {
        let attributes = HashMap::from([("attr1", Value::String("foo".to_owned()))]);
        assert_eq!(
            name_for_op_and_attributes("op_with_attributes_1", |name| attributes.get(name))
                .unwrap(),
            "foo"
        );
        assert_eq!(
            name_for_op_and_attributes("op_with_attributes_2", |name| attributes.get(name))
                .unwrap(),
            "foo"
        );
    }

    #[test]
    fn skips_templates_when_attrs_are_missing() {
        let attributes = HashMap::from([
            ("attr2", Value::String("bar".to_owned())),
            ("attr3", Value::String("baz".to_owned())),
        ]);
        assert_eq!(
            name_for_op_and_attributes("op_with_attributes_1", |name| attributes.get(name))
                .unwrap(),
            "bar baz"
        );
    }

    #[test]
    fn handles_literal_prefixes_and_suffixes() {
        let attributes = HashMap::from([("attr3", Value::String("baz".to_owned()))]);
        assert_eq!(
            name_for_op_and_attributes("op_with_attributes_1", |name| attributes.get(name))
                .unwrap(),
            "prefix baz suffix",
        );
    }

    #[test]
    fn considers_multiple_files() {
        let attributes: HashMap<&str, Value> = HashMap::new();
        assert_eq!(
            name_for_op_and_attributes("op_in_second_name_file", |name| attributes.get(name))
                .unwrap(),
            "second file literal name",
        );
    }

    #[test]
    fn returns_none_for_unknown_ops() {
        let attributes: HashMap<&str, Value> = HashMap::new();
        assert!(name_for_op_and_attributes("unknown_op", |name| attributes.get(name)).is_none());
    }

    #[test]
    fn handles_multiple_value_types() {
        let attributes = HashMap::from([("attr1", Value::Bool(true))]);
        assert_eq!(
            name_for_op_and_attributes("op_with_attributes_1", |name| attributes.get(name))
                .unwrap(),
            "true",
        );

        let attributes = HashMap::from([("attr1", Value::I64(123))]);
        assert_eq!(
            name_for_op_and_attributes("op_with_attributes_1", |name| attributes.get(name))
                .unwrap(),
            "123",
        );

        let attributes = HashMap::from([("attr1", Value::U64(123))]);
        assert_eq!(
            name_for_op_and_attributes("op_with_attributes_1", |name| attributes.get(name))
                .unwrap(),
            "123",
        );

        let attributes = HashMap::from([("attr1", Value::F64(1.23))]);
        assert_eq!(
            name_for_op_and_attributes("op_with_attributes_1", |name| attributes.get(name))
                .unwrap(),
            "1.23",
        );
    }

    #[test]
    fn name_handles_arrays() {
        let attributes = HashMap::from([
            (
                "attr2",
                Value::Array(vec![
                    Annotated::new("posts:123".into()),
                    Annotated::new("posts:456".into()),
                ]),
            ),
            ("attr3", Value::U64(789)),
        ]);

        assert_eq!(
            name_for_op_and_attributes("op_with_attributes_1", |name| attributes.get(name))
                .unwrap(),
            "posts:123, posts:456 789",
        );
    }
}