scuffle_metrics_derive/
lib.rs

1//! A proc-macro to derive the `#[metrics]` attribute and the
2//! `#[derive(MetricEnum)]` attribute.
3//!
4//! For more information checkout the [`scuffle-metrics`](../scuffle_metrics)
5//! crate.
6//!
7//! ## Status
8//!
9//! This crate is currently under development and is not yet stable, unit tests
10//! are not yet fully implemented.
11//!
12//! Unit tests are not yet fully implemented. Use at your own risk.
13//!
14//! ## License
15//!
16//! This project is licensed under the [MIT](./LICENSE.MIT) or
17//! [Apache-2.0](./LICENSE.Apache-2.0) license. You can choose between one of
18//! them if you use this work.
19//!
20//! `SPDX-License-Identifier: MIT OR Apache-2.0`
21
22use enum_impl::metric_enum_impl;
23use metrics_impl::metrics_impl;
24use proc_macro::TokenStream;
25
26mod enum_impl;
27mod metrics_impl;
28
29/// A macro used to create metric handlers.
30///
31/// You can change the crate by specifying `#[metrics(crate_path = "...")]`.
32///
33/// Module Attributes:
34///
35/// - `crate_path`: The `scuffle_metrics` crate path.
36/// - `rename`: The name of the metric container.
37///
38/// Function Attributes:
39///
40/// - `crate_path`: The `scuffle_metrics` crate path.
41/// - `builder`: The builder to use for the metric.
42/// - `unit`: The unit of the metric.
43/// - `rename`: The name of the metric.
44///
45/// Function Arguments Attributes:
46///
47/// - `rename`: The name of the argument.
48///
49/// When using the module, you do not need to attribute each function with the
50/// `#[metrics]` attribute. All non function definitions are ignored.
51///
52/// # Module Example
53///
54/// ```rust
55/// #[scuffle_metrics::metrics]
56/// mod example {
57///     use scuffle_metrics::{MetricEnum, collector::CounterU64};
58///
59///     #[derive(MetricEnum)]
60///     pub enum Kind {
61///         Http,
62///         Grpc,
63///     }
64///
65///     #[metrics(unit = "requests")]
66///     pub fn request(kind: Kind) -> CounterU64;
67/// }
68///
69/// // Increment the counter
70/// example::request(example::Kind::Http).incr();
71/// ```
72///
73/// # Function Example
74///
75/// ```rust
76/// # use scuffle_metrics::{MetricEnum, collector::CounterU64};
77/// # #[derive(MetricEnum)]
78/// # pub enum Kind {
79/// #     Http,
80/// #     Grpc,
81/// # }
82/// #[scuffle_metrics::metrics(unit = "requests")]
83/// pub fn request(kind: Kind) -> CounterU64;
84///
85/// // Increment the counter
86/// request(Kind::Http).incr();
87/// ```
88#[proc_macro_attribute]
89pub fn metrics(args: TokenStream, input: TokenStream) -> TokenStream {
90    match metrics_impl(args, input) {
91        Ok(tokens) => tokens.into(),
92        Err(err) => err.to_compile_error().into(),
93    }
94}
95
96/// Implements a conversion `Into<opentelemetry::Value>` for the enum.
97/// This allows the enum to be used as a metric label.
98///
99/// You can change the crate by specifying `#[metrics(crate_path = "...")]`.
100///
101/// Enum Attributes:
102///
103/// - `crate_path`: The `scuffle_metrics` crate path.
104///
105/// Enum Variant Attributes:
106///
107/// - `rename`: The name of the metric.
108#[proc_macro_derive(MetricEnum, attributes(metrics))]
109pub fn metric_enum(input: TokenStream) -> TokenStream {
110    match metric_enum_impl(input.into()) {
111        Ok(tokens) => tokens.into(),
112        Err(err) => err.to_compile_error().into(),
113    }
114}
scuffle_metrics_derive/lib.rs

scuffle_metrics_derive/
lib.rs
