add cpuexporter example

Author: endersonmaia

README.md

@@ -545,6 +545,26 @@ sudo lunatik unload
 examples/dnsdoctor/cleanup.sh
 ```
 
+### cpuexporter
+
+[cpuexporter](examples/cpuexporter.lua) will gather CPU usage statistics and expose using [OpenMetrics text format](https://github.com/prometheus/OpenMetrics/blob/main/specification/OpenMetrics.md#text-format) at a UNIX socket file.
+
+#### Usage
+
+```shell
+sudo make examples_install         	# installs examples
+sudo lunatik spawn examples/cpuexporter # runs cpuexporter
+sudo socat - UNIX-CONNECT:/tmp/cpuexporter.sock <<<""
+# TYPE cpu_usage_system gauge
+cpu_usage_system{cpu="cpu1"} 0.0000000000000000 1764094519529162
+cpu_usage_system{cpu="cpu0"} 0.0000000000000000 1764094519529162
+# TYPE cpu_usage_idle gauge
+cpu_usage_idle{cpu="cpu1"} 100.0000000000000000 1764094519529162
+cpu_usage_idle{cpu="cpu0"} 100.0000000000000000 1764094519529162
+...
+```
+
+
 ## References
 
 * [Scripting the Linux Routing Table with Lua](https://netdevconf.info/0x17/sessions/talk/scripting-the-linux-routing-table-with-lua.html)

examples/cpuexporter.lua

@@ -0,0 +1,150 @@
+--
+-- SPDX-FileCopyrightText: (c) 2025 Enderson Maia <[email protected]>
+-- SPDX-License-Identifier: MIT OR GPL-2.0-only
+--
+
+local lunatik = require("lunatik")
+local thread  = require("thread")
+local socket  = require("socket")
+local unix    = require("socket.unix")
+local linux   = require("linux")
+local cpu     = require("cpu")
+
+local shouldstop = thread.shouldstop
+local sock = socket.sock
+
+local server = unix.bind("/tmp/cpuexporter.sock", "STREAM")
+server:listen()
+
+-- Scale integer to decimal with high precision (16 decimal places)
+-- Converts a ratio (value/total) to percentage format with high precision
+local function to_percent_float(value, total)
+	if total == 0 then
+		return "0.0"
+	end
+
+	-- Calculate percentage: (value / total) * 100
+	-- Scale by 10^16 for 16 decimal places precision
+	local scaled1 = (value * 1000000000) // total  		-- First scale by 10^9
+	local int_part = scaled1 // 10000000           		-- Get integer part (divide by 10^7)
+	local frac_part = scaled1 % 10000000           		-- Get first 7 decimal digits
+	local scaled2 = (frac_part * 1000000000) // total  	-- Scale remaining fraction by 10^9
+
+	return string.format("%d.%07d%09d", int_part, frac_part, scaled2)
+end
+
+-- Helper function to sum all values in a table
+local function _sum_table(tbl)
+	local sum = 0
+	for _, value in pairs(tbl) do
+		sum = sum + value
+	end
+	return sum
+end
+
+-- returns cpu_usage based on two samples within a 100ms interval
+local function cpu_usage()
+	local usage = {}
+
+--TODO: add cpu-total with accumulated values for all cpus
+	cpu.foreach_online(function(cpu_id)
+--FIXME: not sure if always calling cpu.stats twice is good
+--       or calling twice for the first time and keep state
+--       for the last call and make delta based on that
+		local t1 = cpu.stats(cpu_id)
+		local t1_total = _sum_table(t1)
+		linux.schedule(100)
+		local t2 = cpu.stats(cpu_id)
+		local t2_total = _sum_table(t2)
+		local total_delta = t2_total - t1_total
+
+		usage[cpu_id] = {}
+		for key, t2_value in pairs(t2) do
+			local delta = t2_value - (t1[key] or 0)
+			if key == "user" then
+				delta = delta - (t2["guest"] - (t1["guest"] or 0))
+			elseif key == "nice" then
+				delta = delta - (t2["guest_nice"] - (t1["guest_nice"] or 0))
+			end
+			usage[cpu_id][key] = to_percent_float(delta, total_delta)
+		end
+	end)
+
+	return usage
+end
+
+local function cpu_metrics()
+	local metrics = ""
+	local ts_ms = linux.time() // 1000  -- Convert to milliseconds (FIXME: note sure if this conversion is necessary)
+	local usage_data = cpu_usage()  -- Call once and store the result
+
+	-- Collect all unique metric names
+	local cpu_metric_names = {}
+	for key, _ in pairs(usage_data[1]) do
+		cpu_metric_names[key] = true
+	end
+
+	-- Output grouped by metric name
+	for metric, _ in pairs(cpu_metric_names) do
+		metrics = metrics .. string.format('# TYPE cpu_usage_%s gauge\n', metric)
+		for cpu_id, cpu_metrics in pairs(usage_data) do
+			local value = cpu_metrics[metric] or "0"
+			metrics = metrics .. string.format('cpu_usage_%s{cpu="cpu%d"} %s %d\n',
+				metric, cpu_id, value, ts_ms)
+		end
+	end
+
+	return metrics
+end
+
+local function handle_client(session)
+	-- Read the request
+	local request, err = session:receive(1024)
+	if not request then
+		error(err)
+	end
+
+	-- Check if this is an HTTP request
+	local method, path, http_version = string.match(request, "^(%w+)%s+([^%s]+)%s+(HTTP/%d%.%d)")
+
+	if http_version then
+		-- This is an HTTP request, validate it
+		if method ~= "GET" then
+			session:send("HTTP/1.1 405 Method Not Allowed\r\n\r\n")
+			error("Method not allowed: " .. tostring(method))
+		end
+
+		if path ~= "/metrics" then
+			session:send("HTTP/1.1 404 Not Found\r\n\r\n")
+			error("Path not found: " .. tostring(path))
+		end
+
+		-- Send HTTP response headers
+		session:send("HTTP/1.1 200 OK\r\n")
+		session:send("Content-Type: text/plain; version=0.0.4\r\n")
+		session:send("\r\n")
+	end
+
+	-- Send metrics (works for both HTTP and plain connections like socat)
+	session:send(cpu_metrics())
+end
+
+local function daemon()
+	print("cpud [daemon]: started")
+	while (not shouldstop()) do
+		local ok, session = pcall(server.accept, server, sock.NONBLOCK)
+		if ok then
+			local ok, err = pcall(handle_client, session)
+			if not ok then
+				print("cpud [daemon]: error handling client: " .. tostring(err))
+			end
+			session:close()
+		elseif session == "EAGAIN" then
+			linux.schedule(100)
+		end
+	end
+	print("cpud [daemon]: stopped")
+end
+
+return daemon
+