1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
//! This crate provides [Metrics] derive macro
#![doc(
html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
)]
#![cfg_attr(not(test), warn(unused_crate_dependencies))]
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
use proc_macro::TokenStream;
use syn::{parse_macro_input, DeriveInput};
mod expand;
mod metric;
mod with_attrs;
/// The [Metrics] derive macro instruments all of the struct fields and
/// creates a [Default] implementation for the struct registering all of
/// the metrics.
///
/// Additionally, it creates a `describe` method on the struct, which
/// internally calls the describe statements for all metric fields.
///
/// Sample usage:
/// ```
/// use metrics::{Counter, Gauge, Histogram};
/// use reth_metrics_derive::Metrics;
///
/// #[derive(Metrics)]
/// #[metrics(scope = "metrics_custom")]
/// pub struct CustomMetrics {
/// /// A gauge with doc comment description.
/// gauge: Gauge,
/// #[metric(rename = "second_gauge", describe = "A gauge with metric attribute description.")]
/// gauge2: Gauge,
/// /// Some doc comment
/// #[metric(describe = "Metric attribute description will be preferred over doc comment.")]
/// counter: Counter,
/// /// A renamed histogram.
/// #[metric(rename = "histogram")]
/// histo: Histogram,
/// }
/// ```
///
/// The example above will be expanded to:
/// ```
/// pub struct CustomMetrics {
/// /// A gauge with doc comment description.
/// gauge: metrics::Gauge,
/// gauge2: metrics::Gauge,
/// /// Some doc comment
/// counter: metrics::Counter,
/// /// A renamed histogram.
/// histo: metrics::Histogram,
/// }
///
/// impl Default for CustomMetrics {
/// fn default() -> Self {
/// Self {
/// gauge: metrics::gauge!("metrics_custom_gauge"),
/// gauge2: metrics::gauge!("metrics_custom_second_gauge"),
/// counter: metrics::counter!("metrics_custom_counter"),
/// histo: metrics::histogram!("metrics_custom_histogram"),
/// }
/// }
/// }
///
/// impl CustomMetrics {
/// /// Describe all exposed metrics
/// pub fn describe() {
/// metrics::describe_gauge!(
/// "metrics_custom_gauge",
/// "A gauge with doc comment description."
/// );
/// metrics::describe_gauge!(
/// "metrics_custom_second_gauge",
/// "A gauge with metric attribute description."
/// );
/// metrics::describe_counter!(
/// "metrics_custom_counter",
/// "Metric attribute description will be preferred over doc comment."
/// );
/// metrics::describe_histogram!("metrics_custom_histogram", "A renamed histogram.");
/// }
/// }
///
/// impl std::fmt::Debug for CustomMetrics {
/// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
/// f.debug_struct("CustomMetrics").finish()
/// }
/// }
/// ```
///
/// Similarly, you can derive metrics with "dynamic" scope,
/// meaning their scope can be set at the time of instantiation.
/// For example:
/// ```
/// use reth_metrics_derive::Metrics;
///
/// #[derive(Metrics)]
/// #[metrics(dynamic = true)]
/// pub struct DynamicScopeMetrics {
/// /// A gauge with doc comment description.
/// gauge: metrics::Gauge,
/// }
/// ```
///
/// The example with dynamic scope will expand to
/// ```
/// pub struct DynamicScopeMetrics {
/// /// A gauge with doc comment description.
/// gauge: metrics::Gauge,
/// }
///
/// impl DynamicScopeMetrics {
/// pub fn new(scope: &str) -> Self {
/// Self { gauge: metrics::gauge!(format!("{}{}{}", scope, "_", "gauge")) }
/// }
///
/// pub fn describe(scope: &str) {
/// metrics::describe_gauge!(
/// format!("{}{}{}", scope, "_", "gauge"),
/// "A gauge with doc comment description."
/// );
/// }
/// }
///
/// impl std::fmt::Debug for DynamicScopeMetrics {
/// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
/// f.debug_struct("DynamicScopeMetrics").finish()
/// }
/// }
/// ```
#[proc_macro_derive(Metrics, attributes(metrics, metric))]
pub fn derive_metrics(input: TokenStream) -> TokenStream {
let input = parse_macro_input!(input as DeriveInput);
expand::derive(&input).unwrap_or_else(|err| err.to_compile_error()).into()
}