feat: add HTTP server mode with JSON and Prometheus endpoints (#34, #53)

Author: vladkens

readme.md

@@ -64,6 +64,7 @@ Usage: macmon [OPTIONS] [COMMAND]
 
 Commands:
   pipe   Output metrics in JSON format
+  serve  Serve metrics over HTTP
   debug  Print debug information
   help   Print this message or the help of the given subcommand(s)
 
@@ -124,6 +125,59 @@ This will collect 10 samples with an update interval of 500 milliseconds.
 }
 ```
 
+## 🌐 HTTP Server
+
+You can use the `serve` subcommand to expose metrics over HTTP. This is useful for integrating with monitoring systems like [Prometheus](https://prometheus.io/) and [Grafana](https://grafana.com/).
+
+```sh
+macmon serve            # default port 9090, interval 1000ms
+macmon serve -p 8080    # custom port
+macmon serve -i 500     # sampling interval 500ms
+macmon serve &          # run in background
+```
+
+Two endpoints are available:
+
+| Endpoint | Format | Description |
+|---|---|---|
+| `GET /json` | JSON | Current metrics snapshot (same format as `pipe --soc-info`) |
+| `GET /metrics` | Prometheus | Metrics in [Prometheus text format](https://prometheus.io/docs/instrumenting/exposition_formats/) |
+
+### Prometheus / Grafana setup
+
+Add a scrape target to your `prometheus.yml`:
+
+```yaml
+scrape_configs:
+  - job_name: macmon
+    static_configs:
+      - targets: ["localhost:9090"]
+```
+
+Then import or build a Grafana dashboard querying metrics such as:
+
+```
+macmon_cpu_power_watts{chip="Apple M3 Pro"}
+macmon_ecpu_usage_ratio{chip="Apple M3 Pro"}
+macmon_memory_ram_used_bytes{chip="Apple M3 Pro"}
+```
+
+### Prometheus output example
+
+```
+# HELP macmon_cpu_temp_celsius Average CPU temperature in Celsius
+# TYPE macmon_cpu_temp_celsius gauge
+macmon_cpu_temp_celsius{chip="Apple M3 Pro"} 47.3
+
+# HELP macmon_cpu_power_watts CPU power consumption in Watts
+# TYPE macmon_cpu_power_watts gauge
+macmon_cpu_power_watts{chip="Apple M3 Pro"} 8.42
+
+# HELP macmon_ecpu_usage_ratio Efficiency CPU cluster utilization (0–1)
+# TYPE macmon_ecpu_usage_ratio gauge
+macmon_ecpu_usage_ratio{chip="Apple M3 Pro"} 0.083
+```
+
 ## 📦 Build from Source
 
 1. Install [Rust toolchain](https://www.rust-lang.org/tools/install)

src/main.rs

@@ -1,6 +1,10 @@
 use clap::{CommandFactory, Parser, Subcommand, parser::ValueSource};
 use macmon::{App, Sampler, debug};
 use std::error::Error;
+use std::sync::{Arc, Mutex};
+use std::thread;
+
+mod serve;
 
 #[derive(Debug, Subcommand)]
 enum Commands {
@@ -16,6 +20,13 @@ enum Commands {
     soc_info: bool,
   },
 
+  /// Serve metrics over HTTP (JSON at / and Prometheus at /metrics)
+  Serve {
+    /// Port to listen on
+    #[arg(short, long, default_value_t = 9090)]
+    port: u16,
+  },
+
   /// Print debug information
   Debug,
 }
@@ -61,6 +72,27 @@ fn main() -> Result<(), Box<dyn Error>> {
         }
       }
     }
+    Some(Commands::Serve { port }) => {
+      let mut sampler = Sampler::new()?;
+      let soc = Arc::new(sampler.get_soc_info().clone());
+      let shared: serve::SharedMetrics = Arc::new(Mutex::new(None));
+
+      let shared_http = Arc::clone(&shared);
+      let soc_http = Arc::clone(&soc);
+      let port = *port;
+      thread::spawn(move || {
+        if let Err(e) = serve::run(port, shared_http, soc_http) {
+          eprintln!("server error: {e}");
+        }
+      });
+
+      loop {
+        match sampler.get_metrics(args.interval.max(100)) {
+          Ok(m) => *shared.lock().unwrap() = Some(m),
+          Err(e) => eprintln!("sampling error: {e}"),
+        }
+      }
+    }
     Some(Commands::Debug) => debug::print_debug()?,
     _ => {
       let mut app = App::new()?;

src/serve.rs

@@ -0,0 +1,128 @@
+use std::io::{Read, Write};
+use std::net::{TcpListener, TcpStream};
+use std::sync::{Arc, Mutex};
+use std::thread;
+
+use macmon::{Metrics, SocInfo};
+
+pub type SharedMetrics = Arc<Mutex<Option<Metrics>>>;
+
+#[rustfmt::skip]
+fn to_prometheus(m: &Metrics, soc: &SocInfo) -> String {
+  let chip = &soc.chip_name;
+  let l = format!(r#"chip="{chip}""#);
+
+  macro_rules! gauge {
+    ($out:expr, $name:literal, $help:literal, $value:expr) => {
+      $out.push_str(&format!(
+        "# HELP {} {}\n# TYPE {} gauge\n{}{{{l}}} {}\n\n",
+        $name, $help, $name, $name, $value
+      ));
+    };
+  }
+
+  let mut out = String::new();
+  gauge!(out, "macmon_cpu_temp_celsius", "Average CPU temperature in Celsius", m.temp.cpu_temp_avg);
+  gauge!(out, "macmon_gpu_temp_celsius", "Average GPU temperature in Celsius", m.temp.gpu_temp_avg);
+  gauge!(out, "macmon_memory_ram_total_bytes", "Total RAM in bytes", m.memory.ram_total);
+  gauge!(out, "macmon_memory_ram_used_bytes", "Used RAM in bytes", m.memory.ram_usage);
+  gauge!(out, "macmon_memory_swap_total_bytes", "Total swap in bytes", m.memory.swap_total);
+  gauge!(out, "macmon_memory_swap_used_bytes", "Used swap in bytes", m.memory.swap_usage);
+  gauge!(out, "macmon_ecpu_freq_mhz", "Efficiency CPU cluster frequency in MHz", m.ecpu_usage.0);
+  gauge!(out, "macmon_ecpu_usage_ratio", "Efficiency CPU cluster utilization (0–1)", m.ecpu_usage.1);
+  gauge!(out, "macmon_pcpu_freq_mhz", "Performance CPU cluster frequency in MHz", m.pcpu_usage.0);
+  gauge!(out, "macmon_pcpu_usage_ratio", "Performance CPU cluster utilization (0–1)", m.pcpu_usage.1);
+  gauge!(out, "macmon_gpu_freq_mhz", "GPU frequency in MHz", m.gpu_usage.0);
+  gauge!(out, "macmon_gpu_usage_ratio", "GPU utilization (0–1)", m.gpu_usage.1);
+  gauge!(out, "macmon_cpu_power_watts", "CPU power consumption in Watts", m.cpu_power);
+  gauge!(out, "macmon_gpu_power_watts", "GPU power consumption in Watts", m.gpu_power);
+  gauge!(out, "macmon_ane_power_watts", "Apple Neural Engine power consumption in Watts", m.ane_power);
+  gauge!(out, "macmon_all_power_watts", "Combined CPU+GPU+ANE power consumption in Watts", m.all_power);
+  gauge!(out, "macmon_sys_power_watts", "Total system power consumption in Watts", m.sys_power);
+  gauge!(out, "macmon_ram_power_watts", "RAM power consumption in Watts", m.ram_power);
+  gauge!(out, "macmon_gpu_ram_power_watts", "GPU RAM power consumption in Watts", m.gpu_ram_power);
+  out
+}
+
+fn to_json(m: &Metrics, soc: &SocInfo) -> String {
+  let mut doc = serde_json::to_value(m).unwrap_or_default();
+  doc["soc"] = serde_json::to_value(soc).unwrap_or_default();
+  doc["timestamp"] = serde_json::to_value(chrono::Utc::now().to_rfc3339()).unwrap_or_default();
+  serde_json::to_string(&doc).unwrap_or_default()
+}
+
+fn read_path(stream: &mut TcpStream) -> Option<String> {
+  let mut buf = [0u8; 2048];
+  let n = stream.read(&mut buf).ok()?;
+  let text = std::str::from_utf8(&buf[..n]).ok()?;
+  let path = text.lines().next()?.split_whitespace().nth(1)?;
+  Some(path.split('?').next().unwrap_or(path).to_string())
+}
+
+fn write_response(stream: &mut TcpStream, status: u16, content_type: &str, body: String) {
+  let status_text = match status {
+    200 => "OK",
+    404 => "Not Found",
+    503 => "Service Unavailable",
+    _ => "OK",
+  };
+  let _ = stream.write_all(
+    format!(
+      "HTTP/1.1 {status} {status_text}\r\nContent-Type: {content_type}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+      body.len()
+    )
+    .as_bytes(),
+  );
+}
+
+fn handle_conn(mut stream: TcpStream, shared: SharedMetrics, soc: Arc<SocInfo>) {
+  let path = match read_path(&mut stream) {
+    Some(p) => p,
+    None => return,
+  };
+
+  let lock = shared.lock().unwrap();
+
+  let Some(m) = lock.as_ref() else {
+    drop(lock);
+    write_response(&mut stream, 503, "application/json", r#"{"error":"no data yet"}"#.to_string());
+    return;
+  };
+
+  match path.as_str() {
+    "/json" => {
+      let body = to_json(m, &soc);
+      drop(lock);
+      write_response(&mut stream, 200, "application/json", body);
+    }
+    "/metrics" => {
+      let body = to_prometheus(m, &soc);
+      drop(lock);
+      write_response(&mut stream, 200, "text/plain; version=0.0.4; charset=utf-8", body);
+    }
+    _ => {
+      drop(lock);
+      write_response(&mut stream, 404, "application/json", r#"{"error":"not found"}"#.to_string());
+    }
+  }
+}
+
+pub fn run(
+  port: u16,
+  shared: SharedMetrics,
+  soc: Arc<SocInfo>,
+) -> Result<(), Box<dyn std::error::Error>> {
+  let listener = TcpListener::bind(format!("0.0.0.0:{port}"))?;
+  eprintln!("macmon serving on http://localhost:{port}");
+  eprintln!("  GET /json    → JSON metrics");
+  eprintln!("  GET /metrics → Prometheus format");
+
+  for stream in listener.incoming() {
+    let Ok(stream) = stream else { continue };
+    let shared = Arc::clone(&shared);
+    let soc = Arc::clone(&soc);
+    thread::spawn(move || handle_conn(stream, shared, soc));
+  }
+
+  Ok(())
+}