process-metrics 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fc7fb298dde1bb1446b8223bf55be24f776fe8e042c0a5e2ee2cf3452e64383
-  data.tar.gz: 340908860960f819a24c864e3d64bed4288840fad98dc4a0f33f37e622cc22ce
+  metadata.gz: bb30f9e1ffed610ad4a6735a8875f6438eae603ce53e6cb67274e7f893f1c4d5
+  data.tar.gz: 0474ced532e19377ee8b4b7003c21d1a098afc8df5fb3f9865ea163aa756eced
 SHA512:
-  metadata.gz: d7bef8457eb65f378e63d65a768ac8ab4d5d4ae45bcb97f7489b9e06676afeb5fabe2e7b818d132fcae6436e51394ee810ade201f17f8ffd24211db42452b2a5
-  data.tar.gz: 680700b1619d358370114cde3c8d1025c998b0e55ad01d5ee6a3c211857056865f9dd9f5d244ac20ebcb5ec6595f4e8439a2193c28f3765dae17b20df3158b64
+  metadata.gz: 898911e287967bb88596747da31bc6e956bdf4aa8bdea23b461df7998922155d72bd577ca0092320514aa41738547576abd379779a89cf66a22d5a63f0e279f8
+  data.tar.gz: 0f78a3b25a090f9823feae392358281e10f1828a0cb4d324ad880a0a877e0ae34d8cd9d4fbedf7018fe847b5dff1b2f2c6a27702eebb61d714afb46faf4eda7a

data/lib/process/metrics/general/linux.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2019-2026, by Samuel Williams.
+
+require "etc"
+
+module Process
+	module Metrics
+		# General process information by reading /proc. Used on Linux to avoid spawning `ps`.
+		# We read directly from the kernel (proc(5)) so there is no subprocess and no parsing of
+		# external command output; same data source as the kernel uses for process accounting.
+		# Parses /proc/[pid]/stat and /proc/[pid]/cmdline for each process.
+		module General::Linux
+			# Clock ticks per second for /proc stat times (utime, stime, starttime).
+			CLK_TCK = Etc.sysconf(Etc::SC_CLK_TCK) rescue 100
+			
+			# Page size in bytes for RSS (resident set size is in pages in /proc/pid/stat).
+			PAGE_SIZE = Etc.sysconf(Etc::SC_PAGESIZE) rescue 4096
+			
+			# Whether /proc is available so we can list processes without ps.
+			def self.supported?
+				File.directory?("/proc") && File.readable?("/proc/self/stat")
+			end
+			
+			# Capture process information from /proc. If given `pid`, captures only those process(es). If given `ppid`, captures that parent and all descendants. Both can be given to capture a process and its children.
+			# @parameter pid [Integer | Array(Integer)] Process ID(s) to capture.
+			# @parameter ppid [Integer | Array(Integer)] Parent process ID(s) to include children for.
+			# @parameter memory [Boolean] Whether to capture detailed memory metrics (default: Memory.supported?).
+			# @returns [Hash<Integer, General>] Map of PID to General instance.
+			def self.capture(pid: nil, ppid: nil, memory: Memory.supported?)
+				# When filtering by ppid we need the full process list to build the parent-child tree,
+				# so we enumerate all numeric /proc entries; when only pid is set we read just those.
+				pids_to_read = if pid && ppid.nil?
+					Array(pid)
+				else
+					Dir.children("/proc").filter{|e| e.match?(/\A\d+\z/)}.map(&:to_i)
+				end
+				
+				uptime_jiffies = nil
+				
+				processes = {}
+				pids_to_read.each do |pid|
+					stat_path = "/proc/#{pid}/stat"
+					next unless File.readable?(stat_path)
+					
+					stat_content = File.read(stat_path)
+					# comm field can contain spaces and parentheses; find the closing ')' (proc(5)).
+					closing_paren_index = stat_content.rindex(")")
+					next unless closing_paren_index
+					
+					executable_name = stat_content[1...closing_paren_index]
+					fields = stat_content[(closing_paren_index + 2)..].split(/\s+/)
+					# After comm: state(3), ppid(4), pgrp(5), ... utime(14), stime(15), ... starttime(22), vsz(23), rss(24). 0-based: ppid=1, pgrp=2, utime=11, stime=12, starttime=19, vsz=20, rss=21.
+					parent_process_id = fields[1].to_i
+					process_group_id = fields[2].to_i
+					utime = fields[11].to_i
+					stime = fields[12].to_i
+					starttime = fields[19].to_i
+					virtual_size = fields[20].to_i
+					resident_pages = fields[21].to_i
+					
+					# Read /proc/uptime once per capture and reuse for every process (starttime is in jiffies since boot).
+					uptime_jiffies ||= begin
+						uptime_seconds = File.read("/proc/uptime").split(/\s+/).first.to_f
+						(uptime_seconds * CLK_TCK).to_i
+					end
+					
+					processor_time = (utime + stime).to_f / CLK_TCK
+					elapsed_time = [(uptime_jiffies - starttime).to_f / CLK_TCK, 0.0].max
+					
+					command = read_command(pid, executable_name)
+					
+					processes[pid] = General.new(
+						pid,
+						parent_process_id,
+						process_group_id,
+						0.0, # processor_utilization: would need two samples; not available from single stat read
+						virtual_size,
+						resident_pages * PAGE_SIZE,
+						processor_time,
+						elapsed_time,
+						command,
+						nil
+					)
+				rescue Errno::ENOENT, Errno::ESRCH, Errno::EACCES
+					# Process disappeared or we can't read it.
+					next
+				end
+				
+				# Restrict to the requested pid/ppid subtree using the same tree logic as the ps backend.
+				if ppid
+					pids = Set.new
+					hierarchy = General.build_tree(processes)
+					General.expand_children(Array(pid), hierarchy, pids) if pid
+					General.expand_children(Array(ppid), hierarchy, pids)
+					processes.select!{|process_id, _| pids.include?(process_id)}
+				end
+				
+				General.capture_memory(processes) if memory
+				
+				processes
+			end
+			
+			# Read command line from /proc/[pid]/cmdline; fall back to executable name from stat if empty.
+			# Use binread because cmdline is NUL-separated and may contain non-UTF-8 bytes; we split on NUL and join for display.
+			def self.read_command(pid, command_fallback)
+				path = "/proc/#{pid}/cmdline"
+				return command_fallback unless File.readable?(path)
+				
+				cmdline_content = File.binread(path)
+				return command_fallback if cmdline_content.empty?
+				
+				# cmdline is NUL-separated; replace with spaces for display.
+				cmdline_content.split("\0").join(" ").strip
+			rescue Errno::ENOENT, Errno::ESRCH, Errno::EACCES
+				command_fallback
+			end
+		end
+	end
+end
+
+if Process::Metrics::General::Linux.supported?
+	class << Process::Metrics::General
+		def capture(...)
+			Process::Metrics::General::Linux.capture(...)
+		end
+	end
+else
+	require_relative "process_status"
+end

data/lib/process/metrics/general/process_status.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2019-2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		# General process information via the process status command (`ps`). Used on non-Linux platforms (e.g. Darwin)
+		# where there is no /proc; ps is the portable way to get pid, ppid, times, and memory in one pass.
+		module General::ProcessStatus
+			PS = "ps"
+			
+			# The fields that will be extracted from the `ps` command (order matches -o output).
+			FIELDS = {
+				pid: ->(value){value.to_i},
+				ppid: ->(value){value.to_i},
+				pgid: ->(value){value.to_i},
+				pcpu: ->(value){value.to_f},
+				vsz: ->(value){value.to_i * 1024},
+				rss: ->(value){value.to_i * 1024},
+				time: Process::Metrics.method(:duration),
+				etime: Process::Metrics.method(:duration),
+				command: ->(value){value},
+			}
+			
+			# Whether process listing via ps is available on this system.
+			def self.supported?
+				system("which", PS, out: File::NULL, err: File::NULL)
+			end
+			
+			# Capture process information using ps. If given a `pid`, captures that process; if given `ppid`, captures that process and all descendants. Specify both to capture a process and its children.
+			# @parameter pid [Integer | Array(Integer)] Process ID(s) to capture.
+			# @parameter ppid [Integer | Array(Integer)] Parent process ID(s) to include children for.
+			# @parameter memory [Boolean] Whether to capture detailed memory metrics (default: Memory.supported?).
+			# @returns [Hash<Integer, General>] Map of PID to General instance.
+			def self.capture(pid: nil, ppid: nil, memory: Memory.supported?)
+				spawned_pid = nil
+				
+				header, *lines = IO.pipe do |input, output|
+					arguments = [PS]
+					
+					# When filtering by ppid we need the full process list to build the tree, so use "ax"; otherwise limit to -p.
+					if pid && ppid.nil?
+						arguments.push("-p", Array(pid).join(","))
+					else
+						arguments.push("ax")
+					end
+					
+					arguments.push("-o", FIELDS.keys.join(","))
+					
+					spawned_pid = Process.spawn(*arguments, out: output)
+					output.close
+					
+					input.readlines.map(&:strip)
+				ensure
+					input.close
+					
+					# Always kill and reap the ps subprocess so we never leave it hanging if the pipe closes early.
+					if spawned_pid
+						begin
+							Process.kill(:KILL, spawned_pid)
+							Process.wait(spawned_pid)
+						rescue => error
+							warn "Failed to cleanup ps process #{spawned_pid}:\n#{error.full_message}"
+						end
+					end
+				end
+				
+				processes = {}
+				
+				lines.each do |line|
+					next if line.empty?
+					
+					values = line.split(/\s+/, FIELDS.size)
+					next if values.size < FIELDS.size
+					
+					record = FIELDS.keys.map.with_index{|key, i| FIELDS[key].call(values[i])}
+					instance = General.new(*record, nil)
+					processes[instance.process_id] = instance
+				end
+				
+				# Restrict to the requested pid/ppid subtree; exclude our own ps process from the result.
+				if ppid
+					pids = Set.new
+					hierarchy = General.build_tree(processes)
+					General.expand_children(Array(pid), hierarchy, pids) if pid
+					General.expand_children(Array(ppid), hierarchy, pids)
+					processes.select!{|process_id, _| process_id != spawned_pid && pids.include?(process_id)}
+				else
+					processes.delete(spawned_pid) if spawned_pid
+				end
+				
+				General.capture_memory(processes) if memory
+				
+				processes
+			end
+		end
+	end
+end
+
+# Wire General.capture to this implementation when ProcessStatus is available and the Linux backend is not active (so Linux can load both for comparison tests).
+linux_supported = defined?(Process::Metrics::General::Linux) && Process::Metrics::General::Linux.supported?
+if Process::Metrics::General::ProcessStatus.supported? && !linux_supported
+	class << Process::Metrics::General
+		def capture(...)
+			Process::Metrics::General::ProcessStatus.capture(...)
+		end
+	end
+end

data/lib/process/metrics/general.rb

@@ -9,8 +9,6 @@ require "json"
 
 module Process
 	module Metrics
-		PS = "ps"
-		
 		DURATION = /\A
 			(?:(?<days>\d+)-)?              # Optional days (e.g., '2-')
 			(?:(?<hours>\d+):)?             # Optional hours (e.g., '1:')
@@ -36,19 +34,6 @@ module Process
 			end
 		end
 		
-		# The fields that will be extracted from the `ps` command.
-		FIELDS = {
-			pid: ->(value){value.to_i}, # Process ID
-			ppid: ->(value){value.to_i}, # Parent Process ID
-			pgid: ->(value){value.to_i}, # Process Group ID
-			pcpu: ->(value){value.to_f}, # Percentage CPU
-			vsz: ->(value){value.to_i * 1024}, # Virtual Size (convert from KiB to bytes)
-			rss: ->(value){value.to_i * 1024}, # Resident Size (convert from KiB to bytes)
-			time: self.method(:duration), # CPU Time (seconds)
-			etime: self.method(:duration), # Elapsed Time (seconds)
-			command: ->(value){value}, # Command (name of the process)
-		}
-		
 		# General process information.
 		class General < Struct.new(:process_id, :parent_process_id, :process_group_id, :processor_utilization, :virtual_size, :resident_size, :processor_time, :elapsed_time, :command, :memory)
 			# Convert the object to a JSON serializable hash.
@@ -132,77 +117,13 @@ module Process
 					process.memory = Memory.capture(pid, count: count)
 				end
 			end
-			
-			# Capture process information. If given a `pid`, it will capture the details of that process. If given a `ppid`, it will capture the details of all child processes. Specify both `pid` and `ppid` if you want to capture a process and all its children.
-			#
-			# @parameter pid [Integer] The process ID to capture.
-			# @parameter ppid [Integer] The parent process ID to capture.
-			def self.capture(pid: nil, ppid: nil, memory: Memory.supported?)
-				ps_pid = nil
-				
-				# Extract the information from the `ps` command:
-				header, *lines = IO.pipe do |input, output|
-					arguments = [PS]
-					
-					if pid && ppid.nil?
-						arguments.push("-p", Array(pid).join(","))
-					else
-						arguments.push("ax")
-					end
-					
-					arguments.push("-o", FIELDS.keys.join(","))
-					
-					ps_pid = Process.spawn(*arguments, out: output)
-					output.close
-					
-					input.readlines.map(&:strip)
-				ensure
-					input.close
-					
-					if ps_pid
-						begin
-							# Make sure to kill the ps process if it's still running:
-							Process.kill(:KILL, ps_pid)
-							# Reap the process:
-							Process.wait(ps_pid)
-						rescue => error
-							warn "Failed to cleanup ps process #{ps_pid}:\n#{error.full_message}"
-						end
-					end
-				end
-				
-				processes = {}
-				
-				lines.map do |line|
-					record = FIELDS.
-						zip(line.split(/\s+/, FIELDS.size)).
-						map{|(key, type), value| type.call(value)}
-					instance = self.new(*record)
-					
-					processes[instance.process_id] = instance
-				end
-				
-				if ppid
-					pids = Set.new
-					
-					hierarchy = self.build_tree(processes)
-					
-					self.expand_children(Array(pid), hierarchy, pids)
-					self.expand_children(Array(ppid), hierarchy, pids)
-					
-					processes.select! do |pid, process|
-						if pid != ps_pid
-							pids.include?(pid)
-						end
-					end
-				end
-				
-				if memory
-					self.capture_memory(processes)
-				end
-				
-				return processes
-			end
 		end
 	end
 end
+
+# One backend provides General.capture: Linux uses /proc (no subprocess); other platforms use ps.
+if RUBY_PLATFORM.include?("linux")
+	require_relative "general/linux"
+else
+	require_relative "general/process_status"
+end

data/lib/process/metrics/host/memory/darwin.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		module Host
+			# Darwin (macOS) implementation of host memory metrics.
+			# Uses sysctl (hw.memsize), vm_stat (free + inactive pages), and vm.swapusage for swap.
+			class Memory::Darwin
+				# Parse a size string from vm.swapusage (e.g. "1024.00M", "512.00K") into bytes.
+				# @parameter size_string [String | Nil] The size string from sysctl vm.swapusage.
+				# @returns [Integer | Nil] Size in bytes, or nil if size_string is nil/empty.
+				def self.parse_swap_size(size_string)
+					return nil unless size_string
+					
+					size_string = size_string.strip
+					
+					case size_string
+					when /([\d.]+)M/i then ($1.to_f * 1024 * 1024).round
+					when /([\d.]+)G/i then ($1.to_f * 1024 * 1024 * 1024).round
+					when /([\d.]+)K/i then ($1.to_f * 1024).round
+					else size_string.to_f.round
+					end
+				end
+				
+				# Capture current host memory. Reads total (hw.memsize), free (vm_stat), and swap (vm.swapusage).
+				# @returns [Host::Memory | Nil] A Host::Memory instance, or nil if capture fails.
+				def self.capture
+					total = capture_total
+					return nil unless total && total.positive?
+					
+					free = capture_free
+					return nil unless free
+					
+					free = 0 if free.negative?
+					used = [total - free, 0].max
+					swap_total, swap_used = capture_swap
+					
+					return Host::Memory.new(total, used, free, swap_total, swap_used)
+				end
+				
+				# Total physical RAM in bytes, from sysctl hw.memsize.
+				# @returns [Integer | Nil]
+				def self.capture_total
+					IO.popen(["sysctl", "-n", "hw.memsize"], "r", &:read)&.strip&.to_i
+				end
+				
+				# Free + inactive (reclaimable) memory in bytes, from vm_stat. Matches Linux MemAvailable semantics.
+				# @returns [Integer | Nil]
+				def self.capture_free
+					output = IO.popen(["vm_stat"], "r", &:read)
+					page_size = output[/page size of (\d+) bytes/, 1]&.to_i
+					return nil unless page_size && page_size.positive?
+					
+					pages_free = output[/Pages free:\s*(\d+)/, 1]&.to_i || 0
+					pages_inactive = output[/Pages inactive:\s*(\d+)/, 1]&.to_i || 0
+					return (pages_free + pages_inactive) * page_size
+				end
+				
+				# Swap total and used in bytes, from sysctl vm.swapusage (e.g. "total = 64.00M  used = 32.00M  free = 32.00M").
+				# @returns [Array(Integer | Nil, Integer | Nil)] [swap_total_bytes, swap_used_bytes], or [nil, nil] if unavailable.
+				def self.capture_swap
+					output = IO.popen(["sysctl", "-n", "vm.swapusage"], "r", &:read)
+					return [nil, nil] unless output
+					
+					total_string = output[/total\s*=\s*([\d.]+\s*[KMG]?)/i, 1]
+					used_string = output[/used\s*=\s*([\d.]+\s*[KMG]?)/i, 1]
+					swap_total = total_string ? parse_swap_size(total_string) : nil
+					swap_used = used_string ? parse_swap_size(used_string) : nil
+					
+					return swap_total, swap_used
+				end
+			end
+		end
+	end
+end
+
+# Wire Host::Memory to this implementation on Darwin.
+class << Process::Metrics::Host::Memory
+	def capture
+		Process::Metrics::Host::Memory::Darwin.capture
+	end
+	
+	def supported?
+		File.exist?("/usr/bin/vm_stat")
+	end
+end

data/lib/process/metrics/host/memory/linux.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		module Host
+			# Linux implementation of host memory metrics.
+			# Uses cgroups v2 (memory.max, memory.current) or cgroups v1 (memory.limit_in_bytes, memory.usage_in_bytes) when in a container;
+			# otherwise reads /proc/meminfo (MemTotal, MemAvailable/MemFree, SwapTotal/SwapFree). Parses meminfo once per capture and reuses it.
+			class Memory::Linux
+				# Threshold for distinguishing actual memory limits from "unlimited" sentinel values in cgroups v1.
+				# In cgroups v1, when memory.limit_in_bytes is set to unlimited (by writing -1), the kernel stores a very large sentinel near 2^63.
+				# Any value >= 2^60 (1 exabyte) is treated as unlimited and we fall back to /proc/meminfo.
+				# Reference: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt
+				CGROUP_V1_UNLIMITED_THRESHOLD = 2**60
+				
+				def initialize
+					@meminfo = false
+				end
+				
+				# Capture current host memory. Reads total and used (from cgroup or meminfo), computes free, and parses swap from meminfo.
+				# @returns [Host::Memory | Nil]
+				def capture
+					total = capture_total
+					return nil unless total && total.positive?
+					
+					used = capture_used(total)
+					used = 0 if used.nil? || used.negative?
+					used = [used, total].min
+					free = total - used
+					
+					swap_total, swap_used = capture_swap
+					
+					return Host::Memory.new(total, used, free, swap_total, swap_used)
+				end
+				
+				private
+				
+				# Memoized /proc/meminfo contents. Used for total (MemTotal), used (via MemAvailable), and swap when not in a cgroup.
+				# @returns [String | Nil]
+				def meminfo
+					if @meminfo == false
+						@meminfo = File.read("/proc/meminfo") rescue nil
+					end
+					
+					return @meminfo
+				end
+				
+				# Total memory in bytes: cgroups v2 memory.max, cgroups v1 memory.limit_in_bytes (if < threshold), else MemTotal from meminfo.
+				# @returns [Integer | Nil]
+				def capture_total
+					if File.exist?("/sys/fs/cgroup/memory.max")
+						limit = File.read("/sys/fs/cgroup/memory.max").strip
+						return limit.to_i if limit != "max"
+					end
+					
+					if File.exist?("/sys/fs/cgroup/memory/memory.limit_in_bytes")
+						limit = File.read("/sys/fs/cgroup/memory/memory.limit_in_bytes").strip.to_i
+						return limit if limit > 0 && limit < CGROUP_V1_UNLIMITED_THRESHOLD
+					end
+					
+					unless meminfo_content = self.meminfo
+						return nil
+					end
+					
+					meminfo_content.each_line do |line|
+						if /MemTotal:\s*(?<total>\d+)\s*kB/ =~ line
+							return $~[:total].to_i * 1024
+						end
+					end
+					
+					return nil
+				end
+				
+				# Current memory usage in bytes: cgroups v2 memory.current, cgroups v1 memory.usage_in_bytes, or total - MemAvailable from meminfo.
+				# @parameter total [Integer] Total memory (used to compute used from MemAvailable when not in cgroup).
+				# @returns [Integer | Nil]
+				def capture_used(total)
+					if File.exist?("/sys/fs/cgroup/memory.current")
+						current = File.read("/sys/fs/cgroup/memory.current").strip.to_i
+						return current
+					end
+					
+					if File.exist?("/sys/fs/cgroup/memory/memory.usage_in_bytes")
+						limit = File.read("/sys/fs/cgroup/memory/memory.limit_in_bytes").strip.to_i
+						if limit > 0 && limit < CGROUP_V1_UNLIMITED_THRESHOLD
+							return File.read("/sys/fs/cgroup/memory/memory.usage_in_bytes").strip.to_i
+						end
+					end
+					
+					unless meminfo_content = self.meminfo
+						return nil
+					end
+					
+					available_kilobytes = meminfo_content[/MemAvailable:\s*(\d+)\s*kB/, 1]&.to_i
+					available_kilobytes ||= meminfo_content[/MemFree:\s*(\d+)\s*kB/, 1]&.to_i
+					return nil unless available_kilobytes
+					
+					return [total - (available_kilobytes * 1024), 0].max
+				end
+				
+				# Swap total and used in bytes from meminfo (SwapTotal, SwapFree).
+				# @returns [Array(Integer, Integer)] [swap_total_bytes, swap_used_bytes], or [nil, nil] if no swap.
+				def capture_swap
+					return [nil, nil] unless meminfo_content = self.meminfo
+					swap_total_kilobytes = meminfo_content[/SwapTotal:\s*(\d+)\s*kB/, 1]&.to_i
+					swap_free_kilobytes = meminfo_content[/SwapFree:\s*(\d+)\s*kB/, 1]&.to_i
+					
+					return [nil, nil] unless swap_total_kilobytes
+					
+					swap_total_bytes = swap_total_kilobytes * 1024
+					swap_used_bytes = (swap_total_kilobytes - (swap_free_kilobytes || 0)) * 1024
+					
+					return swap_total_bytes, swap_used_bytes
+				end
+			end
+		end
+	end
+end
+
+# Wire Host::Memory to this implementation on Linux.
+class << Process::Metrics::Host::Memory
+	def capture
+		Process::Metrics::Host::Memory::Linux.new.capture
+	end
+	
+	def supported?
+		File.exist?("/proc/meminfo")
+	end
+end

data/lib/process/metrics/host/memory.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		# Per-host (system-wide) memory metrics. Use Host::Memory for total/used/free and swap; use Process::Metrics::Memory for per-process metrics.
+		module Host
+			# Struct for host memory snapshot. All sizes in bytes.
+			# @attribute total [Integer] Total memory (cgroup limit when in a container, else physical RAM).
+			# @attribute used [Integer] Memory in use (total - free).
+			# @attribute free [Integer] Available memory (MemAvailable-style: free + reclaimable).
+			# @attribute swap_total [Integer, nil] Total swap, or nil if not available.
+			# @attribute swap_used [Integer, nil] Swap in use, or nil if not available.
+			Memory = Struct.new(:total, :used, :free, :swap_total, :swap_used) do
+				alias as_json to_h
+				
+				def to_json(*arguments)
+					as_json.to_json(*arguments)
+				end
+				
+				# Create a zero-initialized Host::Memory instance.
+				# @returns [Memory]
+				def self.zero
+					self.new(0, 0, 0, nil, nil)
+				end
+				
+				# Whether host memory capture is supported on this platform.
+				# @returns [Boolean]
+				def self.supported?
+					false
+				end
+				
+				# Capture current host memory. Implemented by Host::Memory::Linux or Host::Memory::Darwin (in host/memory/linux.rb, host/memory/darwin.rb).
+				# @returns [Memory | Nil] A Host::Memory instance, or nil if not supported or capture failed.
+				def self.capture
+					return nil
+				end
+			end
+		end
+	end
+end
+
+if RUBY_PLATFORM.include?("linux")
+	require_relative "memory/linux"
+elsif RUBY_PLATFORM.include?("darwin")
+	require_relative "memory/darwin"
+end

data/lib/process/metrics/memory/darwin.rb

@@ -5,7 +5,8 @@
 
 module Process
 	module Metrics
-		# Darwin (macOS) implementation of memory metrics using vmmap.
+		# Darwin (macOS) implementation of per-process memory metrics using vmmap(1).
+		# Parses vmmap output for virtual/resident/dirty/swap per region and maps sharing mode (PRV, COW, SHM) to private/shared fields.
 		class Memory::Darwin
 			VMMAP = "/usr/bin/vmmap"
 			
@@ -14,32 +15,21 @@ module Process
 				File.executable?(VMMAP)
 			end
 			
-			# @returns [Numeric] Total memory size in bytes.
-			def self.total_size
-				# sysctl hw.memsize
-				IO.popen(["sysctl", "hw.memsize"], "r") do |io|
-					io.each_line do |line|
-						if line =~ /hw.memsize: (\d+)/
-							return $1.to_i
-						end
-					end
-				end
-			end
-			
-			# Parse a size string from vmmap output into bytes.
-			# @parameter string [String | Nil] The size string (e.g., "4K", "1.5M", "2G").
-			# @returns [Integer] The size in bytes.
-			def self.parse_size(string)
-				return 0 unless string
+			# Parse a size string from vmmap (e.g. "4K", "1.5M", "2G") into bytes.
+			# @parameter size_string [String | Nil]
+			# @returns [Integer]
+			def self.parse_size(size_string)
+				return 0 unless size_string
 				
-				case string.strip
+				case size_string.strip
 				when /([\d\.]+)K/i then ($1.to_f * 1024).round
 				when /([\d\.]+)M/i then ($1.to_f * 1024 * 1024).round
 				when /([\d\.]+)G/i then ($1.to_f * 1024 * 1024 * 1024).round
-				else (string.to_f).ceil
+				else (size_string.to_f).ceil
 				end
 			end
 			
+			# Regex for vmmap region lines: region name, address range, [virtual resident dirty swap], permissions, SM=sharing_mode.
 			LINE = /\A
 				\s*
 				(?<region_name>.+?)\s+
@@ -49,26 +39,24 @@ module Process
 				SM=(?<sharing_mode>\w+)
 			/x
 			
-			# Capture memory usage for the given process IDs.
+			# Capture memory usage by running vmmap for the given pid and summing region sizes. Proportional size is estimated as resident_size / count (Darwin has no PSS).
+			# @parameter pid [Integer] Process ID.
+			# @parameter count [Integer] Number of processes for proportional estimate (default: 1).
+			# @returns [Memory | Nil]
 			def self.capture(pid, count: 1, **options)
 				IO.popen(["vmmap", pid.to_s], "r") do |io|
 					usage = Memory.zero
-					
 					io.each_line do |line|
 						if match = LINE.match(line)
 							usage.map_count += 1
-							
 							virtual_size = parse_size(match[:virtual_size])
 							resident_size = parse_size(match[:resident_size])
 							dirty_size = parse_size(match[:dirty_size])
 							swap_size = parse_size(match[:swap_size])
-							
 							usage.resident_size += resident_size
 							usage.swap_size += swap_size
 							
-							# Private vs. Shared memory
-							# COW=copy_on_write PRV=private NUL=empty ALI=aliased 
-							# SHM=shared ZER=zero_filled S/A=shared_alias
+							# Private vs. Shared memory: COW=copy_on_write PRV=private NUL=empty ALI=aliased SHM=shared ZER=zero_filled S/A=shared_alias
 							case match[:sharing_mode]
 							when "PRV"
 								usage.private_clean_size += resident_size - dirty_size
@@ -85,10 +73,8 @@ module Process
 						end
 					end
 					
-					if usage.map_count.zero?
-						# vmap might not fail, but also might not return any data.
-						return nil
-					end
+					# vmmap might not fail, but also might not return any data.
+					return nil if usage.map_count.zero?
 					
 					# Darwin does not expose proportional memory usage, so we guess based on the number of processes. Yes, this is a terrible hack, but it's the most reasonable thing to do given the constraints:
 					usage.proportional_size = usage.resident_size / count
@@ -101,29 +87,24 @@ module Process
 				return nil
 			end
 		end
+	end
+end
+
+# Wire Memory.capture and Memory.supported? to this implementation when vmmap is executable.
+if Process::Metrics::Memory::Darwin.supported?
+	class << Process::Metrics::Memory
+		# Whether memory capture is supported on this platform.
+		# @returns [Boolean] True if vmmap is available.
+		def supported?
+			true
+		end
 		
-		if Memory::Darwin.supported?
-			class << Memory
-				# Whether memory capture is supported on this platform.
-				# @returns [Boolean] True if vmmap is available.
-				def supported?
-					return true
-				end
-				
-				# Get total system memory size.
-				# @returns [Integer] Total memory in bytes.
-				def total_size
-					return Memory::Darwin.total_size
-				end
-				
-				# Capture memory metrics for a process.
-				# @parameter pid [Integer] The process ID.
-				# @parameter options [Hash] Additional options (e.g., count for proportional estimates).
-				# @returns [Memory] A Memory instance with captured metrics.
-				def capture(...)
-					return Memory::Darwin.capture(...)
-				end
-			end
+		# Capture memory metrics for a process.
+		# @parameter pid [Integer] The process ID.
+		# @parameter options [Hash] Additional options (e.g. count for proportional estimates).
+		# @returns [Memory | Nil] A Memory instance with captured metrics.
+		def capture(...)
+			Process::Metrics::Memory::Darwin.capture(...)
 		end
 	end
 end

data/lib/process/metrics/memory/linux.rb

@@ -5,31 +5,18 @@
 
 module Process
 	module Metrics
-		# Linux implementation of memory metrics using `/proc/[pid]/smaps` and `/proc/[pid]/stat`.
+		# Linux implementation of per-process memory metrics using `/proc/[pid]/smaps` or `/proc/[pid]/smaps_rollup`, and `/proc/[pid]/stat` for fault counters.
+		# Prefers smaps_rollup when readable (single summary); otherwise falls back to full smaps and counts maps from /proc/[pid]/maps.
 		class Memory::Linux
-			# Threshold for distinguishing actual memory limits from "unlimited" sentinel values in cgroups v1.
-			# 
-			# In cgroups v1, when memory.limit_in_bytes is set to unlimited (by writing -1),
-			# the kernel stores a very large sentinel value close to 2^63 (approximately 9,223,372,036,854,771,712 bytes).
-			# Since no real system would have 1 exabyte (2^60 bytes) of RAM, any value >= this threshold
-			# indicates an "unlimited" configuration and should be treated as if no limit is set.
-			#
-			# This allows us to distinguish between:
-			# - Actual container memory limits: typically in GB-TB range (< 1 EB)
-			# - Unlimited sentinel values: near 2^63 (>> 1 EB)
-			#
-			# Reference: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt
-			CGROUP_V1_UNLIMITED_THRESHOLD = 2**60 # ~1 exabyte
-			
-			# Extract minor/major page fault counters from `/proc/[pid]/stat` and assign to usage.
-			# @parameter pid [Integer] The process ID.
-			# @parameter usage [Memory] The Memory instance to populate with fault counters.
+			# Extract minor and major page fault counters from `/proc/[pid]/stat` (proc(5): fields 10=minflt, 12=majflt) and assign to usage.
+			# @parameter pid [Integer] Process ID.
+			# @parameter usage [Memory] Memory instance to populate with minor_faults and major_faults.
 			def self.capture_faults(pid, usage)
-				stat = File.read("/proc/#{pid}/stat")
+				stat_content = File.read("/proc/#{pid}/stat")
 				# The comm field can contain spaces and parentheses; find the closing ')':
-				rparen_index = stat.rindex(")")
-				return unless rparen_index
-				fields = stat[(rparen_index+2)..-1].split(/\s+/)
+				closing_paren_index = stat_content.rindex(")")
+				return unless closing_paren_index
+				fields = stat_content[(closing_paren_index + 2)..].split(/\s+/)
 				# proc(5): field 10=minflt, 12=majflt; our fields array is 0-indexed from field 3.
 				usage.minor_faults = fields[10-3].to_i
 				usage.major_faults = fields[12-3].to_i
@@ -37,39 +24,7 @@ module Process
 				# Ignore.
 			end
 			
-			# Determine the total memory size in bytes. This is the maximum amount of memory that can be used by the current process. If running in a container, this may be limited by the container runtime (e.g. cgroups).
-			#
-			# @returns [Integer] The total memory size in bytes.
-			def self.total_size
-				# Check for Kubernetes/cgroup memory limit first (cgroups v2):
-				if File.exist?("/sys/fs/cgroup/memory.max")
-					limit = File.read("/sys/fs/cgroup/memory.max").strip
-					# "max" means unlimited, fall through to other methods:
-					if limit != "max"
-						return limit.to_i
-					end
-				end
-				
-				# Check for Kubernetes/cgroup memory limit (cgroups v1):
-				if File.exist?("/sys/fs/cgroup/memory/memory.limit_in_bytes")
-					limit = File.read("/sys/fs/cgroup/memory/memory.limit_in_bytes").strip.to_i
-					# A very large number means unlimited, fall through:
-					if limit > 0 && limit < CGROUP_V1_UNLIMITED_THRESHOLD
-						return limit
-					end
-				end
-				
-				# Fall back to Linux system memory detection:
-				if File.exist?("/proc/meminfo")
-					File.foreach("/proc/meminfo") do |line|
-						if /MemTotal:\s*(?<total>\d+)\s*kB/ =~ line
-							return total.to_i * 1024
-						end
-					end
-				end
-			end
-			
-			# The fields that will be extracted from the `smaps` data.
+			# Mapping from smaps/smaps_rollup line names to Memory struct members (values in kB, converted to bytes when parsing).
 			SMAP = {
 				"Rss" => :resident_size,
 				"Pss" => :proportional_size,
@@ -89,24 +44,24 @@ module Process
 					true
 				end
 				
-				# Capture memory usage for the given process IDs.
-				# @parameter pid [Integer] The process ID.
-				# @parameter faults [Boolean] Whether to capture fault counters (default: true).
-				# @parameter options [Hash] Additional options.
+				# Capture memory usage from /proc/[pid]/smaps_rollup and /proc/[pid]/maps. Optionally fill fault counters from /proc/[pid]/stat.
+				# @parameter pid [Integer] Process ID.
+				# @parameter faults [Boolean] Whether to capture minor_faults and major_faults (default: true).
+				# @returns [Memory | Nil]
 				def self.capture(pid, faults: true, **options)
 					File.open("/proc/#{pid}/smaps_rollup") do |file|
 						usage = Memory.zero
-						
 						file.each_line do |line|
 							if /(?<name>.*?):\s+(?<value>\d+) kB/ =~ line
 								if key = SMAP[name]
-									# Convert from kilobytes to bytes
+									# Convert from kilobytes to bytes:
 									usage[key] += value.to_i * 1024
 								end
 							end
 						end
 						
 						usage.map_count += File.readlines("/proc/#{pid}/maps").size
+						
 						# Also capture fault counters if requested:
 						if faults
 							self.capture_faults(pid, usage)
@@ -124,20 +79,19 @@ module Process
 					true
 				end
 				
-				# Capture memory usage for the given process IDs.
-				# @parameter pid [Integer] The process ID.
-				# @parameter faults [Boolean] Whether to capture fault counters (default: true).
-				# @parameter options [Hash] Additional options.
+				# Capture memory usage from /proc/[pid]/smaps (and map count from VmFlags) and /proc/[pid]/maps. Optionally fill fault counters from /proc/[pid]/stat.
+				# @parameter pid [Integer] Process ID.
+				# @parameter faults [Boolean] Whether to capture minor_faults and major_faults (default: true).
+				# @returns [Memory | Nil]
 				def self.capture(pid, faults: true, **options)
 					File.open("/proc/#{pid}/smaps") do |file|
 						usage = Memory.zero
-						
 						file.each_line do |line|
 							# The format of this is fixed according to:
 							# https://github.com/torvalds/linux/blob/351c8a09b00b5c51c8f58b016fffe51f87e2d820/fs/proc/task_mmu.c#L804-L814
 							if /(?<name>.*?):\s+(?<value>\d+) kB/ =~ line
 								if key = SMAP[name]
-									# Convert from kilobytes to bytes
+									# Convert from kilobytes to bytes:
 									usage[key] += value.to_i * 1024
 								end
 							elsif /VmFlags:\s+(?<flags>.*)/ =~ line
@@ -148,7 +102,9 @@ module Process
 						end
 						
 						# Also capture fault counters if requested:
-						self.capture_faults(pid, usage) if faults
+						if faults
+							self.capture_faults(pid, usage)
+						end
 						
 						return usage
 					end
@@ -162,30 +118,25 @@ module Process
 				end
 			end
 		end
+	end
+end
+
+# Wire Memory.capture and Memory.supported? to this implementation when smaps or smaps_rollup is readable.
+if Process::Metrics::Memory::Linux.supported?
+	class << Process::Metrics::Memory
+		# Whether memory capture is supported on this platform.
+		# @returns [Boolean] True if /proc/[pid]/smaps or smaps_rollup is readable.
+		def supported?
+			true
+		end
 		
-		if Memory::Linux.supported?
-			class << Memory
-				# Whether memory capture is supported on this platform.
-				# @returns [Boolean] True if /proc/[pid]/smaps or smaps_rollup is readable.
-				def supported?
-					return true
-				end
-				
-				# Get total system memory size.
-				# @returns [Integer] Total memory in bytes.
-				def total_size
-					return Memory::Linux.total_size
-				end
-				
-				# Capture memory metrics for a process.
-				# @parameter pid [Integer] The process ID.
-				# @parameter faults [Boolean] Whether to capture fault counters (default: true).
-				# @parameter options [Hash] Additional options.
-				# @returns [Memory] A Memory instance with captured metrics.
-				def capture(...)
-					return Memory::Linux.capture(...)
-				end
-			end
+		# Capture memory metrics for a process.
+		# @parameter pid [Integer] The process ID.
+		# @parameter faults [Boolean] Whether to capture fault counters (default: true).
+		# @parameter options [Hash] Additional options.
+		# @returns [Memory | Nil] A Memory instance with captured metrics.
+		def capture(...)
+			Process::Metrics::Memory::Linux.capture(...)
 		end
 	end
 end

data/lib/process/metrics/memory.rb

@@ -4,6 +4,7 @@
 # Copyright, 2019-2026, by Samuel Williams.
 
 require "json"
+require_relative "host/memory"
 
 module Process
 	module Metrics
@@ -33,6 +34,12 @@ module Process
 				self.new(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
 			end
 			
+			# Total system/host memory in bytes. Delegates to Host::Memory.capture.
+			# @returns [Integer | Nil]
+			def self.total_size
+				Host::Memory.capture&.total
+			end
+			
 			# Whether the memory usage can be captured on this system.
 			def self.supported?
 				false
@@ -46,5 +53,8 @@ module Process
 	end
 end
 
-require_relative "memory/linux"
-require_relative "memory/darwin"
+if RUBY_PLATFORM.include?("linux")
+	require_relative "memory/linux"
+elsif RUBY_PLATFORM.include?("darwin")
+	require_relative "memory/darwin"
+end

data/lib/process/metrics/version.rb

@@ -7,6 +7,6 @@
 module Process
 	# @namespace
 	module Metrics
-		VERSION = "0.9.0"
+		VERSION = "0.10.0"
 	end
 end

data/readme.md

@@ -16,12 +16,22 @@ Please see the [project documentation](https://socketry.github.io/process-metric
 
 Please see the [project releases](https://socketry.github.io/process-metrics/releases/index) for all releases.
 
+### v0.10.0
+
+  - **Host::Memory**: New per-host struct `Process::Metrics::Host::Memory` with `total`, `used`, `free`, `swap_total`, `swap_used` (all bytes). Use `Host::Memory.capture` to get a snapshot; `.supported?` indicates platform support.
+
 ### v0.9.0
 
   - `Process::Metrics::Memory.total_size` takes into account cgroup limits.
   - On Linux, capturing faults is optional, controlled by `capture(faults: true/false)`.
   - Report all sizes in bytes for consistency.
 
+### v0.8.0
+
+  - Kill `ps` before waiting to avoid hanging when using the process-status backend.
+  - Ignore `Errno::EACCES` when reading process information.
+  - Cleaner process management for the `ps`-based capture path.
+
 ### v0.7.0
 
   - Be more proactive about returning nil if memory capture failed.
@@ -61,18 +71,6 @@ Please see the [project releases](https://socketry.github.io/process-metrics/rel
   - Added missing dependencies: `bake-test-external` and `json` gem.
   - Added summary lines for PSS (Proportional Set Size) and USS (Unique Set Size).
 
-### v0.2.1
-
-  - Added missing dependency to gemspec.
-  - Added example of command line usage to documentation.
-  - Renamed `rsz` to `rss` (Resident Set Size) for consistency across Darwin and Linux platforms.
-
-### v0.2.0
-
-  - Added `process-metrics` command line interface for monitoring processes.
-  - Implemented structured data using Ruby structs for better performance and clarity.
-  - Added documentation about PSS (Proportional Set Size) and USS (Unique Set Size) metrics.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,11 +1,21 @@
 # Releases
 
+## v0.10.0
+
+  - **Host::Memory**: New per-host struct `Process::Metrics::Host::Memory` with `total`, `used`, `free`, `swap_total`, `swap_used` (all bytes). Use `Host::Memory.capture` to get a snapshot; `.supported?` indicates platform support.
+
 ## v0.9.0
 
   - `Process::Metrics::Memory.total_size` takes into account cgroup limits.
   - On Linux, capturing faults is optional, controlled by `capture(faults: true/false)`.
   - Report all sizes in bytes for consistency.
 
+## v0.8.0
+
+  - Kill `ps` before waiting to avoid hanging when using the process-status backend.
+  - Ignore `Errno::EACCES` when reading process information.
+  - Cleaner process management for the `ps`-based capture path.
+
 ## v0.7.0
 
   - Be more proactive about returning nil if memory capture failed.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process-metrics
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -94,6 +94,11 @@ files:
 - lib/process/metrics/command/summary.rb
 - lib/process/metrics/command/top.rb
 - lib/process/metrics/general.rb
+- lib/process/metrics/general/linux.rb
+- lib/process/metrics/general/process_status.rb
+- lib/process/metrics/host/memory.rb
+- lib/process/metrics/host/memory/darwin.rb
+- lib/process/metrics/host/memory/linux.rb
 - lib/process/metrics/memory.rb
 - lib/process/metrics/memory/darwin.rb
 - lib/process/metrics/memory/linux.rb