Add support for page faults.

Author: ioquatix

examples/cow.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# A small demo to visualize COW-related minor page fault trends.
+# - Allocates page-sized strings in an array.
+# - Forks a child that mutates one byte of a different string each second.
+# - Parent samples Process::Metrics and prints minor/major fault deltas and unique memory growth.
+
+require "process/metrics"
+
+PAGE_SIZE = Integer(ENV.fetch("PAGE_SIZE", "4096")) # bytes
+PAGES     = Integer(ENV.fetch("PAGES", "128"))      # number of page-sized strings
+DURATION  = Integer(ENV.fetch("DURATION", "30"))    # seconds to run/monitor
+
+# Allocate an array of page-sized mutable strings:
+array = Array.new(PAGES) {"\x00" * PAGE_SIZE}
+
+child_pid = fork do
+	$0 = "cow-child"
+	i = 0
+	start = Time.now
+	while (Time.now - start) < DURATION
+		idx = i % PAGES
+		s = array[idx]
+		# Mutate a single byte; this should trigger a COW on the underlying page on first write:
+		s.setbyte(0, (s.getbyte(0) + 1) & 0xFF)
+		i += 1
+		sleep 1
+	end
+end
+
+puts "Monitoring child PID=#{child_pid} for #{DURATION}s (PAGE_SIZE=#{PAGE_SIZE}, PAGES=#{PAGES})"
+
+last_minor = nil
+last_major = nil
+last_unique = nil
+
+DURATION.times do |t|
+	procs = Process::Metrics::General.capture(pid: child_pid)
+	proc = procs[child_pid]
+	unless proc
+		puts "[%2ds] child process is no longer listed" % t
+		break
+	end
+	mem = proc.memory
+	unless mem
+		puts "[%2ds] detailed memory metrics not available on this platform" % t
+		break
+	end
+	
+	minor = mem.minor_faults.to_i
+	major = mem.major_faults.to_i
+	unique = mem.unique_size.to_i          # kB
+	
+	delta_minor = last_minor ? (minor - last_minor) : 0
+	delta_major = last_major ? (major - last_major) : 0
+	delta_unique = last_unique ? (unique - last_unique) : 0
+	
+	puts "[%2ds] minor: %d (+%d), major: %d (+%d), unique_kB: %d (+%d)" % [t, minor, delta_minor, major, delta_major, unique, delta_unique]
+	
+	last_minor = minor
+	last_major = major
+	last_unique = unique
+	
+	sleep 1
+end
+
+begin
+	Process.kill(:TERM, child_pid)
+rescue Errno::ESRCH
+	# already exited
+end
+
+begin
+	_, status = Process.wait2(child_pid)
+	if status
+		if status.signaled?
+			puts "Child terminated by signal #{status.termsig}"
+		else
+			puts "Child exited with status #{status.exitstatus}"
+		end
+	end
+rescue Errno::ECHILD
+	# already reaped
+end

lib/process/metrics/memory.rb

@@ -8,7 +8,7 @@
 module Process
 	module Metrics
 		# Represents memory usage for a process, sizes are in kilobytes.
-		class Memory < Struct.new(:map_count, :resident_size, :proportional_size, :shared_clean_size, :shared_dirty_size, :private_clean_size, :private_dirty_size, :referenced_size, :anonymous_size, :swap_size, :proportional_swap_size)
+		class Memory < Struct.new(:map_count, :resident_size, :proportional_size, :shared_clean_size, :shared_dirty_size, :private_clean_size, :private_dirty_size, :referenced_size, :anonymous_size, :swap_size, :proportional_swap_size, :minor_faults, :major_faults)
 
 			alias as_json to_h
 
@@ -28,7 +28,7 @@ def unique_size
 			end
 
 			def self.zero
-				self.new(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
+				self.new(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
 			end
 
 			# Whether the memory usage can be captured on this system.

lib/process/metrics/memory/linux.rb

@@ -6,6 +6,24 @@
 module Process
 	module Metrics
 		class Memory::Linux
+			# Extract minor/major page fault counters from /proc/[pid]/stat and assign to usage.
+			def self.capture_faults(pid, usage)
+				begin
+					stat = 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+/)
+					# 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
+				rescue Errno::ENOENT, Errno::EACCES
+					# The process may have exited or permissions are insufficient; ignore.
+				rescue => error
+					# Be robust to unexpected formats; ignore errors silently.
+				end
+			end
+			
 			# @returns [Numeric] Total memory size in kilobytes.
 			def self.total_size
 				File.read("/proc/meminfo").each_line do |line|
@@ -49,6 +67,8 @@ def self.capture(pid, **options)
 						end
 
 						usage.map_count += File.readlines("/proc/#{pid}/maps").size
+						# Also capture fault counters:
+						self.capture_faults(pid, usage)
 					rescue Errno::ENOENT => error
 						# Ignore.
 					end
@@ -79,6 +99,8 @@ def self.capture(pid, **options)
 								usage.map_count += 1
 							end
 						end
+						# Also capture fault counters:
+						self.capture_faults(pid, usage)
 					rescue Errno::ENOENT => error
 						# Ignore.
 					end

releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## Unreleased
+
+  - Add support for major and minor page faults on Linux: `Process::Metrics::Memory#major_faults` and `#minor_faults`. Unfortunately these metrics are not available on Darwin (macOS).
+
 ## v0.5.1
 
   - Fixed Linux memory usage capture to correctly read memory statistics.

test/process/memory.rb

@@ -33,7 +33,9 @@
 				referenced_size: be >= 0,
 				anonymous_size: be >= 0,
 				swap_size: be >= 0,
-				proportional_swap_size: be >= 0
+				proportional_swap_size: be >= 0,
+				minor_faults: be >= 0,
+				major_faults: be >= 0
 			)
 		end
 
@@ -46,7 +48,7 @@
 			json = JSON.parse(json_string)
 
 			expect(json).to have_keys(
-				"map_count", "resident_size", "proportional_size", "shared_clean_size", "shared_dirty_size", "private_clean_size", "private_dirty_size", "referenced_size", "anonymous_size", "swap_size", "proportional_swap_size"
+				"map_count", "resident_size", "proportional_size", "shared_clean_size", "shared_dirty_size", "private_clean_size", "private_dirty_size", "referenced_size", "anonymous_size", "swap_size", "proportional_swap_size", "minor_faults", "major_faults"
 			)
 		end
 	end