diff --git a/metrics-benchmark/src/main.rs b/metrics-benchmark/src/main.rs index 6321ebd9..df2b58cb 100644 --- a/metrics-benchmark/src/main.rs +++ b/metrics-benchmark/src/main.rs @@ -2,8 +2,8 @@ use getopts::Options; use hdrhistogram::Histogram as HdrHistogram; use log::{error, info}; use metrics::{ - gauge, histogram, increment_counter, register_counter, register_gauge, register_histogram, - Counter, Gauge, Histogram, Key, KeyName, Metadata, Recorder, SharedString, Unit, + counter, gauge, histogram, Counter, Gauge, Histogram, Key, KeyName, Metadata, Recorder, + SharedString, Unit, }; use metrics_util::registry::{AtomicStorage, Registry}; use portable_atomic::AtomicU64; @@ -120,9 +120,9 @@ impl Generator { if let Some(t0) = self.t0 { let start = if loop_counter % LOOP_SAMPLE == 0 { Some(clock.now()) } else { None }; - increment_counter!("ok"); - gauge!("total", self.gauge as f64); - histogram!("ok", t1.sub(t0)); + counter!("ok").increment(1); + gauge!("total").set(self.gauge as f64); + histogram!("ok").record(t1.sub(t0)); if let Some(val) = start { let delta = clock.now() - val; @@ -145,9 +145,9 @@ impl Generator { let clock = Clock::new(); let mut loop_counter = 0; - let counter = register_counter!("ok"); - let gauge = register_gauge!("total"); - let histogram = register_histogram!("ok"); + let counter = counter!("ok"); + let gauge = gauge!("total"); + let histogram = histogram!("ok"); loop { loop_counter += 1; diff --git a/metrics-exporter-prometheus/examples/prometheus_push_gateway.rs b/metrics-exporter-prometheus/examples/prometheus_push_gateway.rs index e362a194..229a0f38 100644 --- a/metrics-exporter-prometheus/examples/prometheus_push_gateway.rs +++ b/metrics-exporter-prometheus/examples/prometheus_push_gateway.rs @@ -4,10 +4,7 @@ use std::thread; use std::time::Duration; #[allow(unused_imports)] -use metrics::{ - decrement_gauge, gauge, histogram, increment_counter, increment_gauge, register_counter, - register_histogram, -}; +use metrics::{counter, gauge, histogram}; use metrics::{describe_counter, describe_histogram}; #[allow(unused_imports)] use metrics_exporter_prometheus::PrometheusBuilder; @@ -50,23 +47,24 @@ fn main() { let clock = Clock::new(); let mut last = None; - increment_counter!("idle_metric"); - gauge!("testing", 42.0); + counter!("idle_metric").increment(1); + gauge!("testing").set(42.0); // Loop over and over, pretending to do some work. loop { - increment_counter!("tcp_server_loops", "system" => "foo"); + counter!("tcp_server_loops", "system" => "foo").increment(1); if let Some(t) = last { let delta: Duration = clock.now() - t; - histogram!("tcp_server_loop_delta_secs", delta, "system" => "foo"); + histogram!("tcp_server_loop_delta_secs", "system" => "foo").record(delta); } let increment_gauge = thread_rng().gen_bool(0.75); + let gauge = gauge!("lucky_iterations"); if increment_gauge { - increment_gauge!("lucky_iterations", 1.0); + gauge.increment(1.0); } else { - decrement_gauge!("lucky_iterations", 1.0); + gauge.decrement(1.0); } last = Some(clock.now()); diff --git a/metrics-exporter-prometheus/examples/prometheus_server.rs b/metrics-exporter-prometheus/examples/prometheus_server.rs index 9ff05fd9..13a68a56 100644 --- a/metrics-exporter-prometheus/examples/prometheus_server.rs +++ b/metrics-exporter-prometheus/examples/prometheus_server.rs @@ -1,10 +1,7 @@ use std::thread; use std::time::Duration; -use metrics::{ - decrement_gauge, describe_counter, describe_histogram, gauge, histogram, increment_counter, - increment_gauge, -}; +use metrics::{counter, describe_counter, describe_histogram, gauge, histogram}; use metrics_exporter_prometheus::PrometheusBuilder; use metrics_util::MetricKindMask; @@ -38,23 +35,24 @@ fn main() { let clock = Clock::new(); let mut last = None; - increment_counter!("idle_metric"); - gauge!("testing", 42.0); + counter!("idle_metric").increment(1); + gauge!("testing").set(42.0); // Loop over and over, pretending to do some work. loop { - increment_counter!("tcp_server_loops", "system" => "foo"); + counter!("tcp_server_loops", "system" => "foo").increment(1); if let Some(t) = last { let delta: Duration = clock.now() - t; - histogram!("tcp_server_loop_delta_secs", delta, "system" => "foo"); + histogram!("tcp_server_loop_delta_secs", "system" => "foo").record(delta); } let increment_gauge = thread_rng().gen_bool(0.75); + let gauge = gauge!("lucky_iterations"); if increment_gauge { - increment_gauge!("lucky_iterations", 1.0); + gauge.increment(1.0); } else { - decrement_gauge!("lucky_iterations", 1.0); + gauge.decrement(1.0); } last = Some(clock.now()); diff --git a/metrics-exporter-tcp/examples/tcp_server.rs b/metrics-exporter-tcp/examples/tcp_server.rs index 315777b3..1953fa2b 100644 --- a/metrics-exporter-tcp/examples/tcp_server.rs +++ b/metrics-exporter-tcp/examples/tcp_server.rs @@ -1,9 +1,7 @@ use std::thread; use std::time::Duration; -use metrics::{ - decrement_gauge, describe_histogram, histogram, increment_counter, increment_gauge, Unit, -}; +use metrics::{counter, describe_histogram, gauge, histogram, Unit}; use metrics_exporter_tcp::TcpBuilder; use quanta::Clock; @@ -25,18 +23,19 @@ fn main() { ); loop { - increment_counter!("tcp_server_loops", "system" => "foo"); + counter!("tcp_server_loops", "system" => "foo").increment(1); if let Some(t) = last { let delta: Duration = clock.now() - t; - histogram!("tcp_server_loop_delta_secs", delta, "system" => "foo"); + histogram!("tcp_server_loop_delta_secs", "system" => "foo").record(delta); } let increment_gauge = thread_rng().gen_bool(0.75); + let gauge = gauge!("lucky_iterations"); if increment_gauge { - increment_gauge!("lucky_iterations", 1.0); + gauge.increment(1.0); } else { - decrement_gauge!("lucky_iterations", 1.0); + gauge.decrement(1.0); } last = Some(clock.now()); diff --git a/metrics-tracing-context/src/lib.rs b/metrics-tracing-context/src/lib.rs index 677630da..71d219d4 100644 --- a/metrics-tracing-context/src/lib.rs +++ b/metrics-tracing-context/src/lib.rs @@ -45,7 +45,7 @@ //! let span = span!(Level::TRACE, "login", user); //! let _guard = span.enter(); //! -//! counter!("login_attempts", 1, "service" => "login_service"); +//! counter!("login_attempts", "service" => "login_service").increment(1); //! ``` //! //! The code above will emit a increment for a `login_attempts` counter with diff --git a/metrics-tracing-context/tests/integration.rs b/metrics-tracing-context/tests/integration.rs index 35ec2b18..0229393e 100644 --- a/metrics-tracing-context/tests/integration.rs +++ b/metrics-tracing-context/tests/integration.rs @@ -95,7 +95,7 @@ fn test_basic_functionality() { let span = span!(Level::TRACE, "login", user, user.email = email); let _guard = span.enter(); - counter!("login_attempts", 1, "service" => "login_service"); + counter!("login_attempts", "service" => "login_service").increment(1); let snapshot = snapshotter.snapshot().into_vec(); @@ -123,15 +123,16 @@ fn test_macro_forms() { let _guard = span.enter(); // No labels. - counter!("login_attempts_no_labels", 1); + counter!("login_attempts_no_labels").increment(1); // Static labels only. - counter!("login_attempts_static_labels", 1, "service" => "login_service"); + counter!("login_attempts_static_labels", "service" => "login_service").increment(1); // Dynamic labels only. let node_name = "localhost".to_string(); - counter!("login_attempts_dynamic_labels", 1, "node_name" => node_name.clone()); + counter!("login_attempts_dynamic_labels", "node_name" => node_name.clone()).increment(1); // Static and dynamic. - counter!("login_attempts_static_and_dynamic_labels", 1, - "service" => "login_service", "node_name" => node_name.clone()); + counter!("login_attempts_static_and_dynamic_labels", + "service" => "login_service", "node_name" => node_name.clone()) + .increment(1); let snapshot = snapshotter.snapshot().into_vec(); @@ -185,7 +186,7 @@ fn test_no_labels() { let span = span!(Level::TRACE, "login"); let _guard = span.enter(); - counter!("login_attempts", 1); + counter!("login_attempts").increment(1); let snapshot = snapshotter.snapshot().into_vec(); @@ -205,7 +206,7 @@ fn test_multiple_paths_to_the_same_callsite() { let (_guard, snapshotter) = setup(TracingContextLayer::all()); let shared_fn = || { - counter!("my_counter", 1); + counter!("my_counter").increment(1); }; let path1 = || { @@ -279,7 +280,7 @@ fn test_nested_spans() { ); let _guard = span.enter(); - counter!("my_counter", 1); + counter!("my_counter").increment(1); }; let outer = || { @@ -331,7 +332,7 @@ fn test_label_filtering() { let span = span!(Level::TRACE, "login", user, user.email_span = email); let _guard = span.enter(); - counter!("login_attempts", 1, "user.email" => "ferris@rust-lang.org"); + counter!("login_attempts", "user.email" => "ferris@rust-lang.org").increment(1); let snapshot = snapshotter.snapshot().into_vec(); @@ -365,7 +366,7 @@ fn test_label_allowlist() { ); let _guard = span.enter(); - counter!("login_attempts", 1); + counter!("login_attempts").increment(1); let snapshot = snapshotter.snapshot().into_vec(); diff --git a/metrics-util/src/debugging.rs b/metrics-util/src/debugging.rs index b7f88566..31ee34bb 100644 --- a/metrics-util/src/debugging.rs +++ b/metrics-util/src/debugging.rs @@ -382,13 +382,13 @@ mod tests { recorder.install().expect("installing debugging recorder should not fail"); let t1 = std::thread::spawn(|| { - counter!("test_counter", 43); + counter!("test_counter").increment(43); Snapshotter::current_thread_snapshot() }); let t2 = std::thread::spawn(|| { - counter!("test_counter", 47); + counter!("test_counter").increment(47); Snapshotter::current_thread_snapshot() }); diff --git a/metrics-util/src/recoverable.rs b/metrics-util/src/recoverable.rs index 13471025..9fb31236 100644 --- a/metrics-util/src/recoverable.rs +++ b/metrics-util/src/recoverable.rs @@ -258,12 +258,12 @@ mod tests { // Record some metrics, and make sure the atomics for each metric type are // incremented as we would expect them to be. - metrics::counter!("counter", 5); - metrics::increment_gauge!("gauge", 5.0); - metrics::increment_gauge!("gauge", 5.0); - metrics::histogram!("histogram", 5.0); - metrics::histogram!("histogram", 5.0); - metrics::histogram!("histogram", 5.0); + metrics::counter!("counter").increment(5); + metrics::gauge!("gauge").increment(5.0); + metrics::gauge!("gauge").increment(5.0); + metrics::histogram!("histogram").record(5.0); + metrics::histogram!("histogram").record(5.0); + metrics::histogram!("histogram").record(5.0); let _recorder = recoverable.into_inner(); assert_eq!(counter.get(), 5); @@ -272,9 +272,9 @@ mod tests { // Now that we've recovered the recorder, incrementing the same metrics should // not actually increment the value of the atomics for each metric type. - metrics::counter!("counter", 7); - metrics::increment_gauge!("gauge", 7.0); - metrics::histogram!("histogram", 7.0); + metrics::counter!("counter").increment(7); + metrics::gauge!("gauge").increment(7.0); + metrics::histogram!("histogram").record(7.0); assert_eq!(counter.get(), 5); assert_eq!(gauge.get(), 10); @@ -293,12 +293,12 @@ mod tests { // Record some metrics, and make sure the atomics for each metric type are // incremented as we would expect them to be. - metrics::counter!("counter", 5); - metrics::increment_gauge!("gauge", 5.0); - metrics::increment_gauge!("gauge", 5.0); - metrics::histogram!("histogram", 5.0); - metrics::histogram!("histogram", 5.0); - metrics::histogram!("histogram", 5.0); + metrics::counter!("counter").increment(5); + metrics::gauge!("gauge").increment(5.0); + metrics::gauge!("gauge").increment(5.0); + metrics::histogram!("histogram").record(5.0); + metrics::histogram!("histogram").record(5.0); + metrics::histogram!("histogram").record(5.0); drop(recoverable.into_inner()); assert_eq!(counter.get(), 5); @@ -307,9 +307,9 @@ mod tests { // Now that we've recovered the recorder, incrementing the same metrics should // not actually increment the value of the atomics for each metric type. - metrics::counter!("counter", 7); - metrics::increment_gauge!("gauge", 7.0); - metrics::histogram!("histogram", 7.0); + metrics::counter!("counter").increment(7); + metrics::gauge!("gauge").increment(7.0); + metrics::histogram!("histogram").record(7.0); assert_eq!(counter.get(), 5); assert_eq!(gauge.get(), 10); diff --git a/metrics/benches/macros.rs b/metrics/benches/macros.rs index f0d7feec..5ea9c034 100644 --- a/metrics/benches/macros.rs +++ b/metrics/benches/macros.rs @@ -39,7 +39,7 @@ fn macro_benchmark(c: &mut Criterion) { metrics::clear_recorder(); } b.iter(|| { - counter!("counter_bench", 42); + counter!("counter_bench").increment(42); }) }); group.bench_function("uninitialized/with_static_labels", |b| { @@ -47,13 +47,13 @@ fn macro_benchmark(c: &mut Criterion) { metrics::clear_recorder(); } b.iter(|| { - counter!("counter_bench", 42, "request" => "http", "svc" => "admin"); + counter!("counter_bench", "request" => "http", "svc" => "admin").increment(42); }) }); group.bench_function("initialized/no_labels", |b| { reset_recorder(); b.iter(|| { - counter!("counter_bench", 42); + counter!("counter_bench") .increment(42); }); unsafe { metrics::clear_recorder(); @@ -62,7 +62,7 @@ fn macro_benchmark(c: &mut Criterion) { group.bench_function("initialized/with_static_labels", |b| { reset_recorder(); b.iter(|| { - counter!("counter_bench", 42, "request" => "http", "svc" => "admin"); + counter!("counter_bench", "request" => "http", "svc" => "admin").increment(42); }); unsafe { metrics::clear_recorder(); @@ -73,7 +73,7 @@ fn macro_benchmark(c: &mut Criterion) { reset_recorder(); b.iter(move || { - counter!("counter_bench", 42, "request" => "http", "uid" => label_val.clone()); + counter!("counter_bench", "request" => "http", "uid" => label_val.clone()).increment(42); }); unsafe { metrics::clear_recorder(); diff --git a/metrics/examples/basic.rs b/metrics/examples/basic.rs index 4dee080e..a80bdb72 100644 --- a/metrics/examples/basic.rs +++ b/metrics/examples/basic.rs @@ -8,9 +8,8 @@ use std::sync::Arc; use metrics::{ - absolute_counter, counter, decrement_gauge, describe_counter, describe_gauge, - describe_histogram, gauge, histogram, increment_counter, increment_gauge, register_counter, - register_gauge, register_histogram, KeyName, Metadata, SharedString, + counter, describe_counter, describe_gauge, describe_histogram, gauge, histogram, KeyName, + Metadata, SharedString, }; use metrics::{Counter, CounterFn, Gauge, GaugeFn, Histogram, HistogramFn, Key, Recorder, Unit}; @@ -119,54 +118,59 @@ fn main() { ); // And registering them: - let counter1 = register_counter!("test_counter"); + let counter1 = counter!("test_counter"); counter1.increment(1); - let counter2 = register_counter!("test_counter", "type" => "absolute"); + let counter2 = counter!("test_counter", "type" => "absolute"); counter2.absolute(42); - let gauge1 = register_gauge!("test_gauge"); + let gauge1 = gauge!("test_gauge"); gauge1.increment(1.0); - let gauge2 = register_gauge!("test_gauge", "type" => "decrement"); + let gauge2 = gauge!("test_gauge", "type" => "decrement"); gauge2.decrement(1.0); - let gauge3 = register_gauge!("test_gauge", "type" => "set"); + let gauge3 = gauge!("test_gauge", "type" => "set"); gauge3.set(3.1459); - let histogram1 = register_histogram!("test_histogram"); + let histogram1 = histogram!("test_histogram"); histogram1.record(0.57721); // All the supported permutations of `counter!` and its increment/absolute versions: - counter!("bytes_sent", 64); - counter!("bytes_sent", 64, "listener" => "frontend"); - counter!("bytes_sent", 64, "listener" => "frontend", "server" => server_name.clone()); - counter!("bytes_sent", 64, common_labels); - - increment_counter!("requests_processed"); - increment_counter!("requests_processed", "request_type" => "admin"); - increment_counter!("requests_processed", "request_type" => "admin", "server" => server_name.clone()); - increment_counter!("requests_processed", common_labels); - - absolute_counter!("bytes_sent", 64); - absolute_counter!("bytes_sent", 64, "listener" => "frontend"); - absolute_counter!("bytes_sent", 64, "listener" => "frontend", "server" => server_name.clone()); - absolute_counter!("bytes_sent", 64, common_labels); + counter!("bytes_sent").increment(64); + counter!("bytes_sent", "listener" => "frontend").increment(64); + counter!("bytes_sent", "listener" => "frontend", "server" => server_name.clone()).increment(64); + counter!("bytes_sent", common_labels).increment(64); + + counter!("requests_processed").increment(1); + counter!("requests_processed", "request_type" => "admin").increment(1); + counter!("requests_processed", "request_type" => "admin", "server" => server_name.clone()) + .increment(1); + counter!("requests_processed", common_labels).increment(1); + + counter!("bytes_sent").absolute(64); + counter!("bytes_sent", "listener" => "frontend").absolute(64); + counter!("bytes_sent", "listener" => "frontend", "server" => server_name.clone()).absolute(64); + counter!("bytes_sent", common_labels).absolute(64); // All the supported permutations of `gauge!` and its increment/decrement versions: - gauge!("connection_count", 300.0); - gauge!("connection_count", 300.0, "listener" => "frontend"); - gauge!("connection_count", 300.0, "listener" => "frontend", "server" => server_name.clone()); - gauge!("connection_count", 300.0, common_labels); - increment_gauge!("connection_count", 300.0); - increment_gauge!("connection_count", 300.0, "listener" => "frontend"); - increment_gauge!("connection_count", 300.0, "listener" => "frontend", "server" => server_name.clone()); - increment_gauge!("connection_count", 300.0, common_labels); - decrement_gauge!("connection_count", 300.0); - decrement_gauge!("connection_count", 300.0, "listener" => "frontend"); - decrement_gauge!("connection_count", 300.0, "listener" => "frontend", "server" => server_name.clone()); - decrement_gauge!("connection_count", 300.0, common_labels); + gauge!("connection_count").set(300.0); + gauge!("connection_count", "listener" => "frontend").set(300.0); + gauge!("connection_count", "listener" => "frontend", "server" => server_name.clone()) + .set(300.0); + gauge!("connection_count", common_labels).set(300.0); + gauge!("connection_count").increment(300.0); + gauge!("connection_count", "listener" => "frontend").increment(300.0); + gauge!("connection_count", "listener" => "frontend", "server" => server_name.clone()) + .increment(300.0); + gauge!("connection_count", common_labels).increment(300.0); + gauge!("connection_count").decrement(300.0); + gauge!("connection_count", "listener" => "frontend").decrement(300.0); + gauge!("connection_count", "listener" => "frontend", "server" => server_name.clone()) + .decrement(300.0); + gauge!("connection_count", common_labels).decrement(300.0); // All the supported permutations of `histogram!`: - histogram!("svc.execution_time", 70.0); - histogram!("svc.execution_time", 70.0, "type" => "users"); - histogram!("svc.execution_time", 70.0, "type" => "users", "server" => server_name.clone()); - histogram!("svc.execution_time", 70.0, common_labels); + histogram!("svc.execution_time").record(70.0); + histogram!("svc.execution_time", "type" => "users").record(70.0); + histogram!("svc.execution_time", "type" => "users", "server" => server_name.clone()) + .record(70.0); + histogram!("svc.execution_time", common_labels).record(70.0); } diff --git a/metrics/src/lib.rs b/metrics/src/lib.rs index 71ca26ea..6182e852 100644 --- a/metrics/src/lib.rs +++ b/metrics/src/lib.rs @@ -59,14 +59,23 @@ //! Histograms take floating-point 64-bit numbers. //! //! ## Emission -//! Metrics are emitted by utilizing the registration or emission macros. There is a macro for -//! registering and emitting each fundamental metric type: -//! - [`register_counter!`], [`counter!`], and [`increment_counter!`] for counters -//! - [`register_gauge!`], [`gauge!`], [`increment_gauge!`], and [`decrement_gauge!`] for gauges -//! - [`register_histogram!`] and [`histogram!`] for histograms +//! +//! Metrics are emitted by utilizing the emission methods. There is a macro for +//! registering and returning a handle for each fundamental metric type: +//! +//! - [`counter!`] returns the [`Counter`] handle then +//! - [`Counter::increment`] increments the counter. +//! - [`Counter::absolute`] sets the counter. +//! - [`gauge!`] returns the [`Gauge`] handle then +//! - [`Gauge::increment`] increments the gauge. +//! - [`Gauge::decrement`] decrements the gauge. +//! - [`Gauge::set`] sets the gauge. +//! - [`histogram!`] for histograms then +//! - [`Histogram::record`] records a data point. //! //! Additionally, metrics can be described -- setting either the unit of measure or long-form //! description -- by using the `describe_*` macros: +//! //! - [`describe_counter!`] for counters //! - [`describe_gauge!`] for gauges //! - [`describe_histogram!`] for histograms @@ -115,8 +124,8 @@ //! let row_count = run_query(query); //! let delta = start.elapsed(); //! -//! histogram!("process.query_time", delta); -//! counter!("process.query_row_count", row_count); +//! histogram!("process.query_time").record(delta); +//! counter!("process.query_row_count").increment(row_count); //! //! row_count //! } diff --git a/metrics/src/macros.rs b/metrics/src/macros.rs index ab1c0248..1c9b9712 100644 --- a/metrics/src/macros.rs +++ b/metrics/src/macros.rs @@ -74,37 +74,37 @@ macro_rules! key_var { /// # use ::std::convert::From; /// # use ::std::format; /// # use ::std::string::String; -/// # use metrics::register_counter; +/// # use metrics::counter; /// # fn main() { /// // A basic counter: -/// let counter = register_counter!("some_metric_name"); +/// let counter = counter!("some_metric_name"); /// counter.increment(1); /// /// // Specifying labels inline, including using constants for either the key or value: -/// let counter = register_counter!("some_metric_name", "service" => "http"); +/// let counter = counter!("some_metric_name", "service" => "http"); /// counter.absolute(42); /// /// const SERVICE_LABEL: &'static str = "service"; /// const SERVICE_HTTP: &'static str = "http"; -/// let counter = register_counter!("some_metric_name", SERVICE_LABEL => SERVICE_HTTP); +/// let counter = counter!("some_metric_name", SERVICE_LABEL => SERVICE_HTTP); /// counter.increment(123); /// /// // We can also pass labels by giving a vector or slice of key/value pairs. In this scenario, /// // a unit or description can still be passed in their respective positions: /// let dynamic_val = "woo"; /// let labels = [("dynamic_key", format!("{}!", dynamic_val))]; -/// let counter = register_counter!("some_metric_name", &labels); +/// let counter = counter!("some_metric_name", &labels); /// /// // As mentioned in the documentation, metric names also can be owned strings, including ones /// // generated at the callsite via things like `format!`: /// let name = String::from("some_owned_metric_name"); -/// let counter = register_counter!(name); +/// let counter = counter!(name); /// -/// let counter = register_counter!(format!("{}_via_format", "name")); +/// let counter = counter!(format!("{}_via_format", "name")); /// # } /// ``` #[macro_export] -macro_rules! register_counter { +macro_rules! counter { (target: $target:expr, level: $level:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => {{ let metric_key = $crate::key_var!($name $(, $label_key $(=> $label_value)?)*); let metadata = $crate::metadata_var!($target, $level); @@ -112,13 +112,13 @@ macro_rules! register_counter { $crate::recorder().register_counter(&metric_key, metadata) }}; (target: $target:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::register_counter!(target: $target, level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) + $crate::counter!(target: $target, level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) }; (level: $level:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::register_counter!(target: ::std::module_path!(), level: $level, $name $(, $label_key $(=> $label_value)?)*) + $crate::counter!(target: ::std::module_path!(), level: $level, $name $(, $label_key $(=> $label_value)?)*) }; ($name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::register_counter!(target: ::std::module_path!(), level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) + $crate::counter!(target: ::std::module_path!(), level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) }; } @@ -140,38 +140,38 @@ macro_rules! register_counter { /// # use ::std::string::String; /// # use ::std::format; /// # use ::std::convert::From; -/// # use metrics::register_gauge; +/// # use metrics::gauge; /// # fn main() { /// // A basic gauge: -/// let gauge = register_gauge!("some_metric_name"); +/// let gauge = gauge!("some_metric_name"); /// gauge.increment(1.0); /// /// // Specifying labels inline, including using constants for either the key or value: -/// let gauge = register_gauge!("some_metric_name", "service" => "http"); +/// let gauge = gauge!("some_metric_name", "service" => "http"); /// gauge.decrement(42.0); /// /// const SERVICE_LABEL: &'static str = "service"; /// const SERVICE_HTTP: &'static str = "http"; -/// let gauge = register_gauge!("some_metric_name", SERVICE_LABEL => SERVICE_HTTP); +/// let gauge = gauge!("some_metric_name", SERVICE_LABEL => SERVICE_HTTP); /// gauge.increment(3.14); /// /// // We can also pass labels by giving a vector or slice of key/value pairs. In this scenario, /// // a unit or description can still be passed in their respective positions: /// let dynamic_val = "woo"; /// let labels = [("dynamic_key", format!("{}!", dynamic_val))]; -/// let gauge = register_gauge!("some_metric_name", &labels); +/// let gauge = gauge!("some_metric_name", &labels); /// gauge.set(1337.0); /// /// // As mentioned in the documentation, metric names also can be owned strings, including ones /// // generated at the callsite via things like `format!`: /// let name = String::from("some_owned_metric_name"); -/// let gauge = register_gauge!(name); +/// let gauge = gauge!(name); /// -/// let gauge = register_gauge!(format!("{}_via_format", "name")); +/// let gauge = gauge!(format!("{}_via_format", "name")); /// # } /// ``` #[macro_export] -macro_rules! register_gauge { +macro_rules! gauge { (target: $target:expr, level: $level:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => {{ let metric_key = $crate::key_var!($name $(, $label_key $(=> $label_value)?)*); let metadata = $crate::metadata_var!($target, $level); @@ -179,13 +179,13 @@ macro_rules! register_gauge { $crate::recorder().register_gauge(&metric_key, metadata) }}; (target: $target:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::register_gauge!(target: $target, level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) + $crate::gauge!(target: $target, level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) }; (level: $level:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::register_gauge!(target: ::std::module_path!(), level: $level, $name $(, $label_key $(=> $label_value)?)*) + $crate::gauge!(target: ::std::module_path!(), level: $level, $name $(, $label_key $(=> $label_value)?)*) }; ($name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::register_gauge!(target: ::std::module_path!(), level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) + $crate::gauge!(target: ::std::module_path!(), level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) }; } @@ -207,35 +207,35 @@ macro_rules! register_gauge { /// # use ::std::string::String; /// # use ::std::format; /// # use ::std::convert::From; -/// # use metrics::register_histogram; +/// # use metrics::histogram; /// # fn main() { /// // A basic histogram: -/// let histogram = register_histogram!("some_metric_name"); +/// let histogram = histogram!("some_metric_name"); /// histogram.record(1.0); /// /// // Specifying labels inline, including using constants for either the key or value: -/// let histogram = register_histogram!("some_metric_name", "service" => "http"); +/// let histogram = histogram!("some_metric_name", "service" => "http"); /// /// const SERVICE_LABEL: &'static str = "service"; /// const SERVICE_HTTP: &'static str = "http"; -/// let histogram = register_histogram!("some_metric_name", SERVICE_LABEL => SERVICE_HTTP); +/// let histogram = histogram!("some_metric_name", SERVICE_LABEL => SERVICE_HTTP); /// /// // We can also pass labels by giving a vector or slice of key/value pairs. In this scenario, /// // a unit or description can still be passed in their respective positions: /// let dynamic_val = "woo"; /// let labels = [("dynamic_key", format!("{}!", dynamic_val))]; -/// let histogram = register_histogram!("some_metric_name", &labels); +/// let histogram = histogram!("some_metric_name", &labels); /// /// // As mentioned in the documentation, metric names also can be owned strings, including ones /// // generated at the callsite via things like `format!`: /// let name = String::from("some_owned_metric_name"); -/// let histogram = register_histogram!(name); +/// let histogram = histogram!(name); /// -/// let histogram = register_histogram!(format!("{}_via_format", "name")); +/// let histogram = histogram!(format!("{}_via_format", "name")); /// # } /// ``` #[macro_export] -macro_rules! register_histogram { +macro_rules! histogram { (target: $target:expr, level: $level:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => {{ let metric_key = $crate::key_var!($name $(, $label_key $(=> $label_value)?)*); let metadata = $crate::metadata_var!($target, $level); @@ -243,13 +243,13 @@ macro_rules! register_histogram { $crate::recorder().register_histogram(&metric_key, metadata) }}; (target: $target:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::register_histogram!(target: $target, level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) + $crate::histogram!(target: $target, level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) }; (level: $level:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::register_histogram!(target: ::std::module_path!(), level: $level, $name $(, $label_key $(=> $label_value)?)*) + $crate::histogram!(target: ::std::module_path!(), level: $level, $name $(, $label_key $(=> $label_value)?)*) }; ($name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::register_histogram!(target: ::std::module_path!(), level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) + $crate::histogram!(target: ::std::module_path!(), level: $crate::Level::INFO, $name $(, $label_key $(=> $label_value)?)*) }; } @@ -413,461 +413,3 @@ macro_rules! describe_histogram { $crate::describe!(describe_histogram, $name, $description) }; } - -#[doc(hidden)] -#[macro_export] -macro_rules! method { - ($register:ident, $method:ident, target: $target:expr, level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)*) => { - let metric_key = $crate::key_var!($name $(, $label_key $(=> $label_value)?)*); - let metadata = $crate::metadata_var!($target, $level); - - if let ::core::option::Option::Some(recorder) = $crate::try_recorder() { - let handle = recorder.$register(&metric_key, &metadata); - handle.$method($op_val); - } - }; - ($register:ident, $method:ident, target: $target:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)*) => { - $crate::method!($register, $method, target: $target, level: $crate::Level::INFO, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - ($register:ident, $method:ident, level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)*) => { - $crate::method!($register, $method, target: ::std::module_path!(), level: $level, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - ($register:ident, $method:ident, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)*) => { - $crate::method!($register, $method, target: ::std::module_path!(), level: $crate::Level::INFO, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; -} - -/// Increments a counter. -/// -/// Counters represent a single monotonic value, which means the value can only be incremented, not -/// decremented, and always starts out with an initial value of zero. -/// -/// Metric names are shown below using string literals, but they can also be owned `String` values, -/// which includes using macros such as `format!` directly at the callsite. String literals are -/// preferred for performance where possible. -/// -/// # Example -/// ``` -/// # #![no_implicit_prelude] -/// # use ::std::convert::From; -/// # use ::std::format; -/// # use ::std::string::String; -/// # use metrics::{counter, Level}; -/// # fn main() { -/// // A basic counter: -/// counter!("some_metric_name", 12); -/// -/// // A basic counter with level and target specified: -/// counter!(target: "specific_target", level: Level::DEBUG, "some_metric_name", 12); -/// -/// // Specifying labels inline, including using constants for either the key or value: -/// counter!("some_metric_name", 12, "service" => "http"); -/// -/// const SERVICE_LABEL: &'static str = "service"; -/// const SERVICE_HTTP: &'static str = "http"; -/// counter!("some_metric_name", 12, SERVICE_LABEL => SERVICE_HTTP); -/// -/// // We can also pass labels by giving a vector or slice of key/value pairs: -/// let dynamic_val = "woo"; -/// let labels = [("dynamic_key", format!("{}!", dynamic_val))]; -/// counter!("some_metric_name", 12, &labels); -/// -/// // As mentioned in the documentation, metric names also can be owned strings, including ones -/// // generated at the callsite via things like `format!`: -/// let name = String::from("some_owned_metric_name"); -/// counter!(name, 12); -/// -/// counter!(format!("{}_via_format", "name"), 12); -/// # } -/// ``` -#[macro_export] -macro_rules! counter { - (target: $target:expr, level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, increment, target: $target, level: $level, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - (target: $target:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, increment, target: $target, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - (level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, increment, level: $level, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - ($name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, increment, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; -} - -/// Increments a gauge. -/// -/// Gauges represent a single value that can go up or down over time, and always starts out with an -/// initial value of zero. -/// -/// Metric names are shown below using string literals, but they can also be owned `String` values, -/// which includes using macros such as `format!` directly at the callsite. String literals are -/// preferred for performance where possible. -/// -/// # Example -/// ``` -/// # #![no_implicit_prelude] -/// # use ::std::convert::From; -/// # use ::std::string::String; -/// # use ::std::format; -/// # use metrics::{increment_gauge, Level}; -/// # fn main() { -/// // A basic gauge: -/// increment_gauge!("some_metric_name", 42.2222); -/// -/// // A basic gauge with level and target specified: -/// increment_gauge!(target: "specific_target", level: Level::DEBUG, "some_metric_name", 42.2222); -/// -/// // Specifying labels inline, including using constants for either the key or value: -/// increment_gauge!("some_metric_name", 66.6666, "service" => "http"); -/// -/// const SERVICE_LABEL: &'static str = "service"; -/// const SERVICE_HTTP: &'static str = "http"; -/// increment_gauge!("some_metric_name", 66.6666, SERVICE_LABEL => SERVICE_HTTP); -/// -/// // We can also pass labels by giving a vector or slice of key/value pairs: -/// let dynamic_val = "woo"; -/// let labels = [("dynamic_key", format!("{}!", dynamic_val))]; -/// increment_gauge!("some_metric_name", 42.42, &labels); -/// -/// // As mentioned in the documentation, metric names also can be owned strings, including ones -/// // generated at the callsite via things like `format!`: -/// let name = String::from("some_owned_metric_name"); -/// increment_gauge!(name, 800.85); -/// -/// increment_gauge!(format!("{}_via_format", "name"), 3.14); -/// # } -/// ``` -#[macro_export] -macro_rules! increment_gauge { - (target: $target:expr, level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, increment, target: $target, level: $level, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - (target: $target:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, increment, target: $target, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - (level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, increment, level: $level, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - ($name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, increment, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; -} - -/// Decrements a gauge. -/// -/// Gauges represent a single value that can go up or down over time, and always starts out with an -/// initial value of zero. -/// -/// Metric names are shown below using string literals, but they can also be owned `String` values, -/// which includes using macros such as `format!` directly at the callsite. String literals are -/// preferred for performance where possible. -/// -/// # Example -/// ``` -/// # #![no_implicit_prelude] -/// # use ::std::convert::From; -/// # use ::std::format; -/// # use ::std::string::String; -/// # use metrics::{decrement_gauge, Level}; -/// # fn main() { -/// // A basic gauge: -/// decrement_gauge!("some_metric_name", 42.2222); -/// -/// // A basic gauge with level and target specified: -/// decrement_gauge!(target: "specific_target", level: Level::DEBUG, "some_metric_name", 42.2222); -/// -/// // Specifying labels inline, including using constants for either the key or value: -/// decrement_gauge!("some_metric_name", 66.6666, "service" => "http"); -/// -/// const SERVICE_LABEL: &'static str = "service"; -/// const SERVICE_HTTP: &'static str = "http"; -/// decrement_gauge!("some_metric_name", 66.6666, SERVICE_LABEL => SERVICE_HTTP); -/// -/// // We can also pass labels by giving a vector or slice of key/value pairs: -/// let dynamic_val = "woo"; -/// let labels = [("dynamic_key", format!("{}!", dynamic_val))]; -/// decrement_gauge!("some_metric_name", 42.42, &labels); -/// -/// // As mentioned in the documentation, metric names also can be owned strings, including ones -/// // generated at the callsite via things like `format!`: -/// let name = String::from("some_owned_metric_name"); -/// decrement_gauge!(name, 800.85); -/// -/// decrement_gauge!(format!("{}_via_format", "name"), 3.14); -/// # } -/// ``` -#[macro_export] -macro_rules! decrement_gauge { - (target: $target:expr, level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, decrement, target: $target, level: $level, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - (target: $target:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, decrement, target: $target, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - (level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, decrement, level: $level, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - ($name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, decrement, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; -} - -/// Sets a counter to an absolute value. -/// -/// Counters represent a single monotonic value, which means the value can only be incremented, not -/// decremented, and will always start out with an initial value of zero. -/// -/// Using this macro, users can specify an absolute value for the counter instead of the typical -/// delta. This can be useful when dealing with forwarding metrics from an external system into the -/// normal application metrics, without having to track the delta of the metrics from the external -/// system. Users should beware, though, that implementations will enforce the monotonicity -/// property of counters by refusing to update the value unless it is greater than current value of -/// the counter. -/// -/// Metric names are shown below using string literals, but they can also be owned `String` values, -/// which includes using macros such as `format!` directly at the callsite. String literals are -/// preferred for performance where possible. -/// -/// # Example -/// ``` -/// # #![no_implicit_prelude] -/// # use ::std::convert::From; -/// # use ::std::format; -/// # use ::std::string::String; -/// # use metrics::{absolute_counter, Level}; -/// # fn main() { -/// // A basic counter: -/// absolute_counter!("some_metric_name", 12); -/// -/// // A basic counter with level and target specified: -/// absolute_counter!(target: "specific_target", level: Level::DEBUG, "some_metric_name", 12); -/// -/// // Specifying labels inline, including using constants for either the key or value: -/// absolute_counter!("some_metric_name", 13, "service" => "http"); -/// -/// const SERVICE_LABEL: &'static str = "service"; -/// const SERVICE_HTTP: &'static str = "http"; -/// absolute_counter!("some_metric_name", 13, SERVICE_LABEL => SERVICE_HTTP); -/// -/// // We can also pass labels by giving a vector or slice of key/value pairs: -/// let dynamic_val = "woo"; -/// let labels = [("dynamic_key", format!("{}!", dynamic_val))]; -/// absolute_counter!("some_metric_name", 14, &labels); -/// -/// // As mentioned in the documentation, metric names also can be owned strings, including ones -/// // generated at the callsite via things like `format!`: -/// let name = String::from("some_owned_metric_name"); -/// absolute_counter!(name, 15); -/// -/// absolute_counter!(format!("{}_via_format", "name"), 16); -/// # } -/// ``` -#[macro_export] -macro_rules! absolute_counter { - (target: $target:expr, level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, absolute, target: $target, level: $level, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - (target: $target:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, absolute, target: $target, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - (level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, absolute, level: $level, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - ($name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, absolute, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; -} - -/// Updates a gauge. -/// -/// Gauges represent a single value that can go up or down over time, and always starts out with an -/// initial value of zero. -/// -/// Metric names are shown below using string literals, but they can also be owned `String` values, -/// which includes using macros such as `format!` directly at the callsite. String literals are -/// preferred for performance where possible. -/// -/// # Example -/// ``` -/// # #![no_implicit_prelude] -/// # use ::std::convert::From; -/// # use ::std::format; -/// # use ::std::string::String; -/// # use metrics::{gauge, Level}; -/// # fn main() { -/// // A basic gauge: -/// gauge!("some_metric_name", 42.2222); -/// -/// // A basic gauge with level and target specified: -/// gauge!(target: "specific_target", level: Level::DEBUG, "some_metric_name", 42.2222); -/// -/// // Specifying labels inline, including using constants for either the key or value: -/// gauge!("some_metric_name", 66.6666, "service" => "http"); -/// -/// const SERVICE_LABEL: &'static str = "service"; -/// const SERVICE_HTTP: &'static str = "http"; -/// gauge!("some_metric_name", 66.6666, SERVICE_LABEL => SERVICE_HTTP); -/// -/// // We can also pass labels by giving a vector or slice of key/value pairs: -/// let dynamic_val = "woo"; -/// let labels = [("dynamic_key", format!("{}!", dynamic_val))]; -/// gauge!("some_metric_name", 42.42, &labels); -/// -/// // As mentioned in the documentation, metric names also can be owned strings, including ones -/// // generated at the callsite via things like `format!`: -/// let name = String::from("some_owned_metric_name"); -/// gauge!(name, 800.85); -/// -/// gauge!(format!("{}_via_format", "name"), 3.14); -/// # } -/// ``` -#[macro_export] -macro_rules! gauge { - (target: $target:expr, level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, set, target: $target, level: $level, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - (target: $target:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, set, target: $target, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - (level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, set, level: $level, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; - ($name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_gauge, set, $name, $op_val $(, $label_key $(=> $label_value)?)*) - }; -} - -/// Records a histogram. -/// -/// Histograms measure the distribution of values for a given set of measurements, and start with no -/// initial values. -/// -/// # Implicit conversions -/// Histograms are represented as `f64` values, but often come from another source, such as a time -/// measurement. By default, `histogram!` will accept a `f64` directly or a -/// [`Duration`](std::time::Duration), which uses the floating-point number of seconds represents by -/// the duration. -/// -/// External libraries and applications can create their own conversions by implementing the -/// [`IntoF64`](crate::IntoF64) trait for their types, which is required for the value being passed to `histogram!`. -/// -/// Metric names are shown below using string literals, but they can also be owned `String` values, -/// which includes using macros such as `format!` directly at the callsite. String literals are -/// preferred for performance where possible. -/// -/// # Example -/// ``` -/// # #![no_implicit_prelude] -/// # use ::std::convert::From; -/// # use ::std::format; -/// # use ::std::string::String; -/// # use ::std as std; -/// # use metrics::{histogram, Level}; -/// # use std::time::Duration; -/// # fn main() { -/// // A basic histogram: -/// histogram!("some_metric_name", 34.3); -/// -/// // A basic histogram with level and target specified: -/// histogram!(target: "specific_target", level: Level::DEBUG, "some_metric_name", 34.3); -/// -/// // An implicit conversion from `Duration`: -/// let d = Duration::from_millis(17); -/// histogram!("some_metric_name", d); -/// -/// // Specifying labels inline, including using constants for either the key or value: -/// histogram!("some_metric_name", 38.0, "service" => "http"); -/// -/// const SERVICE_LABEL: &'static str = "service"; -/// const SERVICE_HTTP: &'static str = "http"; -/// histogram!("some_metric_name", 38.0, SERVICE_LABEL => SERVICE_HTTP); -/// -/// // We can also pass labels by giving a vector or slice of key/value pairs: -/// let dynamic_val = "woo"; -/// let labels = [("dynamic_key", format!("{}!", dynamic_val))]; -/// histogram!("some_metric_name", 1337.5, &labels); -/// -/// // As mentioned in the documentation, metric names also can be owned strings, including ones -/// // generated at the callsite via things like `format!`: -/// let name = String::from("some_owned_metric_name"); -/// histogram!(name, 800.85); -/// -/// histogram!(format!("{}_via_format", "name"), 3.14); -/// # } -/// ``` -#[macro_export] -macro_rules! histogram { - (target: $target:expr, level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_histogram, record, target: $target, level: $level, $name, $crate::__into_f64($op_val) $(, $label_key $(=> $label_value)?)*) - }; - (target: $target:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_histogram, record, target: $target, $name, $crate::__into_f64($op_val) $(, $label_key $(=> $label_value)?)*) - }; - (level: $level:expr, $name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_histogram, record, level: $level, $name, $crate::__into_f64($op_val) $(, $label_key $(=> $label_value)?)*) - }; - ($name:expr, $op_val:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_histogram, record, $name, $crate::__into_f64($op_val) $(, $label_key $(=> $label_value)?)*) - }; -} - -/// Increments a counter. -/// -/// Counters represent a single monotonic value, which means the value can only be incremented, not -/// decremented, and always starts out with an initial value of zero. -/// -/// Metric names are shown below using string literals, but they can also be owned `String` values, -/// which includes using macros such as `format!` directly at the callsite. String literals are -/// preferred for performance where possible. -/// -/// # Example -/// ``` -/// # #![no_implicit_prelude] -/// # use ::std::convert::From; -/// # use ::std::format; -/// # use ::std::string::String; -/// # use metrics::{counter, Level}; -/// # fn main() { -/// // A basic counter: -/// counter!("some_metric_name", 12); -/// -/// // A basic counter with level and target specified: -/// counter!(target: "specific_target", level: Level::DEBUG, "some_metric_name", 12); -/// -/// // Specifying labels inline, including using constants for either the key or value: -/// counter!("some_metric_name", 12, "service" => "http"); -/// -/// const SERVICE_LABEL: &'static str = "service"; -/// const SERVICE_HTTP: &'static str = "http"; -/// counter!("some_metric_name", 12, SERVICE_LABEL => SERVICE_HTTP); -/// -/// // We can also pass labels by giving a vector or slice of key/value pairs: -/// let dynamic_val = "woo"; -/// let labels = [("dynamic_key", format!("{}!", dynamic_val))]; -/// counter!("some_metric_name", 12, &labels); -/// -/// // As mentioned in the documentation, metric names also can be owned strings, including ones -/// // generated at the callsite via things like `format!`: -/// let name = String::from("some_owned_metric_name"); -/// counter!(name, 12); -/// -/// counter!(format!("{}_via_format", "name"), 12); -/// # } -/// ``` -#[macro_export] -macro_rules! increment_counter { - (target: $target:expr, level: $level:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, increment, target: $target, level: $level, $name, 1 $(, $label_key $(=> $label_value)?)*) - }; - (target: $target:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, increment, target: $target, $name, 1 $(, $label_key $(=> $label_value)?)*) - }; - (level: $level:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, increment, level: $level, $name, 1 $(, $label_key $(=> $label_value)?)*) - }; - ($name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { - $crate::method!(register_counter, increment, $name, 1 $(, $label_key $(=> $label_value)?)*) - }; -} diff --git a/metrics/tests/macros/01_basic.rs b/metrics/tests/macros/01_basic.rs index 11fca299..3b539956 100644 --- a/metrics/tests/macros/01_basic.rs +++ b/metrics/tests/macros/01_basic.rs @@ -1,19 +1,19 @@ -use metrics::{counter, describe_counter, register_counter, Unit}; +use metrics::{counter, describe_counter, Unit}; #[allow(dead_code)] fn literal_key() { describe_counter!("abcdef", "a counter"); describe_counter!("abcdef", Unit::Nanoseconds, "a counter"); - let _ = register_counter!("abcdef"); - counter!("abcdef", 1); + let _ = counter!("abcdef"); + counter!("abcdef").increment(1); } #[allow(dead_code)] fn literal_key_literal_labels() { describe_counter!("abcdef", "a counter"); describe_counter!("abcdef", Unit::Nanoseconds, "a counter"); - let _ = register_counter!("abcdef", "uvw" => "xyz"); - counter!("abcdef", 1, "uvw" => "xyz"); + let _ = counter!("abcdef", "uvw" => "xyz"); + counter!("abcdef", "uvw" => "xyz").increment(1); } #[allow(dead_code)] @@ -21,8 +21,8 @@ fn nonliteral_key() { let some_u16 = 0u16; describe_counter!(format!("response_status_{}", some_u16), "a counter"); describe_counter!(format!("response_status_{}", some_u16), Unit::Nanoseconds, "a counter"); - let _ = register_counter!(format!("response_status_{}", some_u16)); - counter!(format!("response_status_{}", some_u16), 1); + let _ = counter!(format!("response_status_{}", some_u16)); + counter!(format!("response_status_{}", some_u16)).increment(1); } #[allow(dead_code)] @@ -30,8 +30,8 @@ fn nonliteral_key_literal_labels() { let some_u16 = 0u16; describe_counter!(format!("response_status_{}", some_u16), "a counter"); describe_counter!(format!("response_status_{}", some_u16), Unit::Nanoseconds, "a counter"); - let _ = register_counter!(format!("response_status_{}", some_u16), "uvw" => "xyz"); - counter!(format!("response_status_{}", some_u16), 1, "uvw" => "xyz"); + let _ = counter!(format!("response_status_{}", some_u16), "uvw" => "xyz"); + counter!(format!("response_status_{}", some_u16), "uvw" => "xyz").increment(1); } #[allow(dead_code)] @@ -41,8 +41,8 @@ fn nonliteral_key_nonliteral_labels() { let labels = [("uvw", format!("{}!", dynamic_val))]; describe_counter!(format!("response_status_{}", some_u16), "a counter"); describe_counter!(format!("response_status_{}", some_u16), Unit::Nanoseconds, "a counter"); - let _ = register_counter!(format!("response_status_{}", some_u16), &labels); - counter!(format!("response_status_{}", some_u16), 12, &labels); + let _ = counter!(format!("response_status_{}", some_u16), &labels); + counter!(format!("response_status_{}", some_u16), &labels).increment(12); } #[allow(dead_code)] @@ -50,8 +50,8 @@ fn const_key() { const KEY: &str = "abcdef"; describe_counter!(KEY, "a counter"); describe_counter!(KEY, Unit::Nanoseconds, "a counter"); - let _ = register_counter!(KEY); - counter!(KEY, 17); + let _ = counter!(KEY); + counter!(KEY).increment(17); } #[allow(dead_code)] diff --git a/metrics/tests/macros/02_trailing_comma.rs b/metrics/tests/macros/02_trailing_comma.rs index 2cc62653..fa7863f5 100644 --- a/metrics/tests/macros/02_trailing_comma.rs +++ b/metrics/tests/macros/02_trailing_comma.rs @@ -2,22 +2,22 @@ use metrics::counter; #[allow(dead_code)] fn no_trailing_comma() { - counter!("qwe", 1); + counter!("qwe").increment(1); counter!( - "qwe", 1, + "qwe", "foo" => "bar" - ); - counter!("qwe", 1, vec![]); + ).increment(1); + counter!("qwe", vec![]).increment(1); } #[allow(dead_code)] fn with_trailing_comma() { - counter!("qwe", 1,); + counter!("qwe",); counter!( - "qwe", 1, + "qwe", "foo" => "bar", - ); - counter!("qwe", 1, vec![],); + ).increment(1); + counter!("qwe", vec![],).increment(1); } fn main() {} diff --git a/metrics/tests/macros/03_mod_aliasing.rs b/metrics/tests/macros/03_mod_aliasing.rs index 815c0019..dac8537f 100644 --- a/metrics/tests/macros/03_mod_aliasing.rs +++ b/metrics/tests/macros/03_mod_aliasing.rs @@ -11,12 +11,14 @@ pub mod framework { use framework::*; // This exposes mod `framework::metrics`. - #[inline] pub fn register_metrics() { - ::metrics::register_counter!( + ::metrics::counter!( metrics::UPLOAD_METRIC_NAME, - &[(metrics::UPLOAD_METRIC_LABEL_PROCESS_TYPE, ""), (metrics::UPLOAD_METRIC_LABEL_SUCCESS, ""),] + &[ + (metrics::UPLOAD_METRIC_LABEL_PROCESS_TYPE, ""), + (metrics::UPLOAD_METRIC_LABEL_SUCCESS, ""), + ] ); }