Consistent host memory (free and available).

Author: samuel-williams-shopify

lib/process/metrics/host/memory.rb

@@ -8,22 +8,37 @@ 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.
+			# Stored: total_size, used_size, swap_*, reclaimable_size. free_size and available_size are derived.
 			# @attribute total_size [Integer] Total memory (cgroup limit when in a container, else physical RAM).
-			# @attribute used_size [Integer] Memory in use (total_size - free_size).
-			# @attribute free_size [Integer] Available memory (MemAvailable-style: free + reclaimable).
+			# @attribute used_size [Integer] Memory in use (kernel/cgroup view; on Linux includes reclaimable e.g. page cache).
 			# @attribute swap_total_size [Integer, nil] Total swap, or nil if not available.
 			# @attribute swap_used_size [Integer, nil] Swap in use, or nil if not available.
-			Memory = Struct.new(:total_size, :used_size, :free_size, :swap_total_size, :swap_used_size) do
+			# @attribute reclaimable_size [Integer, nil] Reclaimable memory (e.g. page cache, slab), or nil. Included in used_size.
+			Memory = Struct.new(:total_size, :used_size, :swap_total_size, :swap_used_size, :reclaimable_size) do
+				def to_h
+					super.merge(free_size: free_size, available_size: available_size)
+				end
+				
 				alias as_json to_h
 
 				def to_json(*arguments)
 					as_json.to_json(*arguments)
 				end
 
+				# Complement of used: total_size - used_size. Same meaning on all platforms.
+				def free_size
+					total_size - used_size
+				end
+				
+				# Memory that could be used: free_size plus reclaimable. Use this for "available" when reclaimable_size is set; otherwise equals free_size.
+				def available_size
+					free_size + (reclaimable_size || 0)
+				end
+				
 				# Create a zero-initialized Host::Memory instance.
 				# @returns [Memory]
 				def self.zero
-					self.new(0, 0, 0, nil, nil)
+					self.new(0, 0, nil, nil, nil)
 				end
 
 				# Whether host memory capture is supported on this platform.

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

@@ -38,7 +38,7 @@ def self.capture
 					used = [total - free, 0].max
 					swap_total, swap_used = capture_swap
 
-					return Host::Memory.new(total, used, free, swap_total, swap_used)
+					return Host::Memory.new(total, used, swap_total, swap_used, nil)
 				end
 
 				# Total physical RAM in bytes, from sysctl hw.memsize.

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

@@ -15,12 +15,14 @@ class Memory::Linux
 				# 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
+				DEFAULT_CGROUP_ROOT = "/sys/fs/cgroup"
 
-				def initialize
+				def initialize(cgroup_root: nil)
+					@cgroup_root = (cgroup_root || DEFAULT_CGROUP_ROOT).to_s.chomp("/")
 					@meminfo = false
 				end
 
-				# Capture current host memory. Reads total and used (from cgroup or meminfo), computes free, and parses swap from meminfo.
+				# Capture current host memory. Reads total and used (from cgroup or meminfo), computes free, parses swap and reclaimable from meminfo/cgroup.
 				# @returns [Host::Memory | Nil]
 				def capture
 					total = capture_total
@@ -29,15 +31,25 @@ def capture
 					used = capture_used(total)
 					used = 0 if used.nil? || used.negative?
 					used = [used, total].min
-					free = total - used
 
 					swap_total, swap_used = capture_swap
+					reclaimable = capture_reclaimable
 
-					return Host::Memory.new(total, used, free, swap_total, swap_used)
+					return Host::Memory.new(total, used, swap_total, swap_used, reclaimable)
 				end
 
 				private
 
+				# Path for cgroups v2 (unified): e.g. /sys/fs/cgroup/memory.stat
+				def cgroup_v2_path(name)
+					"#{@cgroup_root}/#{name}"
+				end
+				
+				# Path for cgroups v1 (memory controller): e.g. /sys/fs/cgroup/memory/memory.stat
+				def cgroup_v1_path(name)
+					"#{@cgroup_root}/memory/#{name}"
+				end
+				
 				# Memoized /proc/meminfo contents. Used for total (MemTotal), used (via MemAvailable), and swap when not in a cgroup.
 				# @returns [String | Nil]
 				def meminfo
@@ -51,13 +63,13 @@ def meminfo
 				# 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
+					if File.exist?(cgroup_v2_path("memory.max"))
+						limit = File.read(cgroup_v2_path("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
+					if File.exist?(cgroup_v1_path("memory.limit_in_bytes"))
+						limit = File.read(cgroup_v1_path("memory.limit_in_bytes")).strip.to_i
 						return limit if limit > 0 && limit < CGROUP_V1_UNLIMITED_THRESHOLD
 					end
 
@@ -78,15 +90,15 @@ def capture_total
 				# @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
+					if File.exist?(cgroup_v2_path("memory.current"))
+						current = File.read(cgroup_v2_path("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 File.exist?(cgroup_v1_path("memory.usage_in_bytes"))
+						limit = File.read(cgroup_v1_path("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
+							return File.read(cgroup_v1_path("memory.usage_in_bytes")).strip.to_i
 						end
 					end
 
@@ -115,6 +127,37 @@ def capture_swap
 
 					return swap_total_bytes, swap_used_bytes
 				end
+				
+				# Reclaimable memory in bytes (page cache, buffers, reclaimable slab). Included in used_size.
+				# From cgroups v2 memory.stat "file", cgroups v1 memory.stat "cache", or meminfo Cached + Buffers + SReclaimable.
+				# @returns [Integer | Nil]
+				def capture_reclaimable
+					if File.exist?(cgroup_v2_path("memory.stat"))
+						# cgroups v2: "file" is file-backed (page cache), in bytes
+						content = File.read(cgroup_v2_path("memory.stat")) rescue nil
+						if content && (m = content.match(/^file\s+(\d+)/m))
+							return m[1].to_i
+						end
+					end
+					
+					if File.exist?(cgroup_v1_path("memory.stat"))
+						# cgroups v1: "cache" is page cache, in bytes
+						content = File.read(cgroup_v1_path("memory.stat")) rescue nil
+						if content && (m = content.match(/^cache\s+(\d+)/m))
+							return m[1].to_i
+						end
+					end
+					
+					# meminfo: Cached + Buffers + SReclaimable (kB)
+					unless meminfo_content = self.meminfo
+						return nil
+					end
+					cached_kb = meminfo_content[/Cached:\s*(\d+)\s*kB/, 1]&.to_i || 0
+					buffers_kb = meminfo_content[/Buffers:\s*(\d+)\s*kB/, 1]&.to_i || 0
+					sreclaimable_kb = meminfo_content[/SReclaimable:\s*(\d+)\s*kB/, 1]&.to_i || 0
+					reclaimable_kb = cached_kb + buffers_kb + sreclaimable_kb
+					return reclaimable_kb * 1024
+				end
 			end
 		end
 	end

test/process/host/memory.rb

@@ -3,6 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2025-2026, by Samuel Williams.
 
+require "tmpdir"
 require "process/metrics"
 
 describe Process::Metrics::Host::Memory do
@@ -29,12 +30,22 @@
 			end
 		end
 
+		it "may include reclaimable_size (Linux: page cache etc., included in used_size)" do
+			host = Process::Metrics::Host::Memory.capture
+			skip "Host::Memory is not available on this platform" unless host
+			if host.reclaimable_size != nil
+				expect(host.reclaimable_size).to be_a(Integer)
+				expect(host.reclaimable_size).to be >= 0
+				expect(host.reclaimable_size).to be <= host.used_size
+			end
+		end
+		
 		it "serializes to JSON" do
 			host = Process::Metrics::Host::Memory.capture
 			skip "Host::Memory is not available on this platform" unless host
 			json = host.to_json
 			parsed = JSON.parse(json)
-			expect(parsed).to have_keys("total_size", "used_size", "free_size")
+			expect(parsed).to have_keys("total_size", "used_size", "free_size", "available_size", "reclaimable_size")
 		end
 	end
 
@@ -46,3 +57,27 @@
 		end
 	end
 end
+
+if defined?(Process::Metrics::Host::Memory::Linux)
+	describe Process::Metrics::Host::Memory::Linux do
+		with "fake cgroup_root" do
+			it "reads total_size, used_size, reclaimable_size from fake cgroup v2 files" do
+				skip "Only runs on Linux" unless RUBY_PLATFORM.include?("linux")
+				Dir.mktmpdir do |dir|
+					total_bytes = 1_073_741_824
+					used_bytes = 800_000_000
+					file_reclaimable_bytes = 123_456_789
+					File.write(File.join(dir, "memory.max"), total_bytes.to_s)
+					File.write(File.join(dir, "memory.current"), used_bytes.to_s)
+					File.write(File.join(dir, "memory.stat"), "anon 0\nfile #{file_reclaimable_bytes}\nkernel 0\n")
+					host = Process::Metrics::Host::Memory::Linux.new(cgroup_root: dir).capture
+					expect(host).to be_a(Process::Metrics::Host::Memory)
+					expect(host.total_size).to be == total_bytes
+					expect(host.used_size).to be == used_bytes
+					expect(host.free_size).to be == total_bytes - used_bytes
+					expect(host.reclaimable_size).to be == file_reclaimable_bytes
+				end
+			end
+		end
+	end
+end