process-metrics 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbf463af0812bd192ef672f02852cc6142e4ec07ce54e9101561e236848a9339
-  data.tar.gz: debc60440d79a2a745ea287e129f22b4a72fbf4b608a8903aafb95a3204b9b38
+  metadata.gz: 4692590f9565bbf61e0854c736a4225749d1e12021b0fa769fdc6cab6cee7002
+  data.tar.gz: 138b82d832444faa4eafe5137ae4f25ffd4652b5d2b313fd698b1a11c871cb09
 SHA512:
-  metadata.gz: f5b9a378cb31b094f83e180696df41dc7c1cc46f7df1e7af782e9883b07ef1e4d4e0007eab9a90a4526e55f794a9d697a5a5033024ea165392ba2ad6af4face0
-  data.tar.gz: '0281fd18c13ccc1d5a1bc4092b242209185ef38239b227b350dca21d780b912ca5fcacbc81a30ae819bfe4e37972494c7fb432e899887a1c0453973fed6fed87'
+  metadata.gz: be2a880bd7a6285d5472425860ab1cdf1f031e0aca0e0565e849825e51449a9f1278646a34796f6b43f6e9c19cc7b120850e1470e1cc8bc86d9114e27709b779
+  data.tar.gz: 6c149bd8d92118add7f24d2a28d6c9b1ac22e97bd048fb5e30f3ed9e93f4b88bccf3be428255469e566d538ee81ebea72aaa82e7b7db0dce7841e89d8fcba5e0

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,8 @@ 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
 					
 					command = read_command(pid, executable_name)
 					
@@ -80,6 +85,7 @@ module Process
 						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},
+				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,7 @@ 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)
+		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 +48,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, where one fully occupied core is `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.12.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,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.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`.
@@ -56,10 +60,6 @@ Please see the [project releases](https://socketry.github.io/process-metrics/rel
 
   - 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,9 @@
 # Releases
 
+## 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.12.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: []