metrics.rs integration (#68)

Co-authored-by: Ariel Ben-Yehuda <[email protected]>

Author: arielb1

Cargo.toml

@@ -19,13 +19,15 @@ unexpected_cfgs = { level = "warn", check-cfg = ['cfg(tokio_unstable)'] }
 
 [features]
 default = ["rt"]
+metrics-rs-integration = ["dep:metrics"]
 rt = ["tokio"]
 
 [dependencies]
 tokio-stream = "0.1.11"
 futures-util = "0.3.19"
 pin-project-lite = "0.2.7"
 tokio = { version = "1.41.0", features = ["rt", "time", "net"], optional = true }
+metrics = { version = "0.24", optional = true }
 
 [dev-dependencies]
 axum = "0.6"
@@ -35,6 +37,9 @@ num_cpus = "1.13.1"
 serde = { version = "1.0.136", features = ["derive"] }
 serde_json = "1.0.79"
 tokio = { version = "1.41.0", features = ["full", "rt", "time", "macros", "test-util"] }
+metrics-util = { version = "0.19", features = ["debugging"] }
+metrics = { version = "0.24" }
+metrics-exporter-prometheus = { version = "0.16", features = ["uds-listener"] }
 
 [[example]]
 name = "runtime"

src/lib.rs

@@ -102,7 +102,54 @@ async fn do_work() {
         tokio::time::sleep(Duration::from_millis(100)).await;
     }
 }
-```"##
+```
+
+### Monitoring and publishing runtime metrics (unstable)
+
+If the `metrics-rs-integration` feature is additionally enabled, this crate allows
+publishing runtime metrics externally via [metrics-rs](metrics) exporters.
+
+For example, you can use [metrics_exporter_prometheus] to make metrics visible
+to Prometheus. You can see the [metrics_exporter_prometheus] and [metrics-rs](metrics)
+docs for guidance on configuring exporters.
+
+The published metrics are the same as the fields of [RuntimeMetrics], but with
+a "tokio_" prefix added, for example `tokio_workers_count`.
+
+[metrics_exporter_prometheus]: https://docs.rs/metrics_exporter_prometheus
+[RuntimeMetrics]: crate::RuntimeMetrics
+
+This example exports Prometheus metrics by listening on a local Unix socket
+called `prometheus.sock`, which you can access for debugging by
+`curl --unix-socket prometheus.sock localhost`.
+
+```
+use std::time::Duration;
+
+#[tokio::main]
+async fn main() {
+    metrics_exporter_prometheus::PrometheusBuilder::new()
+        .with_http_uds_listener("prometheus.sock")
+        .install()
+        .unwrap();
+    tokio::task::spawn(
+        tokio_metrics::RuntimeMetricsReporterBuilder::default()
+            // the default metric sampling interval is 30 seconds, which is
+            // too long for quick tests, so have it be 1 second.
+            .with_interval(std::time::Duration::from_secs(1))
+            .describe_and_run(),
+    );
+    // Run some code
+    tokio::task::spawn(async move {
+        for _ in 0..1000 {
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .unwrap();
+}
+```
+"##
 )]
 
 macro_rules! cfg_rt {
@@ -122,6 +169,8 @@ cfg_rt! {
         RuntimeMetrics,
         RuntimeMonitor,
     };
+    #[cfg(feature = "metrics-rs-integration")]
+    pub use runtime::metrics_rs_integration::{RuntimeMetricsReporterBuilder, RuntimeMetricsReporter};
 }
 
 mod task;

src/runtime.rs

@@ -1,6 +1,9 @@
 use std::time::{Duration, Instant};
 use tokio::runtime;
 
+#[cfg(feature = "metrics-rs-integration")]
+pub(crate) mod metrics_rs_integration;
+
 #[cfg(any(docsrs, all(tokio_unstable, feature = "rt")))]
 #[cfg_attr(docsrs, doc(cfg(all(tokio_unstable, feature = "rt"))))]
 /// Monitors key metrics of the tokio runtime.