process-metrics 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0917ad55068d053da8e6f58943114ab1cc7d2dd7b61969f022c7a373a7212d9
-  data.tar.gz: cff5b81fdad7a03e4c2a843178e5c880c20c68580ef2dd93e9a29b529591ea87
+  metadata.gz: 42d11b0f2e725706c447c1b4cfa3f15a961f759fb8cacf0ef0d238338c3be6ab
+  data.tar.gz: 80468efcb1b3eab151f8fcf0d054d93d11dcd90127ec70a6ad63e5fc10b68f89
 SHA512:
-  metadata.gz: 94617d513a1849da4c48d052e4aa92d7279d07deb0f0710439a19f5c87b17a3c9fd259ea260b9c774130c7a111ed7ff4d4870d58ece51c1d2bff6a5c65ccd939
-  data.tar.gz: 2689b081c6aa85ce0901c97feec76ddb54ef9bd322872f1fc6a76a6bfd14f682a8a80499e094fae8c080f443f36ddfaea61ea90c888a63fdee6f027a0fd5a8ed
+  metadata.gz: 5c765d57991e1a15e8c966ea1497234dae6e8e98cdd8e2463cefe1caf046770b1930b01b68b202b7ace9d802ad6d0577dfbb3cfef48a1d23abc3013ea5a48580
+  data.tar.gz: 8c2bf4692a659037dc8167ad7f3349beb300e4bf021ee97b8ed3bf645cc83eaeefa19ae6ef5aee62855d781f7782ab9750d3999ca21982b865c24afbb65a0be5

data/bin/process-metrics

@@ -21,7 +21,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require_relative '../lib/process/metrics/command'
+require_relative "../lib/process/metrics/command"
 
 begin
 	Process::Metrics::Command.call

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

@@ -1,28 +1,13 @@
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# frozen_string_literal: true
 
-require 'samovar'
+# Released under the MIT License.
+# Copyright, 2020-2025, by Samuel Williams.
 
-require_relative '../general'
+require "samovar"
 
-require 'console/terminal'
+require_relative "../general"
+
+require "console/terminal"
 
 module Process
 	module Metrics
@@ -57,10 +42,8 @@ module Process
 				self.description = "Display a summary of memory usage statistics."
 				
 				options do
-					option '--pid <integer>', "Report on a single process id.", type: Integer, required: true
-					option '-p/--ppid <integer>', "Report on all children of this process id.", type: Integer, required: true
-					
-					option '--memory-scale <integer>', "Scale maximum memory usage to the specified amount (MiB).", type: Integer, default: 512
+					option "--pid <integer>", "Report on a single process id.", type: Integer, required: true
+					option "-p/--ppid <integer>", "Report on all children of this process id.", type: Integer, required: true
 				end
 				
 				def terminal
@@ -77,7 +60,7 @@ module Process
 					return terminal
 				end
 				
-				def format_pcpu(value, terminal)
+				def format_processor_utilization(value, terminal)
 					if value > 80.0
 						intensity = :high
 					elsif value > 50.0
@@ -104,18 +87,18 @@ module Process
 					return "#{value.round(unit)}#{units[unit]}"
 				end
 				
-				def format_memory_usage(value, terminal, scale: @options[:memory_scale])
-					if value > (1024.0 * scale * 0.8)
+				def format_memory_usage(value, total, terminal)
+					if value > (total * 0.8)
 						intensity = :high
-					elsif value > (1024.0 * scale * 0.5)
+					elsif value > (total * 0.5)
 						intensity = :medium
 					else
 						intensity = :low
 					end
 					
-					formatted = (format_size(value) + ' ').rjust(10)
+					formatted = (format_size(value) + " ").rjust(10)
 					
-					terminal.print(formatted, intensity, "[", Bar.format(value / (1024.0 * scale), 60), "]", :reset)
+					terminal.print(formatted, intensity, "[", Bar.format(value / total.to_f, 60), "]", :reset)
 				end
 				
 				def call
@@ -124,35 +107,47 @@ module Process
 					summary = Process::Metrics::General.capture(pid: @options[:pid], ppid: @options[:ppid])
 					
 					format_memory_usage = self.method(:format_memory_usage).curry
-					memory_usage = 0
+					shared_memory_usage = 0
+					private_memory_usage = 0
+					total_memory_usage = 0
+					
+					summary.each do |pid, general|
+						if memory = general.memory
+							total_memory_usage += memory.proportional_size + memory.unique_size
+						else
+							total_memory_usage += general.resident_size
+						end
+					end
+					
 					proportional = true
 					
 					summary.each do |pid, general|
 						terminal.print_line(:pid, pid, :reset, " ", :command, general[:command])
 						
 						terminal.print(:key, "Processor Usage: ".rjust(20), :reset)
-						format_pcpu(general.pcpu, terminal)
+						format_processor_utilization(general.processor_utilization, terminal)
 						terminal.print_line
 						
 						if memory = general.memory
-							memory_usage += memory.proportional_size
+							shared_memory_usage += memory.proportional_size
+							private_memory_usage += memory.unique_size
 							
 							terminal.print_line(
-								:key, "Memory (PSS): ".rjust(20), :reset,
-								format_memory_usage[memory.proportional_size]
+								:key, "Shared Memory: ".rjust(20), :reset,
+								format_memory_usage[memory.proportional_size, total_memory_usage]
 							)
 							
 							terminal.print_line(
-								:key, "Private (USS): ".rjust(20), :reset,
-								format_memory_usage[memory.unique_size]
+								:key, "Private Memory: ".rjust(20), :reset,
+								format_memory_usage[memory.unique_size, total_memory_usage]
 							)
 						else
-							memory_usage += general.rss
+							shared_memory_usage += general.resident_size
 							proportional = false
 							
 							terminal.print_line(
-								:key, "Memory (RSS): ".rjust(20), :reset,
-								format_memory_usage[general.rss]
+								:key, "Memory: ".rjust(20), :reset,
+								format_memory_usage[general.resident_size, total_memory_usage]
 							)
 						end
 					end
@@ -161,15 +156,25 @@ module Process
 					
 					if proportional
 						terminal.print_line(
-							:key, "Memory (PSS): ".rjust(20), :reset,
-							format_memory_usage[memory_usage]
+							:key, "Shared Memory: ".rjust(20), :reset,
+							format_memory_usage[shared_memory_usage, total_memory_usage]
+						)
+						
+						terminal.print_line(
+							:key, "Private Memory: ".rjust(20), :reset,
+							format_memory_usage[private_memory_usage, total_memory_usage]
 						)
 					else
 						terminal.print_line(
-							:key, "Memory (RSS): ".rjust(20), :reset,
-							format_memory_usage[memory_usage]
+							:key, "Memory: ".rjust(20), :reset,
+							format_memory_usage[memory_usage, total_memory_usage]
 						)
 					end
+					
+					terminal.print_line(
+						:key, "Memory (Total): ".rjust(20), :reset,
+						format_memory_usage[shared_memory_usage + private_memory_usage, total_memory_usage]
+					)
 				end
 			end
 		end

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

@@ -1,27 +1,12 @@
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# frozen_string_literal: true
 
-require 'samovar'
+# Released under the MIT License.
+# Copyright, 2020-2025, by Samuel Williams.
 
-require_relative 'summary'
-require_relative '../version'
+require "samovar"
+
+require_relative "summary"
+require_relative "../version"
 
 module Process
 	module Metrics
@@ -30,13 +15,13 @@ module Process
 				self.description = "Collect memory usage statistics."
 				
 				options do
-					option '-h/--help', "Print out help information."
-					option '-v/--version', "Print out the application version."
+					option "-h/--help", "Print out help information."
+					option "-v/--version", "Print out the application version."
 				end
 				
 				nested :command, {
-					'summary' => Summary,
-				}, default: 'summary'
+					"summary" => Summary,
+				}, default: "summary"
 				
 				def call
 					if @options[:version]

data/lib/process/metrics/command.rb

@@ -1,24 +1,9 @@
-# Copyright, 2017, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# frozen_string_literal: true
 
-require_relative 'command/top'
+# Released under the MIT License.
+# Copyright, 2020-2025, by Samuel Williams.
+
+require_relative "command/top"
 
 module Process
 	module Metrics

data/lib/process/metrics/general.rb

@@ -1,87 +1,89 @@
 # frozen_string_literal: true
 
-# Copyright, 2019, by Samuel G. D. Williams. <https://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# Released under the MIT License.
+# Copyright, 2019-2025, by Samuel Williams.
 
-require_relative 'memory'
-require 'set'
+require_relative "memory"
+require "set"
+require "json"
 
 module Process
 	module Metrics
 		PS = "ps"
 		
+		DURATION = /\A
+			(?:(?<days>\d+)-)?              # Optional days (e.g., '2-')
+			(?:(?<hours>\d+):)?             # Optional hours (e.g., '1:')
+			(?<minutes>\d{1,2}):            # Minutes (always present, 1 or 2 digits)
+			(?<seconds>\d{2})               # Seconds (exactly 2 digits)
+			(?:\.(?<fraction>\d{1,2}))?     # Optional fraction of a second (e.g., '.27')
+		\z/x
+		
+		
+		# Parse a duration string into seconds.
 		# According to the linux manual page specifications.
 		def self.duration(value)
-			if /((?<days>\d\d)\-)?((?<hours>\d\d):)?(?<minutes>\d\d):(?<seconds>\d\d)?/ =~ value
-				(((days&.to_i || 0) * 24 + (hours&.to_i || 0)) * 60 + (minutes&.to_i || 0)) * 60 + seconds&.to_i
+			if match = DURATION.match(value)
+				days = match[:days].to_i
+				hours = match[:hours].to_i
+				minutes = match[:minutes].to_i
+				seconds = match[:seconds].to_i
+				fraction = match[:fraction].to_i
+				
+				return days * 24 * 60 * 60 + hours * 60 * 60 + minutes * 60 + seconds + fraction / 100.0
+			else
+				return 0.0
 			end
 		end
 		
-		# pid: Process Identifier
-		# pmem: Percentage Memory used.
-		# pcpu: Percentage Processor used.
-		# time: The process time used (executing on CPU).
-		# vsz: Virtual Size in kilobytes
-		# rss: Resident Set Size in kilobytes
-		# etime: The process elapsed time.
-		# command: The name of the process.
+		# The fields that will be extracted from the `ps` command.
 		FIELDS = {
-			pid: ->(value){value.to_i},
-			ppid: ->(value){value.to_i},
-			pgid: ->(value){value.to_i},
-			pcpu: ->(value){value.to_f},
-			time: self.method(:duration),
-			vsz: ->(value){value.to_i},
-			rss: ->(value){value.to_i},
-			etime: self.method(:duration),
-			command: ->(value){value},
+			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}, # Virtual Size (KiB)
+			rss: ->(value){value.to_i}, # Resident Size (KiB)
+			time: self.method(:duration), # CPU Time (seconds)
+			etime: self.method(:duration), # Elapsed Time (seconds)
+			command: ->(value){value}, # Command (name of the process)
 		}
 		
-		class General < Struct.new(:pid, :ppid, :pgid, :pcpu, :vsz, :rss, :time, :etime, :command, :memory)
+		# 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.
 			def as_json
 				{
-					pid: self.pid,
-					ppid: self.ppid,
-					pgid: self.pgid,
-					pcpu: self.pcpu,
-					vsz: self.vsz,
-					rss: self.rss,
-					time: self.time,
-					etime: self.etime,
+					process_id: self.process_id,
+					parent_process_id: self.parent_process_id,
+					process_group_id: self.process_group_id,
+					processor_utilization: self.processor_utilization,
+					total_size: self.total_size,
+					virtual_size: self.virtual_size,
+					resident_size: self.resident_size,
+					processor_time: self.processor_time,
+					elapsed_time: self.elapsed_time,
 					command: self.command,
 					memory: self.memory&.as_json,
 				}
 			end
 			
+			# Convert the object to a JSON string.
 			def to_json(*arguments)
 				as_json.to_json(*arguments)
 			end
 			
-			def memory_usage
-				if self.memory
-					self.memory.proportional_size
+			# The total size of the process in memory, in kilobytes.
+			def total_size
+				if memory = self.memory
+					memory.proportional_size
 				else
-					self.rss
+					self.resident_size
 				end
 			end
 			
+			alias memory_usage total_size
+			
 			def self.expand_children(children, hierarchy, pids)
 				children.each do |pid|
 					self.expand(pid, hierarchy, pids)
@@ -102,8 +104,8 @@ module Process
 				hierarchy = Hash.new{|h,k| h[k] = []}
 				
 				processes.each_value do |process|
-					if ppid = process.ppid
-						hierarchy[ppid] << process.pid
+					if parent_process_id = process.parent_process_id
+						hierarchy[parent_process_id] << process.process_id
 					end
 				end
 				
@@ -116,18 +118,22 @@ module Process
 				end
 			end
 			
-			def self.capture(pid: nil, ppid: nil, ps: PS, fields: FIELDS)
+			# 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, ps: PS, memory: Memory.supported?)
 				input, output = IO.pipe
 				
 				arguments = [ps]
 				
 				if pid && ppid.nil?
-					arguments.push("-p", Array(pid).join(','))
+					arguments.push("-p", Array(pid).join(","))
 				else
 					arguments.push("ax")
 				end
 				
-				arguments.push("-o", fields.keys.join(','))
+				arguments.push("-o", FIELDS.keys.join(","))
 				
 				ps_pid = Process.spawn(*arguments, out: output, pgroup: true)
 				
@@ -138,13 +144,12 @@ module Process
 				processes = {}
 				
 				lines.map do |line|
-					record = fields.
-						zip(line.split(/\s+/, fields.size)).
+					record = FIELDS.
+						zip(line.split(/\s+/, FIELDS.size)).
 						map{|(key, type), value| type.call(value)}
-					
 					instance = self.new(*record)
 					
-					processes[instance.pid] = instance
+					processes[instance.process_id] = instance
 				end
 				
 				if ppid
@@ -162,12 +167,8 @@ module Process
 					end
 				end
 				
-				if Memory.supported?
+				if memory
 					self.capture_memory(processes)
-					
-					# if pid
-					# 	self.compute_summary(pid, processes)
-					# end
 				end
 				
 				return processes

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Process
+	module Metrics
+		class Memory::Darwin
+			VMMAP = "/usr/bin/vmmap"
+			
+			# Whether the memory usage can be captured on this system.
+			def self.supported?
+				File.executable?(VMMAP)
+			end
+			
+			# Parse a size string into kilobytes.
+			def self.parse_size(string)
+				return 0 unless string
+				
+				case string.strip
+				when /([\d\.]+)K/i then ($1.to_f).round
+				when /([\d\.]+)M/i then ($1.to_f * 1024).round
+				when /([\d\.]+)G/i then ($1.to_f * 1024 * 1024).round
+				else (string.to_f / 1024).ceil
+				end
+			end
+			
+			LINE = /\A
+				\s*
+				(?<region_name>.+?)\s+
+				(?<start_address>[0-9a-fA-F]+)-(?<end_address>[0-9a-fA-F]+)\s+
+				\[\s*(?<virtual_size>[\d\.]+[KMG]?)\s+(?<resident_size>[\d\.]+[KMG]?)\s+(?<dirty_size>[\d\.]+[KMG]?)\s+(?<swap_size>[\d\.]+[KMG]?)\s*\]\s+
+				(?<permissions>[rwx\-\/]+)\s+
+				SM=(?<sharing_mode>\w+)
+			/x
+			
+			# Capture memory usage for the given process IDs.
+			def self.capture(pids)
+				usage = Memory.zero
+				
+				pids.each do |pid|
+					IO.popen(["vmmap", pid.to_s], "r") do |io|
+						io.each_line do |line|
+							if match = LINE.match(line)
+								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])
+								
+								# puts [match[:region_name], virtual_size, resident_size, dirty_size, swap_size, match[:permissions], match[:sharing_mode]].join(",")
+								
+								# Update counts
+								usage.map_count += 1
+								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
+								case match[:sharing_mode]
+								when "PRV"
+									usage.private_clean_size += resident_size - dirty_size
+									usage.private_dirty_size += dirty_size
+								when "COW", "SHM"
+									usage.shared_clean_size += resident_size - dirty_size
+									usage.shared_dirty_size += dirty_size
+								end
+								
+								# Anonymous memory: no region detail path or special names
+								if match[:region_name] =~ /MALLOC|VM_ALLOCATE|Stack|STACK|anonymous/
+									usage.anonymous_size += resident_size
+								end
+								# else
+								# 	puts "Failed to match line: #{line}"
+							end
+						end
+					end
+				end
+				
+				# On Darwin, we cannot compute the proportional size, so we just set it to the resident size.
+				usage.proportional_size = usage.resident_size
+				usage.proportional_swap_size = usage.swap_size
+				
+				return usage
+			end
+		end
+		
+		if Memory::Darwin.supported?
+			class << Memory
+				def supported?
+					return true
+				end
+				
+				def capture(pids)
+					return Memory::Darwin.capture(pids)
+				end
+			end
+		end
+	end
+end