process-metrics 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b288419449c98ce2b53cc2ecb8d3d2660a473c17677b66e6f18015b803db1482
-  data.tar.gz: 67b4d639f7744814e47e61aac54ef7c588557a94ca8454926594d742f9cf88ce
+  metadata.gz: 7fc7fb298dde1bb1446b8223bf55be24f776fe8e042c0a5e2ee2cf3452e64383
+  data.tar.gz: 340908860960f819a24c864e3d64bed4288840fad98dc4a0f33f37e622cc22ce
 SHA512:
-  metadata.gz: 0a1686b0609d8009a2d5a26b659876c29c5378d89b35b39777b5d55d53413b2a10558470075ce0303959f77213ceef101cad19547dc95743440d0243af2746e1
-  data.tar.gz: 13a3e9bbc06eb5412a6b37c499f531eebf58317c1944d0e679dd68d8b87abc4450e62b7166c435334745555d26bb873b9ddc47d65324bdf17832b27865f60a2c
+  metadata.gz: d7bef8457eb65f378e63d65a768ac8ab4d5d4ae45bcb97f7489b9e06676afeb5fabe2e7b818d132fcae6436e51394ee810ade201f17f8ffd24211db42452b2a5
+  data.tar.gz: 680700b1619d358370114cde3c8d1025c998b0e55ad01d5ee6a3c211857056865f9dd9f5d244ac20ebcb5ec6595f4e8439a2193c28f3765dae17b20df3158b64

data/context/getting-started.md

@@ -32,29 +32,30 @@ Process::Metrics::General.capture(pid: Process.pid)
 # => 
 # {3517456=>
 #   #<struct Process::Metrics::General
-#    pid=3517456,
-#    ppid=3517432,
-#    pgid=3517456,
+#    process_id=3517456,
+#    parent_process_id=3517432,
+#    process_group_id=3517456,
 #    processor_utilization=0.0,
-#    vsz=0,
-#    rss=486892,
-#    time=29928,
-#    etime=2593,
+#    virtual_size=445768278528,
+#    resident_size=20348928,
+#    processor_time=0.05,
+#    elapsed_time=2.0,
 #    command="irb",
 #    memory=
 #     #<struct Process::Metrics::Memory
 #      map_count=193,
-#      total_size=486896,
-#      resident_size=30556,
-#      proportional_size=25672,
-#      shared_clean_size=5008,
+#      resident_size=31289344,
+#      proportional_size=26288128,
+#      shared_clean_size=5128192,
 #      shared_dirty_size=0,
-#      private_clean_size=5180,
-#      private_dirty_size=20368,
-#      referenced_size=30548,
-#      anonymous_size=20376,
+#      private_clean_size=5304320,
+#      private_dirty_size=20856832,
+#      referenced_size=31281152,
+#      anonymous_size=20865024,
 #      swap_size=0,
-#      proportional_swap_size=0>>}
+#      proportional_swap_size=0,
+#      minor_faults=0,
+#      major_faults=0>>}
 ```
 
 If you want to capture a tree of processes, you can specify the `ppid:` option instead.
@@ -67,8 +68,8 @@ The {ruby Process::Metrics::General} struct contains the following fields:
 - `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).
-- `total_size` - Memory Size (KB), 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 (KB), the amount of physical memory used by the process.
+- `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.
 - `elapsed_time` - Elapsed Time (s), the amount of time the process has been running.
 - `command` - Command Name, the name of the command that started the process.
@@ -76,15 +77,15 @@ The {ruby Process::Metrics::General} struct contains the following fields:
 The {ruby Process::Metrics::Memory} struct contains the following fields:
 
 - `map_count` - Number of Memory Mappings, e.g. number of thread stacks, fiber stacks, shared libraries, memory mapped files, etc.
-- `resident_size` - Resident Memory Size (KB), the amount of physical memory used by the process.
-- `proportional_size` - Proportional Memory Size (KB), the amount of memory that the process is using, taking into account shared memory.
-- `shared_clean_size` - Shared Clean Memory Size (KB), the amount of shared memory that is clean (not modified).
-- `shared_dirty_size` - Shared Dirty Memory Size (KB), the amount of shared memory that is dirty (modified).
-- `private_clean_size` - Private Clean Memory Size (KB), the amount of private memory that is clean (not modified).
-- `private_dirty_size` - Private Dirty Memory Size (KB), the amount of private memory that is dirty (modified).
-- `referenced_size` - Referenced Memory Size (KB), active page-cache that isn't going to be reclaimed any time soon.
-- `anonymous_size` - Anonymous Memory Size (KB), mapped memory that isn't backed by a file.
-- `swap_size` - Swap Memory Size (KB), the amount of memory that has been swapped to disk.
-- `proportional_swap_size` - Proportional Swap Memory Size (KB), the amount of memory that has been swapped to disk, excluding shared memory.
+- `resident_size` - Resident Memory Size (bytes), the amount of physical memory used by the process.
+- `proportional_size` - Proportional Memory Size (bytes), the amount of memory that the process is using, taking into account shared memory.
+- `shared_clean_size` - Shared Clean Memory Size (bytes), the amount of shared memory that is clean (not modified).
+- `shared_dirty_size` - Shared Dirty Memory Size (bytes), the amount of shared memory that is dirty (modified).
+- `private_clean_size` - Private Clean Memory Size (bytes), the amount of private memory that is clean (not modified).
+- `private_dirty_size` - Private Dirty Memory Size (bytes), the amount of private memory that is dirty (modified).
+- `referenced_size` - Referenced Memory Size (bytes), active page-cache that isn't going to be reclaimed any time soon.
+- `anonymous_size` - Anonymous Memory Size (bytes), mapped memory that isn't backed by a file.
+- `swap_size` - Swap Memory Size (bytes), the amount of memory that has been swapped to disk.
+- `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.

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "samovar"
 
@@ -90,23 +90,28 @@ module Process
 				UNITS = ["KiB", "MiB", "GiB"]
 				
 				# Format a memory size value in human-readable units.
-				# @parameter value [Numeric] The size value in kilobytes.
+				# @parameter value [Numeric] The size value in bytes.
 				# @parameter units [Array(String)] The unit labels to use for scaling.
 				# @returns [String] A formatted string with value and unit (e.g., "512KiB", "1.5MiB").
 				def format_size(value, units: UNITS)
-					unit = 0
+					unit = -1
 					
-					while value > 1024.0 && unit < units.size
+					while value >= 1024.0 && unit < units.size - 1
 						value /= 1024.0
 						unit += 1
 					end
 					
-					return "#{value.round(unit)}#{units[unit]}"
+					if unit < 0
+						# Value is less than 1 KiB, show in bytes
+						return "#{value.round(0)}B"
+					else
+						return "#{value.round(unit)}#{units[unit]}"
+					end
 				end
 				
 				# Format a memory value with a horizontal bar showing utilization relative to total.
-				# @parameter value [Numeric] The memory value in kilobytes.
-				# @parameter total [Numeric] The total memory available in kilobytes.
+				# @parameter value [Numeric] The memory value in bytes.
+				# @parameter total [Numeric] The total memory available in bytes.
 				# @parameter terminal [Console::Terminal] The terminal to output styled text.
 				def format_memory(value, total, terminal)
 					if value > (total * 0.8)
@@ -123,10 +128,11 @@ module Process
 				end
 				
 				# Get the total memory to use for percentage calculations.
-				# @returns [Integer] Total memory in kilobytes.
+				# @returns [Integer] Total memory in bytes.
 				def total_memory
 					if total_memory = @options[:total_memory]
-						return total_memory * 1024
+						# Convert from MiB to bytes
+						return total_memory * 1024 * 1024
 					else
 						return Process::Metrics::Memory.total_size
 					end

data/lib/process/metrics/general.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require_relative "memory"
 require "set"
@@ -42,8 +42,8 @@ module Process
 			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)
+			vsz: ->(value){value.to_i * 1024}, # Virtual Size (convert from KiB to bytes)
+			rss: ->(value){value.to_i * 1024}, # Resident Size (convert from KiB to bytes)
 			time: self.method(:duration), # CPU Time (seconds)
 			etime: self.method(:duration), # Elapsed Time (seconds)
 			command: ->(value){value}, # Command (name of the process)
@@ -73,7 +73,7 @@ module Process
 				as_json.to_json(*arguments)
 			end
 			
-			# The total size of the process in memory, in kilobytes.
+			# The total size of the process in memory, in bytes.
 			def total_size
 				if memory = self.memory
 					memory.proportional_size

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 module Process
 	module Metrics
@@ -14,29 +14,29 @@ module Process
 				File.executable?(VMMAP)
 			end
 			
-			# @returns [Numeric] Total memory size in kilobytes.
+			# @returns [Numeric] Total memory size in bytes.
 			def self.total_size
 				# sysctl hw.memsize
 				IO.popen(["sysctl", "hw.memsize"], "r") do |io|
 					io.each_line do |line|
 						if line =~ /hw.memsize: (\d+)/
-							return $1.to_i / 1024
+							return $1.to_i
 						end
 					end
 				end
 			end
 			
-			# Parse a size string from vmmap output into kilobytes.
+			# Parse a size string from vmmap output into bytes.
 			# @parameter string [String | Nil] The size string (e.g., "4K", "1.5M", "2G").
-			# @returns [Integer] The size in kilobytes.
+			# @returns [Integer] The size in bytes.
 			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
+				when /([\d\.]+)K/i then ($1.to_f * 1024).round
+				when /([\d\.]+)M/i then ($1.to_f * 1024 * 1024).round
+				when /([\d\.]+)G/i then ($1.to_f * 1024 * 1024 * 1024).round
+				else (string.to_f).ceil
 				end
 			end
 			
@@ -111,7 +111,7 @@ module Process
 				end
 				
 				# Get total system memory size.
-				# @returns [Integer] Total memory in kilobytes.
+				# @returns [Integer] Total memory in bytes.
 				def total_size
 					return Memory::Darwin.total_size
 				end

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

@@ -1,12 +1,26 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 module Process
 	module Metrics
 		# Linux implementation of memory metrics using `/proc/[pid]/smaps` and `/proc/[pid]/stat`.
 		class Memory::Linux
+			# Threshold for distinguishing actual memory limits from "unlimited" sentinel values in cgroups v1.
+			# 
+			# In cgroups v1, when memory.limit_in_bytes is set to unlimited (by writing -1),
+			# the kernel stores a very large sentinel value close to 2^63 (approximately 9,223,372,036,854,771,712 bytes).
+			# Since no real system would have 1 exabyte (2^60 bytes) of RAM, any value >= this threshold
+			# indicates an "unlimited" configuration and should be treated as if no limit is set.
+			#
+			# This allows us to distinguish between:
+			# - Actual container memory limits: typically in GB-TB range (< 1 EB)
+			# - Unlimited sentinel values: near 2^63 (>> 1 EB)
+			#
+			# Reference: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt
+			CGROUP_V1_UNLIMITED_THRESHOLD = 2**60 # ~1 exabyte
+			
 			# Extract minor/major page fault counters from `/proc/[pid]/stat` and assign to usage.
 			# @parameter pid [Integer] The process ID.
 			# @parameter usage [Memory] The Memory instance to populate with fault counters.
@@ -23,11 +37,34 @@ module Process
 				# Ignore.
 			end
 			
-			# @returns [Numeric] Total memory size in kilobytes.
+			# Determine the total memory size in bytes. This is the maximum amount of memory that can be used by the current process. If running in a container, this may be limited by the container runtime (e.g. cgroups).
+			#
+			# @returns [Integer] The total memory size in bytes.
 			def self.total_size
-				File.read("/proc/meminfo").each_line do |line|
-					if /MemTotal:\s+(?<total>\d+) kB/ =~ line
-						return total.to_i
+				# Check for Kubernetes/cgroup memory limit first (cgroups v2):
+				if File.exist?("/sys/fs/cgroup/memory.max")
+					limit = File.read("/sys/fs/cgroup/memory.max").strip
+					# "max" means unlimited, fall through to other methods:
+					if limit != "max"
+						return limit.to_i
+					end
+				end
+				
+				# Check for Kubernetes/cgroup memory limit (cgroups v1):
+				if File.exist?("/sys/fs/cgroup/memory/memory.limit_in_bytes")
+					limit = File.read("/sys/fs/cgroup/memory/memory.limit_in_bytes").strip.to_i
+					# A very large number means unlimited, fall through:
+					if limit > 0 && limit < CGROUP_V1_UNLIMITED_THRESHOLD
+						return limit
+					end
+				end
+				
+				# Fall back to Linux system memory detection:
+				if File.exist?("/proc/meminfo")
+					File.foreach("/proc/meminfo") do |line|
+						if /MemTotal:\s*(?<total>\d+)\s*kB/ =~ line
+							return total.to_i * 1024
+						end
 					end
 				end
 			end
@@ -53,21 +90,27 @@ module Process
 				end
 				
 				# Capture memory usage for the given process IDs.
-				def self.capture(pid, **options)
+				# @parameter pid [Integer] The process ID.
+				# @parameter faults [Boolean] Whether to capture fault counters (default: true).
+				# @parameter options [Hash] Additional options.
+				def self.capture(pid, faults: true, **options)
 					File.open("/proc/#{pid}/smaps_rollup") do |file|
 						usage = Memory.zero
 						
 						file.each_line do |line|
 							if /(?<name>.*?):\s+(?<value>\d+) kB/ =~ line
 								if key = SMAP[name]
-									usage[key] += value.to_i
+									# Convert from kilobytes to bytes
+									usage[key] += value.to_i * 1024
 								end
 							end
 						end
 						
 						usage.map_count += File.readlines("/proc/#{pid}/maps").size
-						# Also capture fault counters:
-						self.capture_faults(pid, usage)
+						# Also capture fault counters if requested:
+						if faults
+							self.capture_faults(pid, usage)
+						end
 						
 						return usage
 					end
@@ -82,7 +125,10 @@ module Process
 				end
 				
 				# Capture memory usage for the given process IDs.
-				def self.capture(pid, **options)
+				# @parameter pid [Integer] The process ID.
+				# @parameter faults [Boolean] Whether to capture fault counters (default: true).
+				# @parameter options [Hash] Additional options.
+				def self.capture(pid, faults: true, **options)
 					File.open("/proc/#{pid}/smaps") do |file|
 						usage = Memory.zero
 						
@@ -91,7 +137,8 @@ module Process
 							# https://github.com/torvalds/linux/blob/351c8a09b00b5c51c8f58b016fffe51f87e2d820/fs/proc/task_mmu.c#L804-L814
 							if /(?<name>.*?):\s+(?<value>\d+) kB/ =~ line
 								if key = SMAP[name]
-									usage[key] += value.to_i
+									# Convert from kilobytes to bytes
+									usage[key] += value.to_i * 1024
 								end
 							elsif /VmFlags:\s+(?<flags>.*)/ =~ line
 								# It should be possible to extract the number of fibers and each fiber's memory usage.
@@ -100,8 +147,8 @@ module Process
 							end
 						end
 						
-						# Also capture fault counters:
-						self.capture_faults(pid, usage)
+						# Also capture fault counters if requested:
+						self.capture_faults(pid, usage) if faults
 						
 						return usage
 					end
@@ -125,13 +172,14 @@ module Process
 				end
 				
 				# Get total system memory size.
-				# @returns [Integer] Total memory in kilobytes.
+				# @returns [Integer] Total memory in bytes.
 				def total_size
 					return Memory::Linux.total_size
 				end
 				
 				# Capture memory metrics for a process.
 				# @parameter pid [Integer] The process ID.
+				# @parameter faults [Boolean] Whether to capture fault counters (default: true).
 				# @parameter options [Hash] Additional options.
 				# @returns [Memory] A Memory instance with captured metrics.
 				def capture(...)

data/lib/process/metrics/memory.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require "json"
 
 module Process
 	module Metrics
-		# Represents memory usage for a process, sizes are in kilobytes.
+		# Represents memory usage for a process, sizes are in bytes.
 		class Memory < Struct.new(:map_count, :resident_size, :proportional_size, :shared_clean_size, :shared_dirty_size, :private_clean_size, :private_dirty_size, :referenced_size, :anonymous_size, :swap_size, :proportional_swap_size, :minor_faults, :major_faults)
 			
 			alias as_json to_h

data/lib/process/metrics/version.rb

@@ -7,6 +7,6 @@
 module Process
 	# @namespace
 	module Metrics
-		VERSION = "0.8.0"
+		VERSION = "0.9.0"
 	end
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2019-2025, by Samuel Williams.  
+Copyright, 2019-2026, by Samuel Williams.  
 Copyright, 2024, by Adam Daniels.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

data/readme.md

@@ -16,6 +16,12 @@ 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.9.0
+
+  - `Process::Metrics::Memory.total_size` takes into account cgroup limits.
+  - On Linux, capturing faults is optional, controlled by `capture(faults: true/false)`.
+  - Report all sizes in bytes for consistency.
+
 ### v0.7.0
 
   - Be more proactive about returning nil if memory capture failed.
@@ -67,12 +73,6 @@ Please see the [project releases](https://socketry.github.io/process-metrics/rel
   - Implemented structured data using Ruby structs for better performance and clarity.
   - Added documentation about PSS (Proportional Set Size) and USS (Unique Set Size) metrics.
 
-### v0.1.1
-
-  - Removed `Gemfile.lock` from version control.
-  - Fixed process metrics to exclude the `ps` command itself from measurements.
-  - Fixed documentation formatting issues.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,11 @@
 # Releases
 
+## v0.9.0
+
+  - `Process::Metrics::Memory.total_size` takes into account cgroup limits.
+  - On Linux, capturing faults is optional, controlled by `capture(faults: true/false)`.
+  - Report all sizes in bytes for consistency.
+
 ## v0.7.0
 
   - Be more proactive about returning nil if memory capture failed.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process-metrics
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -122,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Provide detailed OS-specific process metrics.
 test_files: []