process-metrics 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4692590f9565bbf61e0854c736a4225749d1e12021b0fa769fdc6cab6cee7002
-  data.tar.gz: 138b82d832444faa4eafe5137ae4f25ffd4652b5d2b313fd698b1a11c871cb09
+  metadata.gz: 2822c0b3ad1a6e79d294cc8607359b1a8042818a8b07306c5685064addd4b7fd
+  data.tar.gz: f945a7b3bcf467f696c9823a11ecefa996aae3f7e9d075bcfcd6bba87edd13d1
 SHA512:
-  metadata.gz: be2a880bd7a6285d5472425860ab1cdf1f031e0aca0e0565e849825e51449a9f1278646a34796f6b43f6e9c19cc7b120850e1470e1cc8bc86d9114e27709b779
-  data.tar.gz: 6c149bd8d92118add7f24d2a28d6c9b1ac22e97bd048fb5e30f3ed9e93f4b88bccf3be428255469e566d538ee81ebea72aaa82e7b7db0dce7841e89d8fcba5e0
+  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

@@ -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.rb

@@ -11,7 +11,7 @@ module Process
 			# @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
 			

data/lib/process/metrics/version.rb

@@ -7,6 +7,6 @@
 module Process
 	# @namespace
 	module Metrics
-		VERSION = "0.12.0"
+		VERSION = "0.13.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.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.
@@ -56,10 +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).
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

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

data.tar.gz.sig

@@ -1 +1,2 @@
-S�,d�sL���Y���xN�=1s��C�	>
������5����`F�ZyҪ�C�*�hb�Č���V���J�����B�����2 ^[t4�� @r��=����K���R�*0`��D �g���3�~Uv���b����y�����[8u�����^A=������ �@����	G�w�=1�3p}���;% D`�S���P�G"1��%������wBZV�8�C
��׮�PԼ�N��&ÓD�
��K�Cw�
CB���I�`Ch��{�F��,��`�.�4�W�b����I�?B���+?����#|�׎A;$d:�hW?@�ua�I��x,��
�"��Ez�ŰbbIC��HY�&��9'ܷ
+�)����q=��;��]�$]�irV��0��ޛnk}rO��'r�6˜�/3��gPX��Zl#�b���!2��_C:�4�.bgEL�y�1�p��6�?c>����
��� z�-/��އv�5FE��A���Y��]��x�	�v
+�$���������ٔ&��YqL4�u���`q�Q���iF���'�")�҃�9Su�yJ@7��ίRQ#��

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process-metrics
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Samuel Williams