Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

metrics: rename *_poll_count_* to *_poll_time_* #6924

Merged
merged 2 commits into from
Oct 22, 2024
Merged

metrics: rename *_poll_count_* to *_poll_time_* #6924

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9b25f46
metrics: rename `*_poll_count_*` to `*_poll_time_*`
rcoh Oct 21, 2024
07ae5b1
Fix missed methods
rcoh Oct 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 30 additions & 21 deletions tokio/src/runtime/builder.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1099,12 +1099,12 @@ impl Builder {
///
/// The histogram uses fixed bucket sizes. In other words, the histogram
/// buckets are not dynamic based on input values. Use the
/// `metrics_poll_count_histogram_` builder methods to configure the
/// `metrics_poll_time_histogram` builder methods to configure the
/// histogram details.
///
/// By default, a linear histogram with 10 buckets each 100 microseconds wide will be used.
/// This has an extremely low memory footprint, but may not provide enough granularity. For
/// better granularity with low memory usage, use [`metrics_poll_count_histogram_configuration()`]
/// better granularity with low memory usage, use [`metrics_poll_time_histogram_configuration()`]
/// to select [`LogHistogram`] instead.
///
/// # Examples
Expand All @@ -1113,26 +1113,35 @@ impl Builder {
/// use tokio::runtime;
///
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .build()
/// .unwrap();
/// # // Test default values here
/// # fn us(n: u64) -> std::time::Duration { std::time::Duration::from_micros(n) }
/// # let m = rt.handle().metrics();
/// # assert_eq!(m.poll_count_histogram_num_buckets(), 10);
/// # assert_eq!(m.poll_count_histogram_bucket_range(0), us(0)..us(100));
/// # assert_eq!(m.poll_count_histogram_bucket_range(1), us(100)..us(200));
/// # assert_eq!(m.poll_time_histogram_num_buckets(), 10);
/// # assert_eq!(m.poll_time_histogram_bucket_range(0), us(0)..us(100));
/// # assert_eq!(m.poll_time_histogram_bucket_range(1), us(100)..us(200));
/// ```
///
/// [`Handle::metrics()`]: crate::runtime::Handle::metrics
/// [`Instant::now()`]: std::time::Instant::now
/// [`LogHistogram`]: crate::runtime::LogHistogram
/// [`metrics_poll_count_histogram_configuration()`]: Builder::metrics_poll_count_histogram_configuration
pub fn enable_metrics_poll_count_histogram(&mut self) -> &mut Self {
/// [`metrics_poll_time_histogram_configuration()`]: Builder::metrics_poll_time_histogram_configuration
pub fn enable_metrics_poll_time_histogram(&mut self) -> &mut Self {
self.metrics_poll_count_histogram_enable = true;
self
}

/// Deprecated. Use [`enable_metrics_poll_time_histogram()`] instead.
///
/// [`enable_metrics_poll_time_histogram()`]: Builder::enable_metrics_poll_time_histogram
#[deprecated(note = "`poll_count_histogram` related methods have been renamed `poll_time_histogram` to better reflect their functionality.")]
#[doc(hidden)]
pub fn enable_metrics_poll_count_histogram(&mut self) -> &mut Self {
self.enable_metrics_poll_time_histogram()
}

/// Sets the histogram scale for tracking the distribution of task poll
/// times.
///
Expand All @@ -1151,12 +1160,12 @@ impl Builder {
///
/// # #[allow(deprecated)]
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_count_histogram_scale(HistogramScale::Log)
/// .build()
/// .unwrap();
/// ```
#[deprecated(note = "use metrics_poll_count_histogram_configuration")]
#[deprecated(note = "use `metrics_poll_time_histogram_configuration`")]
pub fn metrics_poll_count_histogram_scale(&mut self, histogram_scale: crate::runtime::HistogramScale) -> &mut Self {
self.metrics_poll_count_histogram.legacy_mut(|b|b.scale = histogram_scale);
self
Expand All @@ -1175,8 +1184,8 @@ impl Builder {
/// use tokio::runtime::{HistogramConfiguration, LogHistogram};
///
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .metrics_poll_count_histogram_configuration(
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_time_histogram_configuration(
/// HistogramConfiguration::log(LogHistogram::default())
/// )
/// .build()
Expand All @@ -1190,8 +1199,8 @@ impl Builder {
/// use tokio::runtime::HistogramConfiguration;
///
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .metrics_poll_count_histogram_configuration(
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_time_histogram_configuration(
/// HistogramConfiguration::linear(Duration::from_micros(10), 100)
/// )
/// .build()
Expand All @@ -1208,8 +1217,8 @@ impl Builder {
/// use tokio::runtime::{HistogramConfiguration, LogHistogram};
///
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .metrics_poll_count_histogram_configuration(
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_time_histogram_configuration(
/// HistogramConfiguration::log(LogHistogram::builder()
/// .max_value(Duration::from_secs(120))
/// .min_value(Duration::from_nanos(100))
Expand All @@ -1224,7 +1233,7 @@ impl Builder {
///
/// [`LogHistogram`]: crate::runtime::LogHistogram
/// [default configuration]: crate::runtime::LogHistogramBuilder
pub fn metrics_poll_count_histogram_configuration(&mut self, configuration: HistogramConfiguration) -> &mut Self {
pub fn metrics_poll_time_histogram_configuration(&mut self, configuration: HistogramConfiguration) -> &mut Self {
Darksonn marked this conversation as resolved.
Show resolved Hide resolved
self.metrics_poll_count_histogram.histogram_type = configuration.inner;
self
}
Expand All @@ -1251,12 +1260,12 @@ impl Builder {
///
/// # #[allow(deprecated)]
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_count_histogram_resolution(Duration::from_micros(100))
/// .build()
/// .unwrap();
/// ```
#[deprecated(note = "use metrics_poll_count_histogram_configuration")]
#[deprecated(note = "use `metrics_poll_time_histogram_configuration`")]
pub fn metrics_poll_count_histogram_resolution(&mut self, resolution: Duration) -> &mut Self {
assert!(resolution > Duration::from_secs(0));
// Sanity check the argument and also make the cast below safe.
Expand Down Expand Up @@ -1285,12 +1294,12 @@ impl Builder {
///
/// # #[allow(deprecated)]
/// let rt = runtime::Builder::new_multi_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .metrics_poll_count_histogram_buckets(15)
/// .build()
/// .unwrap();
/// ```
#[deprecated(note = "use `metrics_poll_count_histogram_configuration")]
#[deprecated(note = "use `metrics_poll_time_histogram_configuration`")]
pub fn metrics_poll_count_histogram_buckets(&mut self, buckets: usize) -> &mut Self {
self.metrics_poll_count_histogram.legacy_mut(|b|b.num_buckets = buckets);
self
Expand Down
81 changes: 56 additions & 25 deletions tokio/src/runtime/metrics/runtime.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -731,7 +731,7 @@ impl RuntimeMetrics {
///
/// Task poll times are not instrumented by default as doing so requires
/// calling [`Instant::now()`] twice per task poll. The feature is enabled
/// by calling [`enable_metrics_poll_count_histogram()`] when building the
/// by calling [`enable_metrics_poll_time_histogram()`] when building the
/// runtime.
///
/// # Examples
Expand All @@ -741,33 +741,39 @@ impl RuntimeMetrics {
///
/// fn main() {
/// runtime::Builder::new_current_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .build()
/// .unwrap()
/// .block_on(async {
/// let metrics = Handle::current().metrics();
/// let enabled = metrics.poll_count_histogram_enabled();
/// let enabled = metrics.poll_time_histogram_enabled();
///
/// println!("Tracking task poll time distribution: {:?}", enabled);
/// });
/// }
/// ```
///
/// [`enable_metrics_poll_count_histogram()`]: crate::runtime::Builder::enable_metrics_poll_count_histogram
/// [`enable_metrics_poll_time_histogram()`]: crate::runtime::Builder::enable_metrics_poll_time_histogram
/// [`Instant::now()`]: std::time::Instant::now
pub fn poll_count_histogram_enabled(&self) -> bool {
pub fn poll_time_histogram_enabled(&self) -> bool {
self.handle
.inner
.worker_metrics(0)
.poll_count_histogram
.is_some()
}

#[deprecated(note = "Renamed to `poll_time_histogram_enabled`")]
#[doc(hidden)]
pub fn poll_count_histogram_enabled(&self) -> bool {
self.poll_time_histogram_enabled()
}

/// Returns the number of histogram buckets tracking the distribution of
/// task poll times.
///
/// This value is configured by calling
/// [`metrics_poll_count_histogram_configuration()`] when building the runtime.
/// [`metrics_poll_time_histogram_configuration()`] when building the runtime.
///
/// # Examples
///
Expand All @@ -776,21 +782,21 @@ impl RuntimeMetrics {
///
/// fn main() {
/// runtime::Builder::new_current_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .build()
/// .unwrap()
/// .block_on(async {
/// let metrics = Handle::current().metrics();
/// let buckets = metrics.poll_count_histogram_num_buckets();
/// let buckets = metrics.poll_time_histogram_num_buckets();
///
/// println!("Histogram buckets: {:?}", buckets);
/// });
/// }
/// ```
///
/// [`metrics_poll_count_histogram_configuration()`]:
/// crate::runtime::Builder::metrics_poll_count_histogram_configuration
pub fn poll_count_histogram_num_buckets(&self) -> usize {
/// [`metrics_poll_time_histogram_configuration()`]:
/// crate::runtime::Builder::metrics_poll_time_histogram_configuration
pub fn poll_time_histogram_num_buckets(&self) -> usize {
self.handle
.inner
.worker_metrics(0)
Expand All @@ -800,15 +806,24 @@ impl RuntimeMetrics {
.unwrap_or_default()
}

/// Deprecated. Use [`poll_time_histogram_num_buckets()`] instead.
///
/// [`poll_time_histogram_num_buckets()`]: Self::poll_time_histogram_num_buckets
#[doc(hidden)]
#[deprecated(note = "renamed to `poll_time_histogram_num_buckets`.")]
pub fn poll_count_histogram_num_buckets(&self) -> usize {
self.poll_time_histogram_num_buckets()
}

/// Returns the range of task poll times tracked by the given bucket.
///
/// This value is configured by calling
/// [`metrics_poll_count_histogram_configuration()`] when building the runtime.
/// [`metrics_poll_time_histogram_configuration()`] when building the runtime.
///
/// # Panics
///
/// The method panics if `bucket` represents an invalid bucket index, i.e.
/// is greater than or equal to `poll_count_histogram_num_buckets()`.
/// is greater than or equal to `poll_time_histogram_num_buckets()`.
///
/// # Examples
///
Expand All @@ -817,25 +832,25 @@ impl RuntimeMetrics {
///
/// fn main() {
/// runtime::Builder::new_current_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .build()
/// .unwrap()
/// .block_on(async {
/// let metrics = Handle::current().metrics();
/// let buckets = metrics.poll_count_histogram_num_buckets();
/// let buckets = metrics.poll_time_histogram_num_buckets();
///
/// for i in 0..buckets {
/// let range = metrics.poll_count_histogram_bucket_range(i);
/// let range = metrics.poll_time_histogram_bucket_range(i);
/// println!("Histogram bucket {} range: {:?}", i, range);
/// }
/// });
/// }
/// ```
///
/// [`metrics_poll_count_histogram_configuration()`]:
/// crate::runtime::Builder::metrics_poll_count_histogram_configuration
/// [`metrics_poll_time_histogram_configuration()`]:
/// crate::runtime::Builder::metrics_poll_time_histogram_configuration
#[track_caller]
pub fn poll_count_histogram_bucket_range(&self, bucket: usize) -> Range<Duration> {
pub fn poll_time_histogram_bucket_range(&self, bucket: usize) -> Range<Duration> {
self.handle
.inner
.worker_metrics(0)
Expand All @@ -851,6 +866,16 @@ impl RuntimeMetrics {
.unwrap_or_default()
}

/// Deprecated. Use [`poll_time_histogram_bucket_range()`] instead.
///
/// [`poll_time_histogram_bucket_range()`]: Self::poll_time_histogram_bucket_range
#[track_caller]
#[doc(hidden)]
#[deprecated(note = "renamed to `poll_time_histogram_bucket_range`")]
pub fn poll_count_histogram_bucket_range(&self, bucket: usize) -> Range<Duration> {
self.poll_time_histogram_bucket_range(bucket)
}

cfg_64bit_metrics! {
/// Returns the number of times the given worker polled tasks with a poll
/// duration within the given bucket's range.
Expand All @@ -872,7 +897,7 @@ impl RuntimeMetrics {
///
/// `bucket` is the index of the bucket being queried. The bucket is scoped
/// to the worker. The range represented by the bucket can be queried by
/// calling [`poll_count_histogram_bucket_range()`]. Each worker maintains
/// calling [`poll_time_histogram_bucket_range()`]. Each worker maintains
/// identical bucket ranges.
///
/// # Panics
Expand All @@ -888,26 +913,26 @@ impl RuntimeMetrics {
///
/// fn main() {
/// runtime::Builder::new_current_thread()
/// .enable_metrics_poll_count_histogram()
/// .enable_metrics_poll_time_histogram()
/// .build()
/// .unwrap()
/// .block_on(async {
/// let metrics = Handle::current().metrics();
/// let buckets = metrics.poll_count_histogram_num_buckets();
/// let buckets = metrics.poll_time_histogram_num_buckets();
///
/// for worker in 0..metrics.num_workers() {
/// for i in 0..buckets {
/// let count = metrics.poll_count_histogram_bucket_count(worker, i);
/// let count = metrics.poll_time_histogram_bucket_count(worker, i);
/// println!("Poll count {}", count);
/// }
/// }
/// });
/// }
/// ```
///
/// [`poll_count_histogram_bucket_range()`]: crate::runtime::RuntimeMetrics::poll_count_histogram_bucket_range
/// [`poll_time_histogram_bucket_range()`]: crate::runtime::RuntimeMetrics::poll_time_histogram_bucket_range
#[track_caller]
pub fn poll_count_histogram_bucket_count(&self, worker: usize, bucket: usize) -> u64 {
pub fn poll_time_histogram_bucket_count(&self, worker: usize, bucket: usize) -> u64 {
self.handle
.inner
.worker_metrics(worker)
Expand All @@ -917,6 +942,12 @@ impl RuntimeMetrics {
.unwrap_or_default()
}

#[doc(hidden)]
#[deprecated(note = "use `poll_time_histogram_bucket_count` instead")]
pub fn poll_count_histogram_bucket_count(&self, worker: usize, bucket: usize) -> u64 {
self.poll_time_histogram_bucket_count(worker, bucket)
}

/// Returns the mean duration of task polls, in nanoseconds.
///
/// This is an exponentially weighted moving average. Currently, this metric
Expand Down
Loading
Loading