chore(metrics): add configurable sampling interval (#654)

Add the ability to configure the metrics sample interval in ms from the
config or override in the sdk command to create a sandbox.

This is so that users can configure how frequently metric samples are
collected. It could be faster or slower but the default remains 1 second
or 1000 ms. If a user wants to disable sampling completely they set it
to 0 and the entire metric sampling task is skipped.

If they disable metric sampling by setting the interval to 0 and then
they try to read the metrics from cli/sdk, they will receive and error
saying metrics are disabled for that sandbox.

Example config:
```json
{
  "database": {
    "max_connections": 1
  },
  "sandbox_defaults": {
    "metrics_sample_interval_ms": 0
  }
}
```

Author: wellsbunk5

crates/cli/lib/sandbox_cmd.rs

@@ -72,6 +72,14 @@ pub struct SandboxArgs {
     #[arg(long, default_value_t = 512)]
     pub memory_mib: u32,
 
+    /// Metrics sampling interval in milliseconds; `0` disables sampling.
+    #[arg(long = "metrics-sample-interval-ms", default_value_t = 1000)]
+    pub metrics_sample_interval_ms: u64,
+
+    /// Disable metrics sampling; overrides `--metrics-sample-interval-ms`.
+    #[arg(long = "disable-metrics-sample")]
+    pub disable_metrics_sample: bool,
+
     /// Root filesystem path for direct passthrough mounts.
     #[arg(long)]
     pub rootfs_path: Option<PathBuf>,
@@ -190,6 +198,11 @@ pub fn run(args: SandboxArgs, log_level: Option<LogLevel>) -> ! {
         forward_output: args.forward_output,
         idle_timeout_secs: args.idle_timeout,
         max_duration_secs: args.max_duration,
+        metrics_sample_interval_ms: if args.disable_metrics_sample {
+            None
+        } else {
+            std::num::NonZero::new(args.metrics_sample_interval_ms)
+        },
         vm: vm_config,
     };
 

crates/microsandbox/lib/config/mod.rs

@@ -5,6 +5,7 @@
 
 use std::{
     collections::HashMap,
+    num::NonZero,
     path::{Path, PathBuf},
     sync::OnceLock,
 };
@@ -32,6 +33,28 @@ pub(crate) const DEFAULT_MAX_CONNECTIONS: u32 = 5;
 /// Default database connection acquisition timeout in seconds.
 pub(crate) const DEFAULT_CONNECT_TIMEOUT_SECS: u64 = 30;
 
+/// Default sandbox metrics sampling interval in milliseconds.
+pub const DEFAULT_METRICS_SAMPLE_INTERVAL_MS: u64 = 1000;
+
+/// Default value for `metrics_sample_interval_ms` fields.
+pub fn default_metrics_sample_interval() -> Option<NonZero<u64>> {
+    NonZero::new(DEFAULT_METRICS_SAMPLE_INTERVAL_MS)
+}
+
+/// Serde adapter mapping the `metrics_sample_interval_ms` wire format `u64` to `Option<NonZero<u64>>` (`0` ↔ `None`).
+pub(crate) mod metrics_interval_serde {
+    use serde::{Deserialize, Deserializer, Serialize, Serializer};
+    use std::num::NonZero;
+
+    pub fn serialize<S: Serializer>(v: &Option<NonZero<u64>>, s: S) -> Result<S::Ok, S::Error> {
+        v.map(|n| n.get()).unwrap_or(0).serialize(s)
+    }
+
+    pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Option<NonZero<u64>>, D::Error> {
+        Ok(NonZero::new(u64::deserialize(d)?))
+    }
+}
+
 /// Service name for microsandbox-managed registry credentials in the OS keyring.
 #[cfg(all(
     feature = "keyring",
@@ -131,6 +154,17 @@ pub struct SandboxDefaults {
 
     /// Default working directory inside the sandbox.
     pub workdir: Option<String>,
+
+    /// Default metrics sampling interval in milliseconds; `0` disables sampling globally.
+    #[serde(
+        default = "default_metrics_sample_interval",
+        with = "metrics_interval_serde"
+    )]
+    pub metrics_sample_interval_ms: Option<NonZero<u64>>,
+
+    /// Force-disable metrics sampling regardless of `metrics_sample_interval_ms`.
+    #[serde(default)]
+    pub disable_metrics_sample: bool,
 }
 
 /// Registry configuration.
@@ -423,6 +457,8 @@ impl Default for SandboxDefaults {
             memory_mib: DEFAULT_MEMORY_MIB,
             shell: "/bin/sh".into(),
             workdir: None,
+            metrics_sample_interval_ms: default_metrics_sample_interval(),
+            disable_metrics_sample: false,
         }
     }
 }
@@ -895,6 +931,10 @@ mod tests {
         assert_eq!(cfg.sandbox_defaults.cpus, 1);
         assert_eq!(cfg.sandbox_defaults.memory_mib, 512);
         assert_eq!(cfg.sandbox_defaults.shell, "/bin/sh");
+        assert_eq!(
+            cfg.sandbox_defaults.metrics_sample_interval_ms,
+            NonZero::new(DEFAULT_METRICS_SAMPLE_INTERVAL_MS)
+        );
         assert_eq!(cfg.log_level, None);
         assert_eq!(cfg.database.max_connections, 5);
         assert_eq!(cfg.database.connect_timeout_secs, 30);
@@ -915,6 +955,59 @@ mod tests {
         assert_eq!(cfg.sandbox_defaults.memory_mib, 512);
     }
 
+    #[test]
+    fn test_deserialize_metrics_interval_missing_uses_default() {
+        let json = r#"{"sandbox_defaults": {}}"#;
+        let cfg: GlobalConfig = serde_json::from_str(json).unwrap();
+        assert_eq!(
+            cfg.sandbox_defaults.metrics_sample_interval_ms,
+            NonZero::new(DEFAULT_METRICS_SAMPLE_INTERVAL_MS)
+        );
+    }
+
+    #[test]
+    fn test_deserialize_metrics_interval_zero_disables() {
+        let json = r#"{"sandbox_defaults": {"metrics_sample_interval_ms": 0}}"#;
+        let cfg: GlobalConfig = serde_json::from_str(json).unwrap();
+        assert!(cfg.sandbox_defaults.metrics_sample_interval_ms.is_none());
+    }
+
+    #[test]
+    fn test_deserialize_metrics_interval_positive() {
+        let json = r#"{"sandbox_defaults": {"metrics_sample_interval_ms": 2500}}"#;
+        let cfg: GlobalConfig = serde_json::from_str(json).unwrap();
+        assert_eq!(
+            cfg.sandbox_defaults.metrics_sample_interval_ms,
+            NonZero::new(2500)
+        );
+    }
+
+    #[test]
+    fn test_serialize_metrics_interval_disabled_round_trips() {
+        let mut cfg = GlobalConfig::default();
+        cfg.sandbox_defaults.metrics_sample_interval_ms = None;
+        let json = serde_json::to_string(&cfg).unwrap();
+        assert!(
+            json.contains("\"metrics_sample_interval_ms\":0"),
+            "expected `0` serialization, got: {json}"
+        );
+        let round: GlobalConfig = serde_json::from_str(&json).unwrap();
+        assert!(round.sandbox_defaults.metrics_sample_interval_ms.is_none());
+    }
+
+    #[test]
+    fn test_deserialize_disable_metrics_sample_default_false() {
+        let cfg: GlobalConfig = serde_json::from_str("{}").unwrap();
+        assert!(!cfg.sandbox_defaults.disable_metrics_sample);
+    }
+
+    #[test]
+    fn test_deserialize_disable_metrics_sample_true() {
+        let json = r#"{"sandbox_defaults": {"disable_metrics_sample": true}}"#;
+        let cfg: GlobalConfig = serde_json::from_str(json).unwrap();
+        assert!(cfg.sandbox_defaults.disable_metrics_sample);
+    }
+
     #[test]
     fn test_deserialize_log_level() {
         let json = r#"{"log_level":"debug"}"#;

crates/microsandbox/lib/error.rs

@@ -138,6 +138,10 @@ pub enum MicrosandboxError {
     #[error("snapshot integrity check failed: {0}")]
     SnapshotIntegrity(String),
 
+    /// Metrics sampling is disabled for this sandbox.
+    #[error("metrics disabled for sandbox: {0}")]
+    MetricsDisabled(String),
+
     /// A custom error message.
     #[error("{0}")]
     Custom(String),

crates/microsandbox/lib/runtime/spawn.rs

@@ -535,6 +535,13 @@ fn sandbox_cli_args(
     args.push(OsString::from(config.cpus.to_string()));
     args.push(OsString::from("--memory-mib"));
     args.push(OsString::from(config.memory_mib.to_string()));
+    match config.effective_metrics_interval() {
+        Some(ms) => {
+            args.push(OsString::from("--metrics-sample-interval-ms"));
+            args.push(OsString::from(ms.get().to_string()));
+        }
+        None => args.push(OsString::from("--disable-metrics-sample")),
+    }
 
     match &config.image {
         RootfsSource::Bind(path) => {
@@ -931,6 +938,87 @@ mod tests {
         assert_eq!(parsed[1].hard, 1024);
     }
 
+    #[test]
+    fn test_sandbox_cli_args_emit_metrics_interval_flag() {
+        let config = SandboxBuilder::new("test")
+            .image("/tmp/rootfs")
+            .metrics_sample_interval(std::time::Duration::from_millis(1000))
+            .build()
+            .unwrap();
+
+        let rendered = render_args(&config);
+
+        assert!(
+            rendered
+                .windows(2)
+                .any(|pair| pair == ["--metrics-sample-interval-ms", "1000"]),
+            "expected metrics interval flag in {rendered:?}"
+        );
+    }
+
+    #[test]
+    fn test_sandbox_cli_args_include_custom_metrics_sample_interval() {
+        let config = SandboxBuilder::new("test")
+            .image("/tmp/rootfs")
+            .metrics_sample_interval(std::time::Duration::from_millis(2500))
+            .build()
+            .unwrap();
+
+        let rendered = render_args(&config);
+
+        assert!(
+            rendered
+                .windows(2)
+                .any(|pair| pair == ["--metrics-sample-interval-ms", "2500"]),
+            "expected custom metrics interval flag in {rendered:?}"
+        );
+    }
+
+    #[test]
+    fn test_sandbox_cli_args_disabled_metrics_emit_disable_flag() {
+        let config = SandboxBuilder::new("test")
+            .image("/tmp/rootfs")
+            .metrics_sample_interval(std::time::Duration::ZERO)
+            .build()
+            .unwrap();
+
+        let rendered = render_args(&config);
+
+        assert!(
+            rendered.iter().any(|arg| arg == "--disable-metrics-sample"),
+            "expected `--disable-metrics-sample` flag; got {rendered:?}"
+        );
+        assert!(
+            !rendered
+                .iter()
+                .any(|arg| arg == "--metrics-sample-interval-ms"),
+            "should not also emit interval flag; got {rendered:?}"
+        );
+    }
+
+    #[test]
+    fn test_sandbox_cli_args_disable_overrides_positive_interval() {
+        let config = SandboxBuilder::new("test")
+            .image("/tmp/rootfs")
+            .metrics_sample_interval(std::time::Duration::from_millis(2500))
+            .disable_metrics_sample()
+            .build()
+            .unwrap();
+
+        let rendered = render_args(&config);
+
+        assert!(
+            rendered.iter().any(|arg| arg == "--disable-metrics-sample"),
+            "expected disable flag to win over positive interval; got {rendered:?}"
+        );
+        assert!(
+            !rendered
+                .iter()
+                .any(|arg| arg == "--metrics-sample-interval-ms"),
+            "should not emit interval flag when disable is set; got {rendered:?}"
+        );
+    }
+
     #[test]
     fn test_sandbox_cli_args_include_db_connect_timeout() {
         let config = SandboxBuilder::new("test")

crates/microsandbox/lib/sandbox/builder.rs

@@ -18,7 +18,8 @@ use super::{
         ImageBuilder, IntoImage, MountBuilder, Patch, PatchBuilder, RootfsSource, VolumeMount,
     },
 };
-use crate::{LogLevel, MicrosandboxResult, size::Mebibytes};
+use crate::{LogLevel, MicrosandboxError, MicrosandboxResult, size::Mebibytes};
+use std::time::Duration;
 
 //--------------------------------------------------------------------------------------------------
 // Types
@@ -155,6 +156,27 @@ impl SandboxBuilder {
         self
     }
 
+    /// Force-disable metrics sampling regardless of `metrics_sample_interval`.
+    pub fn disable_metrics_sample(mut self) -> Self {
+        self.config.disable_metrics_sample = true;
+        self
+    }
+
+    /// Override the metrics sampling interval; pass `Duration::ZERO` to disable.
+    pub fn metrics_sample_interval(mut self, interval: Duration) -> Self {
+        let ms = interval.as_millis();
+        if ms > u128::from(u64::MAX) {
+            if self.build_error.is_none() {
+                self.build_error = Some(MicrosandboxError::InvalidConfig(format!(
+                    "metrics sample interval {interval:?} overflows u64 milliseconds"
+                )));
+            }
+            return self;
+        }
+        self.config.metrics_sample_interval_ms = std::num::NonZero::new(ms as u64);
+        self
+    }
+
     /// Default working directory for commands executed in this sandbox
     /// (e.g., `/app`). Used by [`exec`](super::Sandbox::exec),
     /// [`shell`](super::Sandbox::shell), and [`attach`](super::Sandbox::attach)
@@ -845,6 +867,49 @@ mod tests {
         assert_eq!(config.log_level, None);
     }
 
+    #[test]
+    fn test_builder_metrics_sample_interval_sets_ms() {
+        let config = SandboxBuilder::new("test")
+            .image("alpine")
+            .metrics_sample_interval(std::time::Duration::from_millis(750))
+            .build()
+            .unwrap();
+
+        assert_eq!(
+            config.metrics_sample_interval_ms,
+            std::num::NonZero::new(750)
+        );
+    }
+
+    #[test]
+    fn test_builder_metrics_sample_interval_zero_is_disabled() {
+        let config = SandboxBuilder::new("test")
+            .image("alpine")
+            .metrics_sample_interval(std::time::Duration::ZERO)
+            .build()
+            .unwrap();
+
+        assert!(config.metrics_sample_interval_ms.is_none());
+        assert!(config.effective_metrics_interval().is_none());
+    }
+
+    #[test]
+    fn test_builder_disable_metrics_sample_overrides_interval() {
+        let config = SandboxBuilder::new("test")
+            .image("alpine")
+            .metrics_sample_interval(std::time::Duration::from_millis(5000))
+            .disable_metrics_sample()
+            .build()
+            .unwrap();
+
+        assert!(config.disable_metrics_sample);
+        assert_eq!(
+            config.metrics_sample_interval_ms,
+            std::num::NonZero::new(5000)
+        );
+        assert!(config.effective_metrics_interval().is_none());
+    }
+
     #[test]
     fn test_builder_replace_sets_replace_existing() {
         let config = SandboxBuilder::new("test")