process-metrics 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4692590f9565bbf61e0854c736a4225749d1e12021b0fa769fdc6cab6cee7002
-  data.tar.gz: 138b82d832444faa4eafe5137ae4f25ffd4652b5d2b313fd698b1a11c871cb09
+  metadata.gz: 86b26a801c95a764b0f98139e25ad1ac12b455b1b44b664722d1ff189bce8be4
+  data.tar.gz: 7591aff04fdbc4e9b6eabdd42ac8bcdf6ffbeea605f812b1d00255a57cba49c5
 SHA512:
-  metadata.gz: be2a880bd7a6285d5472425860ab1cdf1f031e0aca0e0565e849825e51449a9f1278646a34796f6b43f6e9c19cc7b120850e1470e1cc8bc86d9114e27709b779
-  data.tar.gz: 6c149bd8d92118add7f24d2a28d6c9b1ac22e97bd048fb5e30f3ed9e93f4b88bccf3be428255469e566d538ee81ebea72aaa82e7b7db0dce7841e89d8fcba5e0
+  metadata.gz: 1a688f8a4db31df31adbbc5d5513716785ff61047f0b010aba506064d4c981dc5582fe99784eef0d244f877643034325d0996a323cc91e3ee1d6e6caa0e0f8e9
+  data.tar.gz: 72d8c7499461b35deafd4af20ba6c065de44f76d8868971e3ab70795febbb2863df98f9cb06c1e82e94fc1cdc7867275d58e1e03f9aa9ea890d50c5a37cf05bb

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,39 @@ 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`.
+
+## Processor Capacity
+
+Use {ruby Process::Metrics::Processor.count} to get the number of processors available to the current process. On Linux, this takes CPU affinity into account.
+
+Use {ruby Process::Metrics::Processor.quota} to get the available processor capacity as a `Float`. On Linux, it also takes cgroup v2 CPU bandwidth limits into account. On other systems, when no finite quota is configured, or when the quota cannot be determined, it returns {ruby Process::Metrics::Processor.count} as a `Float`.
+
+``` ruby
+Process::Metrics::Processor.count
+# => 8
+
+Process::Metrics::Processor.quota
+# => 1.5
+```

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

@@ -73,6 +73,11 @@ module Process
 					end
 					processor_time = (utime + stime).to_f / CLK_TCK
 					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)
 					
@@ -80,7 +85,7 @@ 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,

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

@@ -17,7 +17,7 @@ module Process
 				pid: ->(values){values.shift.to_i},
 				ppid: ->(values){values.shift.to_i},
 				pgid: ->(values){values.shift.to_i},
-				pcpu: ->(values){values.shift.to_f},
+				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)},

data/lib/process/metrics/general.rb

@@ -35,6 +35,7 @@ module Process
 		end
 		
 		# General process information.
+		# @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

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		class Processor
+			# @private
+			module Linux
+				DEFAULT_CGROUP_ROOT = "/sys/fs/cgroup"
+				DEFAULT_CGROUP_PATH = "/proc/self/cgroup"
+				
+				class << self
+					# Read the effective processor quota for the current cgroup.
+					# @parameter cgroup_root [String] The root of the cgroup v2 filesystem.
+					# @parameter cgroup_path [String] The process cgroup membership file.
+					# @returns [Float | Nil] The smallest finite quota in the cgroup hierarchy, if available.
+					def quota(cgroup_root: DEFAULT_CGROUP_ROOT, cgroup_path: DEFAULT_CGROUP_PATH)
+						unless relative_path = current_path(cgroup_path)
+							return nil
+						end
+						
+						root = File.expand_path(cgroup_root)
+						directory = File.expand_path(relative_path.delete_prefix("/"), root)
+						return nil unless directory == root || directory.start_with?("#{root}/")
+						
+						quota = nil
+						
+						loop do
+							if current = read_quota(directory)
+								quota = [quota, current].compact.min
+							end
+							
+							break if directory == root
+							directory = File.dirname(directory)
+						end
+						
+						return quota
+					rescue Errno::EACCES, Errno::EINVAL, Errno::ENOENT, Errno::ENOTDIR, ArgumentError
+						return nil
+					end
+					
+					private
+					
+					def current_path(path)
+						File.foreach(path) do |line|
+							hierarchy, controllers, relative_path = line.strip.split(":", 3)
+							
+							if hierarchy == "0" && controllers == "" && relative_path
+								return relative_path
+							end
+						end
+						
+						return nil
+					end
+					
+					def read_quota(directory)
+						maximum, period = File.read(File.join(directory, "cpu.max")).split
+						return nil if maximum == "max" || !maximum || !period
+						
+						maximum = Integer(maximum)
+						period = Integer(period)
+						return nil unless maximum.positive? && period.positive?
+						
+						return maximum.to_f / period
+					rescue Errno::EACCES, Errno::EINVAL, Errno::ENOENT, Errno::ENOTDIR, ArgumentError
+						return nil
+					end
+				end
+			end
+			
+			# The processor capacity available to the current process.
+			# This takes cgroup v2 CPU bandwidth limits into account, and otherwise returns {count} as a `Float`.
+			# @returns [Float] The available processor capacity in core units.
+			def self.quota
+				count = self.count.to_f
+				
+				if quota = Linux.quota
+					if quota < count
+						return quota
+					end
+				end
+				
+				return count
+			end
+		end
+	end
+end

data/lib/process/metrics/processor.rb

@@ -3,15 +3,31 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
+require "etc"
+
 module Process
 	module Metrics
 		# Computes interval CPU utilization from cumulative process metrics.
 		class Processor
+			# The number of processors available to the current process.
+			# On Linux, this takes the process CPU affinity into account.
+			# @returns [Integer] The number of available processors.
+			def self.count
+				Etc.nprocessors
+			end
+			
+			# The processor capacity available to the current process.
+			# On Linux, this takes cgroup v2 CPU bandwidth limits into account. Otherwise, it returns {count} as a `Float`.
+			# @returns [Float] The available processor capacity in core units.
+			def self.quota
+				return self.count.to_f
+			end
+			
 			# 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`.
+			# @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
 			
@@ -79,3 +95,7 @@ module Process
 		end
 	end
 end
+
+if RUBY_PLATFORM.include?("linux")
+	require_relative "processor/linux"
+end

data/lib/process/metrics/version.rb

@@ -7,6 +7,6 @@
 module Process
 	# @namespace
 	module Metrics
-		VERSION = "0.12.0"
+		VERSION = "0.14.0"
 	end
 end

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.14.0
+
+  - Add `Process::Metrics::Processor.count` and `.quota` for affinity-aware processor counts and cgroup v2-aware processor capacity.
+
+### 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.
@@ -52,14 +60,6 @@ Please see the [project releases](https://socketry.github.io/process-metrics/rel
 
   - Be more proactive about returning nil if memory capture failed.
 
-### v0.6.1
-
-  - 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).
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.14.0
+
+  - Add `Process::Metrics::Processor.count` and `.quota` for affinity-aware processor counts and cgroup v2-aware processor capacity.
+
+## 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process-metrics
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -89,6 +89,7 @@ files:
 - lib/process/metrics/memory/darwin.rb
 - lib/process/metrics/memory/linux.rb
 - lib/process/metrics/processor.rb
+- lib/process/metrics/processor/linux.rb
 - lib/process/metrics/version.rb
 - license.md
 - readme.md

metadata.gz.sig

@@ -1,5 +1,2 @@
-L��/�Uϟlk���4H�	�Y=ǽv��˨W�p�if={�lX���	�н��z�
-R���8H��I����94��s]�����
-���m��l�iqp��Vk���C��)]�j�����Y�I�q5��Sj>D�Z�𽦗�y�ִ�8ʋqr��ٓ���~���bV2���'(ױn:���q��?��,lTM"��
d?*��g;a��P�ꯖ	�
-*;āz@*�%��YNvV�`��$��e8n������~g��^V�9͊O(�@�g@>M���oh^ޅA��;JfS=
-���`�9���6!���B��+~��:Rd��\���Xha��&l��
X�̔2��+#M�Lf�	
+l��U�H�3�>:���H�F#����#Q�
)4�q&x�3���'�
���$�A�=4ߵ�Lj����%����y��YH�����ŕ���x>'*vĿ���CV���3,�Y�
+��(����d�JY�&�c�+�gϖ�J�ܳ�WA�g	��mS0r)��y~