process-metrics 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 290184074b5b6558048bda94e92bc192afe72cac005834ea36a12814048d91bc
-  data.tar.gz: '079bf8f07d0ea7705c366008d99cb2fe20511d130e98b273d28c8384d877e40d'
+  metadata.gz: ca29ce7e69894dd4f9f766caa5ee6055c1a25c06d1b764960ffe72c15dfb1958
+  data.tar.gz: 4723276718e25bc09053ba004357f33a720d3da342b384277f07b5a3eebe898e
 SHA512:
-  metadata.gz: 2029110f30b0993f1c1e30113c391e005b516a8ab7a0a5e945e7629470a4c6659772b370ed5d350667be164a7a216049d5d97ecae60d2809133bd39635dac45e
-  data.tar.gz: 3f1f223f289c74f15f8e15ce333ee998afcbc671270003420ba1e0b698abadb22647fc5a655125c0da098d45c0cba48d0e401eb6f14abc6e600605ab90486210
+  metadata.gz: b6548743e1120c91c17cf5aa6255bb14991c68ac7b28861325ea3376061e7a3da18f4d1bfc7762f83eb48e46f2e1ce792e1550e3fc16cae13254f5c8189e9650
+  data.tar.gz: 53cbcbabaef2f8d414e877eeb5b3d1dbc286f87cbb01ce4a6afee588527440e94c9ea144af4e13d5bb7f085971b2da91f373684bbc8076980cafe02c6aa8f7f6

data/lib/process/metrics/command/summary.rb

@@ -12,6 +12,7 @@ require "console/terminal"
 module Process
 	module Metrics
 		module Command
+			# Helper module for rendering horizontal progress bars using Unicode block characters.
 			module Bar
 				BLOCK = [
 					" ",
@@ -25,6 +26,10 @@ module Process
 					"█",
 				]
 				
+				# Format a fractional value as a horizontal bar.
+				# @parameter value [Float] A value between 0.0 and 1.0 representing the fill level.
+				# @parameter width [Integer] The width of the bar in characters.
+				# @returns [String] A string of Unicode block characters representing the filled bar.
 				def self.format(value, width)
 					blocks = width * value
 					full_blocks = blocks.floor
@@ -38,6 +43,7 @@ module Process
 				end
 			end
 			
+			# Command that displays a formatted summary of memory usage statistics for processes.
 			class Summary < Samovar::Command
 				self.description = "Display a summary of memory usage statistics."
 				
@@ -48,6 +54,8 @@ module Process
 					option "--total-memory <integer>", "Set the total memory relative to the usage (MiB).", type: Integer
 				end
 				
+				# Get the configured terminal for styled output.
+				# @returns [Console::Terminal] A terminal object with color/style definitions.
 				def terminal
 					terminal = Console::Terminal.for($stdout)
 					
@@ -62,6 +70,9 @@ module Process
 					return terminal
 				end
 				
+				# Format a processor utilization percentage with color-coded bar.
+				# @parameter value [Float] The CPU utilization percentage (0.0-100.0).
+				# @parameter terminal [Console::Terminal] The terminal to output styled text.
 				def format_processor_utilization(value, terminal)
 					if value > 80.0
 						intensity = :high
@@ -78,6 +89,10 @@ module Process
 				
 				UNITS = ["KiB", "MiB", "GiB"]
 				
+				# Format a memory size value in human-readable units.
+				# @parameter value [Numeric] The size value in kilobytes.
+				# @parameter units [Array(String)] The unit labels to use for scaling.
+				# @returns [String] A formatted string with value and unit (e.g., "512KiB", "1.5MiB").
 				def format_size(value, units: UNITS)
 					unit = 0
 					
@@ -89,6 +104,10 @@ module Process
 					return "#{value.round(unit)}#{units[unit]}"
 				end
 				
+				# Format a memory value with a horizontal bar showing utilization relative to total.
+				# @parameter value [Numeric] The memory value in kilobytes.
+				# @parameter total [Numeric] The total memory available in kilobytes.
+				# @parameter terminal [Console::Terminal] The terminal to output styled text.
 				def format_memory(value, total, terminal)
 					if value > (total * 0.8)
 						intensity = :high
@@ -103,6 +122,8 @@ module Process
 					terminal.print(formatted, intensity, "[", Bar.format(value / total.to_f, 60), "]", :reset)
 				end
 				
+				# Get the total memory to use for percentage calculations.
+				# @returns [Integer] Total memory in kilobytes.
 				def total_memory
 					if total_memory = @options[:total_memory]
 						return total_memory * 1024
@@ -111,6 +132,7 @@ module Process
 					end
 				end
 				
+				# Execute the summary command, capturing and displaying process metrics.
 				def call
 					# Validate required arguments: at least one of --pid or --ppid must be provided:
 					unless @options[:pid] || @options[:ppid]

data/lib/process/metrics/command/top.rb

@@ -11,6 +11,7 @@ require_relative "../version"
 module Process
 	module Metrics
 		module Command
+			# Top-level command entry point for the process-metrics CLI.
 			class Top < Samovar::Command
 				self.description = "Collect memory usage statistics."
 				
@@ -23,6 +24,7 @@ module Process
 					"summary" => Summary,
 				}, default: "summary"
 				
+				# Execute the top command, dispatching to nested commands.
 				def call
 					if @options[:version]
 						puts "#{self.name} v#{VERSION}"

data/lib/process/metrics/command.rb

@@ -7,7 +7,10 @@ require_relative "command/top"
 
 module Process
 	module Metrics
+		# @namespace
 		module Command
+			# Call the default command (Top).
+			# @parameter arguments [Array] Command-line arguments to pass through.
 			def self.call(*arguments)
 				Top.call(*arguments)
 			end

data/lib/process/metrics/general.rb

@@ -84,12 +84,20 @@ module Process
 			
 			alias memory_usage total_size
 			
+			# Recursively expand a set of child PIDs into a collection.
+			# @parameter children [Array<Integer>] The list of child process IDs to expand.
+			# @parameter hierarchy [Hash<Integer, Array<Integer>>] The parent-to-children process hierarchy.
+			# @parameter pids [Set<Integer>] The set to populate with process IDs.
 			def self.expand_children(children, hierarchy, pids)
 				children.each do |pid|
 					self.expand(pid, hierarchy, pids)
 				end
 			end
 			
+			# Recursively expand a process and its descendants into a collection.
+			# @parameter pid [Integer] The process ID to expand.
+			# @parameter hierarchy [Hash<Integer, Array<Integer>>] The parent-to-children process hierarchy.
+			# @parameter pids [Set<Integer>] The set to populate with process IDs.
 			def self.expand(pid, hierarchy, pids)
 				unless pids.include?(pid)
 					pids << pid
@@ -100,6 +108,9 @@ module Process
 				end
 			end
 			
+			# Build a parent-to-children process hierarchy from a set of processes.
+			# @parameter processes [Hash<Integer, General>] A hash mapping PIDs to General instances.
+			# @returns [Hash<Integer, Array<Integer>>] A hash mapping each parent PID to an array of child PIDs.
 			def self.build_tree(processes)
 				hierarchy = Hash.new{|h,k| h[k] = []}
 				
@@ -112,6 +123,8 @@ module Process
 				return hierarchy
 			end
 			
+			# Capture detailed memory metrics for each process in the given collection.
+			# @parameter processes [Hash<Integer, General>] A hash mapping PIDs to General instances.
 			def self.capture_memory(processes)
 				count = processes.size
 				

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

@@ -5,6 +5,7 @@
 
 module Process
 	module Metrics
+		# Darwin (macOS) implementation of memory metrics using vmmap.
 		class Memory::Darwin
 			VMMAP = "/usr/bin/vmmap"
 			
@@ -25,7 +26,9 @@ module Process
 				end
 			end
 			
-			# Parse a size string into kilobytes.
+			# Parse a size string from vmmap output into kilobytes.
+			# @parameter string [String | Nil] The size string (e.g., "4K", "1.5M", "2G").
+			# @returns [Integer] The size in kilobytes.
 			def self.parse_size(string)
 				return 0 unless string
 				
@@ -93,14 +96,22 @@ module Process
 		
 		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 kilobytes.
 				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

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

@@ -5,7 +5,28 @@
 
 module Process
 	module Metrics
+		# Linux implementation of memory metrics using `/proc/[pid]/smaps` and `/proc/[pid]/stat`.
 		class Memory::Linux
+			# 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.
+			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 +70,8 @@ module Process
 						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 +102,8 @@ module Process
 								usage.map_count += 1
 							end
 						end
+						# Also capture fault counters:
+						self.capture_faults(pid, usage)
 					rescue Errno::ENOENT => error
 						# Ignore.
 					end
@@ -94,14 +119,22 @@ module Process
 		
 		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 kilobytes.
 				def total_size
 					return Memory::Linux.total_size
 				end
 				
+				# Capture memory metrics for a process.
+				# @parameter pid [Integer] The process ID.
+				# @parameter options [Hash] Additional options.
+				# @returns [Memory] A Memory instance with captured metrics.
 				def capture(...)
 					return Memory::Linux.capture(...)
 				end

data/lib/process/metrics/memory.rb

@@ -8,7 +8,7 @@ require "json"
 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
 			
@@ -27,8 +27,10 @@ module Process
 				self.private_clean_size + self.private_dirty_size
 			end
 			
+			# Create a zero-initialized Memory instance.
+			# @returns [Memory] A new Memory object with all fields set to zero.
 			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.

data/lib/process/metrics/version.rb

@@ -3,8 +3,10 @@
 # Released under the MIT License.
 # Copyright, 2019-2025, by Samuel Williams.
 
+# @namespace
 module Process
+	# @namespace
 	module Metrics
-		VERSION = "0.5.2"
+		VERSION = "0.6.0"
 	end
 end

data/readme.md

@@ -16,6 +16,10 @@ 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.6.0
+
+  - 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.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.6.0
+
+  - 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.

data.tar.gz.sig

@@ -1,3 +1,2 @@
-&-�"]�4�s0�:��oϒb�ri�T@�.ޖ
-��X�U�i����yP���?�@o,��r5
-/&CH�&�P��������>'k�vf'$xk&e�ɦ�Gָru���߭�B�n΍D-�ZU�y#c`Ԕ�A*�/���Ru��痴S:~�)rw)/דp��=���R�E� c�H_��/jdX$���A�9��,?6f�Ę�����<+	�BI�Pg����ZxN�T�:֔
���
�Sw�f����Y��~>��}���+#do<�����ҩerV�S��C
+\��1,��5��%��A�F��&|՝\,�J�:����!wA��x��^0`o>��iW�\D|
+�!���i�(�y���B��kJ>*�V��%��Jcy�`�/Uj=���?^��G�.��S���C]�j���ȃ���R%��7�|�VQU�S�p+�/����J+O��&5�4ƺ

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process-metrics
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -122,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Provide detailed OS-specific process metrics.
 test_files: []