process-metrics 0.11.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbf463af0812bd192ef672f02852cc6142e4ec07ce54e9101561e236848a9339
-  data.tar.gz: debc60440d79a2a745ea287e129f22b4a72fbf4b608a8903aafb95a3204b9b38
+  metadata.gz: 2822c0b3ad1a6e79d294cc8607359b1a8042818a8b07306c5685064addd4b7fd
+  data.tar.gz: f945a7b3bcf467f696c9823a11ecefa996aae3f7e9d075bcfcd6bba87edd13d1
 SHA512:
-  metadata.gz: f5b9a378cb31b094f83e180696df41dc7c1cc46f7df1e7af782e9883b07ef1e4d4e0007eab9a90a4526e55f794a9d697a5a5033024ea165392ba2ad6af4face0
-  data.tar.gz: '0281fd18c13ccc1d5a1bc4092b242209185ef38239b227b350dca21d780b912ca5fcacbc81a30ae819bfe4e37972494c7fb432e899887a1c0453973fed6fed87'
+  metadata.gz: 5869ec2e258caad4625fc45f9ee572ebbf9803592f0b8ed1115e80a5f21ad7b36acc3122c9d17aa5c8816c33d76bc4393c3d6620f2ec15f44e065701168ee952
+  data.tar.gz: 7b0a434ceba0c1b0d89297825a5bde80999542e10060e5aa89bafc34e44529e75323ad5de3b3ad792e7bdaee87856e64111ba209026e597203eeed8c6ca3aad9

data/context/getting-started.md

@@ -21,6 +21,7 @@ $ gem install process-metrics
 The `process-metrics` gem provides a simple interface to collect and analyze process metrics.
 
 - {ruby Process::Metrics::General} is the main entry point for process metrics. Use {ruby Process::Metrics::General.capture} to collect metrics for one or more processes.
+- {ruby Process::Metrics::Processor} measures processor utilization over intervals between samples.
 - {ruby Process::Metrics::Memory} provides additional methods for collecting memory metrics when the host operating system provides the necessary information.
 
 ## Usage
@@ -67,7 +68,7 @@ The {ruby Process::Metrics::General} struct contains the following fields:
 - `process_id` - Process ID, a unique identifier for the process.
 - `parent_process_id` - Parent Process ID, the process ID of the process that started this process.
 - `process_group_id` - Process Group ID, the process group ID of the process, which can be shared by multiple processes.
-- `processor_utilization` - Processor Utilization (%), the percentage of CPU time used by the process (over a system-specific duration).
+- `processor_utilization` - Average processor utilization in core units over the system's observation period. `1.0` represents one fully occupied CPU core, and multi-threaded processes can exceed `1.0`.
 - `total_size` - Memory Size (bytes), the total size of the process's memory space (usually over-estimated as it doesn't take into account shared memory).
 - `resident_size` - Resident (Set) Size (bytes), the amount of physical memory used by the process.
 - `processor_time` - CPU Time (s), the amount of CPU time used by the process.
@@ -89,3 +90,25 @@ The {ruby Process::Metrics::Memory} struct contains the following fields:
 - `proportional_swap_size` - Proportional Swap Memory Size (bytes), the amount of memory that has been swapped to disk, excluding shared memory.
 
 In general, the interpretation of these fields is operating system specific. At best, they provide a rough estimate of the process's memory usage, but you should consult the documentation for your operating system for more details on exactly what each field represents.
+
+## Interval Processor Utilization
+
+The processor utilization reported by {ruby Process::Metrics::General} is a snapshot based on the operating system's observation period. Use {ruby Process::Metrics::Processor} when you need utilization over a specific sampling interval:
+
+``` ruby
+processor = Process::Metrics::Processor.new
+
+# The first sample establishes a baseline:
+processor.sample(Process.pid)
+
+sleep(10)
+sample = processor.sample(Process.pid).fetch(Process.pid)
+
+sample.duration
+# => approximately 10.0
+
+sample.utilization
+# => 1.0 means one fully occupied CPU core during the interval
+```
+
+Both interfaces use the same core-unit scale. A utilization of `0.5` means half of one core on average, while `2.0` means two cores were fully occupied. Utilization is therefore not limited to the range `0.0..1.0`.

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

@@ -18,9 +18,16 @@ module Process
 			# 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
 			
+			# The Unix timestamp when the system booted.
+			BOOT_TIME = if File.readable?("/proc/stat")
+				File.foreach("/proc/stat") do |line|
+					break line.split.last.to_f if line.start_with?("btime ")
+				end
+			end
+			
 			# Whether /proc is available so we can list processes without ps.
 			def self.supported?
-				File.directory?("/proc") && File.readable?("/proc/self/stat")
+				File.directory?("/proc") && File.readable?("/proc/self/stat") && File.readable?("/proc/uptime") && !BOOT_TIME.nil?
 			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.
@@ -38,7 +45,6 @@ module Process
 				end
 				
 				uptime_jiffies = nil
-				
 				processes = {}
 				pids_to_read.each do |pid|
 					stat_path = "/proc/#{pid}/stat"
@@ -56,7 +62,7 @@ module Process
 					process_group_id = fields[2].to_i
 					utime = fields[11].to_i
 					stime = fields[12].to_i
-					starttime = fields[19].to_i
+					start_time = fields[19].to_i
 					virtual_size = fields[20].to_i
 					resident_pages = fields[21].to_i
 					
@@ -65,9 +71,13 @@ module Process
 						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
+					elapsed_time = [(uptime_jiffies - start_time).to_f / CLK_TCK, 0.0].max
+					processor_utilization = if elapsed_time > 0.0
+						processor_time.fdiv(elapsed_time)
+					else
+						0.0
+					end
 					
 					command = read_command(pid, executable_name)
 					
@@ -75,11 +85,12 @@ module Process
 						pid,
 						parent_process_id,
 						process_group_id,
-						0.0, # processor_utilization: would need two samples; not available from single stat read
+						processor_utilization,
 						virtual_size,
 						resident_pages * PAGE_SIZE,
 						processor_time,
 						elapsed_time,
+						BOOT_TIME + start_time.to_f / CLK_TCK,
 						command,
 						nil
 					)

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

@@ -3,6 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
+require "time"
+
 module Process
 	module Metrics
 		# General process information via the process status command (`ps`). Used on non-Linux platforms (e.g. Darwin)
@@ -12,15 +14,16 @@ module Process
 			
 			# 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},
+				pid: ->(values){values.shift.to_i},
+				ppid: ->(values){values.shift.to_i},
+				pgid: ->(values){values.shift.to_i},
+				pcpu: ->(values){values.shift.to_f / 100.0},
+				vsz: ->(values){values.shift.to_i * 1024},
+				rss: ->(values){values.shift.to_i * 1024},
+				time: ->(values){Process::Metrics.duration(values.shift)},
+				etime: ->(values){Process::Metrics.duration(values.shift)},
+				lstart: ->(values){Time.strptime(values.shift(5).join(" "), "%a %b %e %H:%M:%S %Y").to_f},
+				command: ->(values){values.join(" ")},
 			}
 			
 			# Whether process listing via ps is available on this system.
@@ -48,7 +51,7 @@ module Process
 					
 					arguments.push("-o", FIELDS.keys.join(","))
 					
-					spawned_pid = Process.spawn(*arguments, out: output)
+					spawned_pid = Process.spawn({"LC_ALL" => "C"}, *arguments, out: output)
 					output.close
 					
 					input.readlines.map(&:strip)
@@ -71,10 +74,9 @@ module Process
 				lines.each do |line|
 					next if line.empty?
 					
-					values = line.split(/\s+/, FIELDS.size)
-					next if values.size < FIELDS.size
+					values = line.split(/\s+/)
+					record = FIELDS.values.map{|parser| parser.call(values)}
 					
-					record = FIELDS.keys.map.with_index{|key, i| FIELDS[key].call(values[i])}
 					instance = General.new(*record, nil)
 					processes[instance.process_id] = instance
 				end

data/lib/process/metrics/general.rb

@@ -35,7 +35,8 @@ module Process
 		end
 		
 		# 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)
+		# @attribute [Float] The processor utilization in core units, where `1.0` represents one fully occupied CPU core. Multi-threaded processes may report values greater than `1.0`.
+		class General < Struct.new(:process_id, :parent_process_id, :process_group_id, :processor_utilization, :virtual_size, :resident_size, :processor_time, :elapsed_time, :start_time, :command, :memory)
 			# Convert the object to a JSON serializable hash.
 			def as_json
 				{
@@ -48,6 +49,7 @@ module Process
 					resident_size: self.resident_size,
 					processor_time: self.processor_time,
 					elapsed_time: self.elapsed_time,
+					start_time: self.start_time,
 					command: self.command,
 					memory: self.memory&.as_json,
 				}

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

@@ -6,10 +6,14 @@
 module Process
 	module Metrics
 		module Host
+			# Captures host memory limits and usage from a cgroup v1 filesystem.
 			class Memory::Linux::CgroupV1
 				CGROUP_V1_UNLIMITED_THRESHOLD = 2**60
 				DEFAULT_CGROUP_ROOT = "/sys/fs/cgroup"
 				
+				# Whether cgroup v1 memory metrics are available.
+				# @parameter cgroup_root [String | Nil] The root of the cgroup filesystem.
+				# @returns [Boolean] Whether the required cgroup v1 files exist.
 				def self.supported?(cgroup_root = DEFAULT_CGROUP_ROOT)
 					root = (cgroup_root || DEFAULT_CGROUP_ROOT).to_s.chomp("/")
 					
@@ -20,10 +24,14 @@ module Process
 					return false
 				end
 				
+				# Initialize the cgroup v1 memory reader.
+				# @parameter cgroup_root [String | Nil] The root of the cgroup filesystem.
 				def initialize(cgroup_root: nil)
 					@cgroup_root = (cgroup_root || DEFAULT_CGROUP_ROOT).to_s.chomp("/")
 				end
 				
+				# Capture host memory from the cgroup v1 filesystem.
+				# @returns [Host::Memory | Nil] The captured host memory, if the cgroup has a finite limit.
 				def capture
 					total = read_total
 					return nil unless total && total.positive?

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

@@ -6,9 +6,13 @@
 module Process
 	module Metrics
 		module Host
+			# Captures host memory limits and usage from a cgroup v2 filesystem.
 			class Memory::Linux::CgroupV2
 				DEFAULT_CGROUP_ROOT = "/sys/fs/cgroup"
 				
+				# Whether cgroup v2 memory metrics are available.
+				# @parameter cgroup_root [String | Nil] The root of the cgroup filesystem.
+				# @returns [Boolean] Whether the required cgroup v2 files exist.
 				def self.supported?(cgroup_root = DEFAULT_CGROUP_ROOT)
 					root = (cgroup_root || DEFAULT_CGROUP_ROOT).to_s.chomp("/")
 					
@@ -19,10 +23,14 @@ module Process
 					return false
 				end
 				
+				# Initialize the cgroup v2 memory reader.
+				# @parameter cgroup_root [String | Nil] The root of the cgroup filesystem.
 				def initialize(cgroup_root: nil)
 					@cgroup_root = (cgroup_root || DEFAULT_CGROUP_ROOT).to_s.chomp("/")
 				end
 				
+				# Capture host memory from the cgroup v2 filesystem.
+				# @returns [Host::Memory | Nil] The captured host memory, if the cgroup has a finite limit.
 				def capture
 					total = read_total
 					return nil unless total && total.positive?

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

@@ -6,11 +6,16 @@
 module Process
 	module Metrics
 		module Host
+			# Captures host memory from Linux `/proc/meminfo`.
 			class Memory::Linux::Meminfo
+				# Whether `/proc/meminfo` is available.
+				# @returns [Boolean] Whether the procfs memory information exists.
 				def self.supported?
 					File.exist?("/proc/meminfo")
 				end
 				
+				# Capture host memory from `/proc/meminfo`.
+				# @returns [Host::Memory | Nil] The captured host memory, if available.
 				def capture
 					content = File.read("/proc/meminfo") rescue nil
 					return nil unless content

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

@@ -10,6 +10,9 @@ module Process
 			module Memory::Linux
 				DEFAULT_CGROUP_ROOT = "/sys/fs/cgroup"
 				
+				# Capture host memory from the available Linux interface.
+				# @parameter cgroup_root [String] The root of the cgroup filesystem.
+				# @returns [Host::Memory | Nil] The captured host memory, if available.
 				def self.capture(cgroup_root: DEFAULT_CGROUP_ROOT)
 					if Memory::Linux::CgroupV2.supported?(cgroup_root)
 						if capture = Memory::Linux::CgroupV2.new(cgroup_root: cgroup_root).capture

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

@@ -15,12 +15,17 @@ module Process
 			# @attribute swap_used_size [Integer, nil] Swap in use, or nil if not available.
 			# @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
+				# Convert the memory snapshot to a hash, including derived sizes.
+				# @returns [Hash(Symbol, Integer | Nil)] The memory snapshot fields.
 				def to_h
 					super.merge(free_size: free_size, available_size: available_size)
 				end
 				
 				alias as_json to_h
 				
+				# Convert the memory snapshot to JSON.
+				# @parameter arguments [Array] Additional arguments passed to the JSON encoder.
+				# @returns [String] The encoded memory snapshot.
 				def to_json(*arguments)
 					as_json.to_json(*arguments)
 				end

data/lib/process/metrics/processor.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		# Computes interval CPU utilization from cumulative process metrics.
+		class Processor
+			# An immutable measurement of process CPU usage over an interval.
+			# @attribute [Integer] The process ID.
+			# @attribute [Float] The elapsed monotonic time in seconds.
+			# @attribute [Float] The CPU time consumed during the interval in seconds.
+			# @attribute [Float] The CPU utilization in core units, where `1.0` represents one fully occupied core. Multi-threaded processes may report values greater than `1.0`.
+			class Sample < Struct.new(:process_id, :duration, :processor_time, :utilization)
+			end
+			
+			# @private
+			Snapshot = Struct.new(:start_time, :processor_time, :timestamp)
+			
+			# Initialize a process metrics sampler.
+			# @parameter capture [Interface(:call)] The process snapshot capture callable.
+			def initialize(capture: General.method(:capture))
+				@capture = capture
+				@snapshots = {}
+			end
+			
+			# Sample CPU utilization for the given processes.
+			# The first observation of each process establishes a baseline and does not produce a sample.
+			# @parameter process_ids [Integer | Array(Integer)] The process IDs to sample.
+			# @returns [Hash(Integer, Processor::Sample)] The valid interval samples keyed by process ID.
+			def sample(process_ids)
+				processes = @capture.call(pid: process_ids, memory: false)
+				timestamp = now
+				return {} unless finite?(timestamp)
+				
+				samples = {}
+				snapshots = {}
+				
+				processes.each do |process_id, process|
+					start_time = process.start_time
+					processor_time = process.processor_time
+					next unless finite?(start_time) && finite?(processor_time)
+					
+					current = Snapshot.new(start_time, processor_time, timestamp)
+					snapshots[process_id] = current
+					
+					if previous = @snapshots[process_id]
+						next unless previous.start_time == current.start_time
+						
+						duration = current.timestamp - previous.timestamp
+						processor_time = current.processor_time - previous.processor_time
+						next unless finite?(duration) && duration > 0.0
+						next unless finite?(processor_time) && processor_time >= 0.0
+						
+						utilization = processor_time / duration
+						next unless finite?(utilization)
+						
+						samples[process_id] = Sample.new(process_id, duration, processor_time, utilization).freeze
+					end
+				end
+				
+				@snapshots = snapshots
+				
+				return samples
+			end
+			
+			private
+			
+			# Get the current monotonic time.
+			def now
+				Process.clock_gettime(Process::CLOCK_MONOTONIC)
+			end
+			
+			# Whether the value is a finite number.
+			def finite?(value)
+				value.is_a?(Numeric) && value.finite?
+			end
+		end
+	end
+end

data/lib/process/metrics/version.rb

@@ -7,6 +7,6 @@
 module Process
 	# @namespace
 	module Metrics
-		VERSION = "0.11.1"
+		VERSION = "0.13.0"
 	end
 end

data/lib/process/metrics.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require_relative "metrics/version"
 require_relative "metrics/general"
+require_relative "metrics/processor"

data/readme.md

@@ -16,6 +16,14 @@ 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.13.0
+
+  - Normalize processor utilization to core units, where `1.0` represents one fully occupied CPU core, and restore Linux reporting.
+
+### v0.12.0
+
+  - Add `Process::Metrics::Processor` for measuring per-process CPU utilization over an interval.
+
 ### v0.11.0
 
   - `process-metrics` command is removed, replaced with `bake process:metrics`.
@@ -52,14 +60,6 @@ Please see the [project releases](https://socketry.github.io/process-metrics/rel
 
   - Handle `Errno::ESRCH: No such process @ io_fillbuf - fd:xxx /proc/xxx/smaps_rollup` by ignoring it.
 
-### 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.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.13.0
+
+  - Normalize processor utilization to core units, where `1.0` represents one fully occupied CPU core, and restore Linux reporting.
+
+## v0.12.0
+
+  - Add `Process::Metrics::Processor` for measuring per-process CPU utilization over an interval.
+
 ## v0.11.0
 
   - `process-metrics` command is removed, replaced with `bake process:metrics`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process-metrics
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -88,6 +88,7 @@ files:
 - lib/process/metrics/memory.rb
 - lib/process/metrics/memory/darwin.rb
 - lib/process/metrics/memory/linux.rb
+- lib/process/metrics/processor.rb
 - lib/process/metrics/version.rb
 - license.md
 - readme.md
@@ -113,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Provide detailed OS-specific process metrics.
 test_files: []