3
3
use crate :: runtime:: handle:: Handle ;
4
4
use crate :: runtime:: { blocking, driver, Callback , HistogramBuilder , Runtime , TaskCallback } ;
5
5
#[ cfg( tokio_unstable) ]
6
- use crate :: runtime:: { LocalOptions , LocalRuntime , TaskMeta } ;
6
+ use crate :: runtime:: { metrics :: HistogramConfiguration , LocalOptions , LocalRuntime , TaskMeta } ;
7
7
use crate :: util:: rand:: { RngSeed , RngSeedGenerator } ;
8
8
9
9
use crate :: runtime:: blocking:: BlockingPool ;
@@ -1102,6 +1102,11 @@ impl Builder {
1102
1102
/// `metrics_poll_count_histogram_` builder methods to configure the
1103
1103
/// histogram details.
1104
1104
///
1105
+ /// By default, a linear histogram with 10 buckets each 100 microseconds wide will be used.
1106
+ /// This has an extremely low memory footprint, but may not provide enough granularity. For
1107
+ /// better granularity with low memory usage, use [`metrics_poll_count_histogram_configuration()`]
1108
+ /// to select [`LogHistogram`] instead.
1109
+ ///
1105
1110
/// # Examples
1106
1111
///
1107
1112
/// ```
@@ -1121,6 +1126,8 @@ impl Builder {
1121
1126
///
1122
1127
/// [`Handle::metrics()`]: crate::runtime::Handle::metrics
1123
1128
/// [`Instant::now()`]: std::time::Instant::now
1129
+ /// [`LogHistogram`]: crate::runtime::LogHistogram
1130
+ /// [`metrics_poll_count_histogram_configuration()`]: Builder::metrics_poll_count_histogram_configuration
1124
1131
pub fn enable_metrics_poll_count_histogram( & mut self ) -> & mut Self {
1125
1132
self . metrics_poll_count_histogram_enable = true ;
1126
1133
self
@@ -1142,14 +1149,83 @@ impl Builder {
1142
1149
/// ```
1143
1150
/// use tokio::runtime::{self, HistogramScale};
1144
1151
///
1152
+ /// # #[allow(deprecated)]
1145
1153
/// let rt = runtime::Builder::new_multi_thread()
1146
1154
/// .enable_metrics_poll_count_histogram()
1147
1155
/// .metrics_poll_count_histogram_scale(HistogramScale::Log)
1148
1156
/// .build()
1149
1157
/// .unwrap();
1150
1158
/// ```
1159
+ #[ deprecated( note = "use metrics_poll_count_histogram_configuration" ) ]
1151
1160
pub fn metrics_poll_count_histogram_scale( & mut self , histogram_scale: crate :: runtime:: HistogramScale ) -> & mut Self {
1152
- self . metrics_poll_count_histogram. scale = histogram_scale;
1161
+ self . metrics_poll_count_histogram. legacy_mut( |b|b. scale = histogram_scale) ;
1162
+ self
1163
+ }
1164
+
1165
+ /// Configure the histogram for tracking poll times
1166
+ ///
1167
+ /// By default, a linear histogram with 10 buckets each 100 microseconds wide will be used.
1168
+ /// This has an extremely low memory footprint, but may not provide enough granularity. For
1169
+ /// better granularity with low memory usage, use [`LogHistogram`] instead.
1170
+ ///
1171
+ /// # Examples
1172
+ /// Configure a [`LogHistogram`] with [default configuration]:
1173
+ /// ```
1174
+ /// use tokio::runtime;
1175
+ /// use tokio::runtime::{HistogramConfiguration, LogHistogram};
1176
+ ///
1177
+ /// let rt = runtime::Builder::new_multi_thread()
1178
+ /// .enable_metrics_poll_count_histogram()
1179
+ /// .metrics_poll_count_histogram_configuration(
1180
+ /// HistogramConfiguration::log(LogHistogram::default())
1181
+ /// )
1182
+ /// .build()
1183
+ /// .unwrap();
1184
+ /// ```
1185
+ ///
1186
+ /// Configure a linear histogram with 100 buckets, each 10μs wide
1187
+ /// ```
1188
+ /// use tokio::runtime;
1189
+ /// use std::time::Duration;
1190
+ /// use tokio::runtime::HistogramConfiguration;
1191
+ ///
1192
+ /// let rt = runtime::Builder::new_multi_thread()
1193
+ /// .enable_metrics_poll_count_histogram()
1194
+ /// .metrics_poll_count_histogram_configuration(
1195
+ /// HistogramConfiguration::linear(Duration::from_micros(10), 100)
1196
+ /// )
1197
+ /// .build()
1198
+ /// .unwrap();
1199
+ /// ```
1200
+ ///
1201
+ /// Configure a [`LogHistogram`] with the following settings:
1202
+ /// - Measure times from 100ns to 120s
1203
+ /// - Max error of 0.1
1204
+ /// - No more than 1024 buckets
1205
+ /// ```
1206
+ /// use std::time::Duration;
1207
+ /// use tokio::runtime;
1208
+ /// use tokio::runtime::{HistogramConfiguration, LogHistogram};
1209
+ ///
1210
+ /// let rt = runtime::Builder::new_multi_thread()
1211
+ /// .enable_metrics_poll_count_histogram()
1212
+ /// .metrics_poll_count_histogram_configuration(
1213
+ /// HistogramConfiguration::log(LogHistogram::builder()
1214
+ /// .max_value(Duration::from_secs(120))
1215
+ /// .min_value(Duration::from_nanos(100))
1216
+ /// .max_error(0.1)
1217
+ /// .max_buckets(1024)
1218
+ /// .expect("configuration uses 488 buckets")
1219
+ /// )
1220
+ /// )
1221
+ /// .build()
1222
+ /// .unwrap();
1223
+ /// ```
1224
+ ///
1225
+ /// [`LogHistogram`]: crate::runtime::LogHistogram
1226
+ /// [default configuration]: crate::runtime::LogHistogramBuilder
1227
+ pub fn metrics_poll_count_histogram_configuration( & mut self , configuration: HistogramConfiguration ) -> & mut Self {
1228
+ self . metrics_poll_count_histogram. histogram_type = configuration. inner;
1153
1229
self
1154
1230
}
1155
1231
@@ -1173,19 +1249,22 @@ impl Builder {
1173
1249
/// use tokio::runtime;
1174
1250
/// use std::time::Duration;
1175
1251
///
1252
+ /// # #[allow(deprecated)]
1176
1253
/// let rt = runtime::Builder::new_multi_thread()
1177
1254
/// .enable_metrics_poll_count_histogram()
1178
1255
/// .metrics_poll_count_histogram_resolution(Duration::from_micros(100))
1179
1256
/// .build()
1180
1257
/// .unwrap();
1181
1258
/// ```
1259
+ #[ deprecated( note = "use metrics_poll_count_histogram_configuration" ) ]
1182
1260
pub fn metrics_poll_count_histogram_resolution( & mut self , resolution: Duration ) -> & mut Self {
1183
1261
assert!( resolution > Duration :: from_secs( 0 ) ) ;
1184
1262
// Sanity check the argument and also make the cast below safe.
1185
1263
assert!( resolution <= Duration :: from_secs( 1 ) ) ;
1186
1264
1187
1265
let resolution = resolution. as_nanos( ) as u64 ;
1188
- self . metrics_poll_count_histogram. resolution = resolution;
1266
+
1267
+ self . metrics_poll_count_histogram. legacy_mut( |b|b. resolution = resolution) ;
1189
1268
self
1190
1269
}
1191
1270
@@ -1204,14 +1283,16 @@ impl Builder {
1204
1283
/// ```
1205
1284
/// use tokio::runtime;
1206
1285
///
1286
+ /// # #[allow(deprecated)]
1207
1287
/// let rt = runtime::Builder::new_multi_thread()
1208
1288
/// .enable_metrics_poll_count_histogram()
1209
1289
/// .metrics_poll_count_histogram_buckets(15)
1210
1290
/// .build()
1211
1291
/// .unwrap();
1212
1292
/// ```
1293
+ #[ deprecated( note = "use `metrics_poll_count_histogram_configuration" ) ]
1213
1294
pub fn metrics_poll_count_histogram_buckets( & mut self , buckets: usize ) -> & mut Self {
1214
- self . metrics_poll_count_histogram. num_buckets = buckets;
1295
+ self . metrics_poll_count_histogram. legacy_mut ( |b|b . num_buckets = buckets) ;
1215
1296
self
1216
1297
}
1217
1298
}
0 commit comments