Add #[with_removal] attribute to #[metrics] macro

`#[with_removal]` generates two additional functions that allow to
remove individual label sets from a metric family as well as clear the
family completely. This is useful when metrics are used for dynamic
data, such as peer RTT in a P2P system.

The feature is hidden behind `cfg(foundations_unstable)`, which allows
us to iterate on the API in the future. Both proc-macro unit tests as
well as an integration test are included in the change.

Author: TheJokr

Cargo.toml

@@ -65,7 +65,7 @@ pin-project-lite = "0.2.16"
 proc-macro2 = { version = "1", default-features = false }
 prometheus = { version = "0.14", default-features = false }
 prometheus-client = "0.18"
-prometools = "0.2.2"
+prometools = "0.2.3"
 rand = "0.9"
 percent-encoding = "2.3"
 quote = "1"

foundations-macros/src/metrics/mod.rs

@@ -58,6 +58,7 @@ struct FnAttrs {
     doc: String,
     ctor: Option<ExprStruct>,
     optional: bool,
+    with_removal: bool,
 }
 
 struct FnArg {
@@ -298,6 +299,7 @@ fn metric_init(foundations: &Path, fn_: &ItemFn) -> proc_macro2::TokenStream {
                 doc,
                 optional,
                 ctor,
+                ..
             },
         ident: field_name,
         args,
@@ -355,7 +357,13 @@ fn metric_init(foundations: &Path, fn_: &ItemFn) -> proc_macro2::TokenStream {
 
 fn metric_fn(foundations: &Path, metrics_struct: &Ident, fn_: &ItemFn) -> proc_macro2::TokenStream {
     let ItemFn {
-        attrs: FnAttrs { cfg, doc, .. },
+        attrs:
+            FnAttrs {
+                cfg,
+                doc,
+                with_removal,
+                ..
+            },
         fn_token,
         vis: fn_vis,
         ident: metric_name,
@@ -364,35 +372,77 @@ fn metric_fn(foundations: &Path, metrics_struct: &Ident, fn_: &ItemFn) -> proc_m
         ty: metric_type,
     } = fn_;
 
-    let fn_args = args.iter().map(|arg| arg.to_arg());
+    let fn_args: Vec<_> = args.iter().map(|arg| arg.to_arg()).collect();
 
-    let fn_body = if args.is_empty() {
-        quote! {
+    let (convert_args, access_metric) = if args.is_empty() {
+        let accessor = quote! {
             ::std::clone::Clone::clone(&#metrics_struct.#metric_name)
-        }
+        };
+        (quote! {}, accessor)
     } else {
         let label_inits = args.iter().map(|arg| arg.to_initializer());
+        let convert = quote! {
+            let __args = #metric_name {
+                #(#label_inits,)*
+            };
+        };
 
-
-        quote! {
+        let accessor = quote! {
             ::std::clone::Clone::clone(
                 &#foundations::reexports_for_macros::prometools::serde::Family::get_or_create(
                     &#metrics_struct.#metric_name,
-                    &#metric_name {
-                        #(#label_inits,)*
-                    },
+                    &__args,
                 )
             )
+        };
+        (convert, accessor)
+    };
+
+    let removal_fns = if cfg!(foundations_unstable) && *with_removal {
+        let remove_ident = format_ident!("{metric_name}_remove");
+        let remove_doc = LitStr::new(
+            &format!("Removes one label set from the `{metric_name}` family."),
+            Span::call_site(),
+        );
+
+        let clear_ident = format_ident!("{metric_name}_clear");
+        let clear_doc = LitStr::new(
+            &format!("Removes all label sets from the `{metric_name}` family."),
+            Span::call_site(),
+        );
+
+        quote! {
+            #[doc = #remove_doc]
+            #(#cfg)*
+            #fn_vis #fn_token #remove_ident(#(#fn_args,)*) #arrow_token bool {
+                #convert_args
+                #foundations::reexports_for_macros::prometools::serde::Family::remove(
+                    &#metrics_struct.#metric_name,
+                    &__args,
+                )
+            }
+
+            #[doc = #clear_doc]
+            #(#cfg)*
+            #fn_vis #fn_token #clear_ident() {
+                #foundations::reexports_for_macros::prometools::serde::Family::clear(
+                    &#metrics_struct.#metric_name,
+                )
+            }
         }
+    } else {
+        quote! {}
     };
 
     quote! {
         #[doc = #doc]
         #(#cfg)*
         #[must_use]
         #fn_vis #fn_token #metric_name(#(#fn_args,)*) #arrow_token #metric_type {
-            #fn_body
+            #convert_args
+            #access_metric
         }
+        #removal_fns
     }
 }
 
@@ -711,15 +761,16 @@ mod tests {
                     message: &'static str,
                     error: impl Into<String>,
                 ) -> Counter {
+                    let __args = connections_errors_total {
+                        endpoint: ::std::clone::Clone::clone(endpoint),
+                        kind,
+                        message,
+                        error: ::std::convert::Into::into(error),
+                    };
                     ::std::clone::Clone::clone(
                         &::foundations::reexports_for_macros::prometools::serde::Family::get_or_create(
                             &__oxy_Metrics.connections_errors_total,
-                            &connections_errors_total {
-                                endpoint: ::std::clone::Clone::clone(endpoint),
-                                kind,
-                                message,
-                                error: ::std::convert::Into::into(error),
-                            },
+                            &__args,
                         )
                     )
                 }
@@ -825,15 +876,111 @@ mod tests {
                 pub fn requests_per_connection(
                     endpoint: String,
                 ) -> Histogram {
+                    let __args = requests_per_connection { endpoint, };
                     ::std::clone::Clone::clone(
                         &::foundations::reexports_for_macros::prometools::serde::Family::get_or_create(
                             &__oxy_Metrics.requests_per_connection,
-                            &requests_per_connection {
-                                endpoint,
+                            &__args,
+                        )
+                    )
+                }
+            }
+        };
+
+        assert_eq!(actual, expected);
+    }
+
+    #[cfg(foundations_unstable)]
+    #[test]
+    fn expand_with_removal() {
+        let attr = parse_attr! {
+            #[metrics]
+        };
+
+        let src = parse_quote! {
+            pub(crate) mod oxy {
+                /// Total number of requests
+                #[with_removal]
+                pub(crate) fn requests_total(status: u16) -> Counter;
+            }
+        };
+
+        let actual = expand_from_parsed(attr, src).to_string();
+
+        let expected = code_str! {
+            pub(crate) mod oxy {
+                use super::*;
+
+                #[allow(non_camel_case_types)]
+                struct __oxy_Metrics {
+                    requests_total:
+                        ::foundations::reexports_for_macros::prometools::serde::Family<
+                            requests_total,
+                            Counter,
+                        >,
+                }
+
+                #[allow(non_camel_case_types)]
+                #[derive(
+                    ::std::clone::Clone,
+                    ::std::cmp::Eq,
+                    ::std::hash::Hash,
+                    ::std::cmp::PartialEq,
+                    ::foundations::reexports_for_macros::serde::Serialize,
+                )]
+                #[serde(crate = ":: foundations :: reexports_for_macros :: serde")]
+                struct requests_total {
+                    status: u16,
+                }
+
+                #[allow(non_upper_case_globals)]
+                static __oxy_Metrics: ::std::sync::LazyLock<__oxy_Metrics> =
+                    ::std::sync::LazyLock::new(|| {
+                        let registry = &mut *::foundations::telemetry::metrics::internal::Registries::get_subsystem(stringify!(oxy), false, true);
+
+                        __oxy_Metrics {
+                            requests_total: {
+                                let metric = ::std::default::Default::default();
+
+                                ::foundations::reexports_for_macros::prometheus_client::registry::Registry::register(
+                                    registry,
+                                    ::std::stringify!(requests_total),
+                                    str::trim(" Total number of requests"),
+                                    ::std::boxed::Box::new(::std::clone::Clone::clone(&metric))
+                                );
+
+                                metric
                             },
+                        }
+                    });
+
+                #[doc = " Total number of requests"]
+                #[must_use]
+                pub(crate) fn requests_total(status: u16,) -> Counter {
+                    let __args = requests_total { status, };
+                    ::std::clone::Clone::clone(
+                        &::foundations::reexports_for_macros::prometools::serde::Family::get_or_create(
+                            &__oxy_Metrics.requests_total,
+                            &__args,
                         )
                     )
                 }
+
+                #[doc = "Removes one label set from the `requests_total` family."]
+                pub(crate) fn requests_total_remove(status: u16,) -> bool {
+                    let __args = requests_total { status, };
+                    ::foundations::reexports_for_macros::prometools::serde::Family::remove(
+                        &__oxy_Metrics.requests_total,
+                        &__args,
+                    )
+                }
+
+                #[doc = "Removes all label sets from the `requests_total` family."]
+                pub(crate) fn requests_total_clear() {
+                    ::foundations::reexports_for_macros::prometools::serde::Family::clear(
+                        &__oxy_Metrics.requests_total,
+                    )
+                }
             }
         };