feat: Make the collector module public (#63)

* feat: Make the collector module public

This allows collecting the metrics without sending them to a
process-wide registered metrics-rs collector.  Useful for integration
into other metrics clients.

Author: flub

Cargo.toml

@@ -20,6 +20,9 @@ keywords = [
 all-features = true
 
 [features]
+default = ["metrics-rs"]
+# Enable the metrics-rs collector integration.
+metrics-rs = ["dep:metrics"]
 # Enable a `dummy` collector that always return an empty `Metrics` for non supported platforms
 dummy = []
 # Use a Gauge on `process_cpu_seconds_total` metrics instead of Counter to represent f64 value.
@@ -30,7 +33,7 @@ use-gauge-on-cpu-seconds-total = []
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-metrics = "0.24.0"
+metrics = { version = "0.24.0", optional = true }
 
 [target.'cfg(target_os = "macos")'.dependencies]
 libproc = "0.14.2"

README.md

@@ -131,10 +131,11 @@ async fn main() {
 
 This crate offers the following features:
 
-| Feature Name                     | Description                                                                                                                                         |
-| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `dummy`                          | Enables a dummy collector that returns an empty `Metrics` on non-supported platforms.                                                               |
-| `use-gauge-on-cpu-seconds-total` | Use a Gauge on `process_cpu_seconds_total` metrics instead of Counter to represent `f64` value. This is a previous behavior prior to version 2.0.0. |
+| Feature Name                      | Description                                                                                                                                         |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dummy`                           | Enables a dummy collector that returns an empty `Metrics` on non-supported platforms.                                                               |
+| `use-gauge-on-cpu-seconds-total`  | Use a Gauge on `process_cpu_seconds_total` metrics instead of Counter to represent `f64` value. This is a previous behavior prior to version 2.0.0. |
+| `metrics-rs` (enabled by default) | Enables the [metrics] integration. Can be removed to reduce dependencies if unused.
 
 # License
 

src/collector.rs

@@ -1,11 +1,24 @@
-#[cfg_attr(target_os = "macos", path = "collector/macos.rs")]
-#[cfg_attr(target_os = "linux", path = "collector/linux.rs")]
-#[cfg_attr(target_os = "windows", path = "collector/windows.rs")]
-#[cfg_attr(target_os = "freebsd", path = "collector/freebsd.rs")]
-#[cfg_attr(target_os = "openbsd", path = "collector/openbsd.rs")]
+//! Raw metrics for the running process.
+//!
+//! This module contains the implementation to collect the Prometheus metrics for the
+//! running process.  This can be useful to export these metrics via custom mechanisms
+//! rather than via the [metrics] crate.
+//!
+//! Use the [`collect`] function to create a snapshot of the current metrics.
+//!
+//! To export these metrics via the [metrics] crate however it is recommended to use the
+//! [`Collector`] struct.
+//!
+//! [`Collector`]: crate::Collector
+
+#[cfg_attr(target_os = "macos", path = "implementation/macos.rs")]
+#[cfg_attr(target_os = "linux", path = "implementation/linux.rs")]
+#[cfg_attr(target_os = "windows", path = "implementation/windows.rs")]
+#[cfg_attr(target_os = "freebsd", path = "implementation/freebsd.rs")]
+#[cfg_attr(target_os = "openbsd", path = "implementation/openbsd.rs")]
 #[allow(unused_attributes)]
-#[cfg_attr(feature = "dummy", path = "collector/dummy.rs")]
-mod collector;
+#[cfg_attr(feature = "dummy", path = "implementation/dummy.rs")]
+mod implementation;
 
 #[cfg(all(
     not(feature = "dummy"),
@@ -21,22 +34,32 @@ compile_error!(
     "A feature \"dummy\" must be enabled to compile this crate on non supported platforms."
 );
 
-pub use collector::collect;
+/// Creates a snapshot of the running process' [`Metrics`].
+///
+/// Creates a new instance of [`Metrics`] with the current values of the running process.
+pub use implementation::collect;
 
-/// Process metrics
-/// https://prometheus.io/docs/instrumenting/writing_clientlibs/#process-metrics
+/// Standard Prometheus process metrics.
+///
+/// This struct describes the standard set of Prometheus process metrics as described at
+/// <https://prometheus.io/docs/instrumenting/writing_clientlibs/#process-metrics>.
+///
+/// To create a populated struct for the running process use the [`collect`] function.  The
+/// `Default` impl does not populate any metrics.
 #[derive(Debug, Default, PartialEq)]
 pub struct Metrics {
     /// Total user and system CPU time spent in seconds.
     pub cpu_seconds_total: Option<f64>,
     /// Number of open file descriptors.
     pub open_fds: Option<u64>,
     /// Maximum number of open file descriptors.
+    ///
     /// 0 indicates 'unlimited'.
     pub max_fds: Option<u64>,
     /// Virtual memory size in bytes.
     pub virtual_memory_bytes: Option<u64>,
     /// Maximum amount of virtual memory available in bytes.
+    ///
     /// 0 indicates 'unlimited'.
     pub virtual_memory_max_bytes: Option<u64>,
     /// Resident memory size in bytes.

src/collector/dummy.rs renamed to src/implementation/dummy.rs

@@ -1,14 +1,20 @@
 #![doc = include_str!("../README.md")]
-mod collector;
+pub mod collector;
 
+#[cfg(feature = "metrics-rs")]
 use std::sync::Arc;
 
+#[cfg(feature = "metrics-rs")]
 use metrics::{describe_gauge, gauge, Unit};
 
-#[cfg(not(feature = "use-gauge-on-cpu-seconds-total"))]
+#[cfg(all(
+    feature = "metrics-rs",
+    not(feature = "use-gauge-on-cpu-seconds-total")
+))]
 use metrics::{counter, describe_counter};
 
 /// Metrics names
+#[cfg(feature = "metrics-rs")]
 #[derive(Debug, PartialEq, Eq)]
 struct Metrics {
     cpu_seconds_total: Arc<str>,
@@ -21,6 +27,7 @@ struct Metrics {
     threads: Arc<str>,
 }
 
+#[cfg(feature = "metrics-rs")]
 impl Metrics {
     // Create new Metrics, allocating prefixed strings for metrics names.
     fn new(prefix: impl AsRef<str>) -> Self {
@@ -38,19 +45,25 @@ impl Metrics {
     }
 }
 
+#[cfg(feature = "metrics-rs")]
 impl Default for Metrics {
     // Create new Metrics, without prefixing and thus allocating.
     fn default() -> Self {
         Self::new("")
     }
 }
 
-/// Prometheus style process metrics collector
+/// Prometheus style process metrics collector for the [metrics] crate.
+///
+/// This is a collector which will directly export the metrics to the registered [metrics]
+/// collector.
+#[cfg(feature = "metrics-rs")]
 #[derive(Debug, Default, PartialEq, Eq, Clone)]
 pub struct Collector {
     metrics: Arc<Metrics>,
 }
 
+#[cfg(feature = "metrics-rs")]
 impl Collector {
     /// Add an prefix that is prepended to metric keys.
     /// # Examples