process-metrics 0.5.0 → 0.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/context/getting-started.md +90 -0
- data/context/index.yaml +13 -0
- data/lib/process/metrics/command/summary.rb +7 -2
- data/lib/process/metrics/memory/linux.rb +3 -3
- data/lib/process/metrics/version.rb +2 -2
- data/readme.md +57 -0
- data/releases.md +54 -0
- data.tar.gz.sig +0 -0
- metadata +7 -4
- metadata.gz.sig +0 -0
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 290184074b5b6558048bda94e92bc192afe72cac005834ea36a12814048d91bc
|
|
4
|
+
data.tar.gz: '079bf8f07d0ea7705c366008d99cb2fe20511d130e98b273d28c8384d877e40d'
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 2029110f30b0993f1c1e30113c391e005b516a8ab7a0a5e945e7629470a4c6659772b370ed5d350667be164a7a216049d5d97ecae60d2809133bd39635dac45e
|
|
7
|
+
data.tar.gz: 3f1f223f289c74f15f8e15ce333ee998afcbc671270003420ba1e0b698abadb22647fc5a655125c0da098d45c0cba48d0e401eb6f14abc6e600605ab90486210
|
checksums.yaml.gz.sig
CHANGED
|
Binary file
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Getting Started
|
|
2
|
+
|
|
3
|
+
This guide explains how to use the `process-metrics` gem to collect and analyze process metrics including processor and memory utilization.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
Add the gem to your project:
|
|
8
|
+
|
|
9
|
+
``` bash
|
|
10
|
+
$ bundle add process-metrics
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Or, if you prefer, install it globally:
|
|
14
|
+
|
|
15
|
+
``` bash
|
|
16
|
+
$ gem install process-metrics
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Core Concepts
|
|
20
|
+
|
|
21
|
+
The `process-metrics` gem provides a simple interface to collect and analyze process metrics.
|
|
22
|
+
|
|
23
|
+
- {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.
|
|
24
|
+
- {ruby Process::Metrics::Memory} provides additional methods for collecting memory metrics when the host operating system provides the necessary information.
|
|
25
|
+
|
|
26
|
+
## Usage
|
|
27
|
+
|
|
28
|
+
To collect process metrics, use the {ruby Process::Metrics::General.capture} method:
|
|
29
|
+
|
|
30
|
+
``` ruby
|
|
31
|
+
Process::Metrics::General.capture(pid: Process.pid)
|
|
32
|
+
# =>
|
|
33
|
+
# {3517456=>
|
|
34
|
+
# #<struct Process::Metrics::General
|
|
35
|
+
# pid=3517456,
|
|
36
|
+
# ppid=3517432,
|
|
37
|
+
# pgid=3517456,
|
|
38
|
+
# processor_utilization=0.0,
|
|
39
|
+
# vsz=0,
|
|
40
|
+
# rss=486892,
|
|
41
|
+
# time=29928,
|
|
42
|
+
# etime=2593,
|
|
43
|
+
# command="irb",
|
|
44
|
+
# memory=
|
|
45
|
+
# #<struct Process::Metrics::Memory
|
|
46
|
+
# map_count=193,
|
|
47
|
+
# total_size=486896,
|
|
48
|
+
# resident_size=30556,
|
|
49
|
+
# proportional_size=25672,
|
|
50
|
+
# shared_clean_size=5008,
|
|
51
|
+
# shared_dirty_size=0,
|
|
52
|
+
# private_clean_size=5180,
|
|
53
|
+
# private_dirty_size=20368,
|
|
54
|
+
# referenced_size=30548,
|
|
55
|
+
# anonymous_size=20376,
|
|
56
|
+
# swap_size=0,
|
|
57
|
+
# proportional_swap_size=0>>}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
If you want to capture a tree of processes, you can specify the `ppid:` option instead.
|
|
61
|
+
|
|
62
|
+
### Fields
|
|
63
|
+
|
|
64
|
+
The {ruby Process::Metrics::General} struct contains the following fields:
|
|
65
|
+
|
|
66
|
+
- `process_id` - Process ID, a unique identifier for the process.
|
|
67
|
+
- `parent_process_id` - Parent Process ID, the process ID of the process that started this process.
|
|
68
|
+
- `process_group_id` - Process Group ID, the process group ID of the process, which can be shared by multiple processes.
|
|
69
|
+
- `processor_utilization` - Processor Utilization (%), the percentage of CPU time used by the process (over a system-specific duration).
|
|
70
|
+
- `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).
|
|
71
|
+
- `resident_size` - Resident (Set) Size (KB), the amount of physical memory used by the process.
|
|
72
|
+
- `processor_time` - CPU Time (s), the amount of CPU time used by the process.
|
|
73
|
+
- `elapsed_time` - Elapsed Time (s), the amount of time the process has been running.
|
|
74
|
+
- `command` - Command Name, the name of the command that started the process.
|
|
75
|
+
|
|
76
|
+
The {ruby Process::Metrics::Memory} struct contains the following fields:
|
|
77
|
+
|
|
78
|
+
- `map_count` - Number of Memory Mappings, e.g. number of thread stacks, fiber stacks, shared libraries, memory mapped files, etc.
|
|
79
|
+
- `resident_size` - Resident Memory Size (KB), the amount of physical memory used by the process.
|
|
80
|
+
- `proportional_size` - Proportional Memory Size (KB), the amount of memory that the process is using, taking into account shared memory.
|
|
81
|
+
- `shared_clean_size` - Shared Clean Memory Size (KB), the amount of shared memory that is clean (not modified).
|
|
82
|
+
- `shared_dirty_size` - Shared Dirty Memory Size (KB), the amount of shared memory that is dirty (modified).
|
|
83
|
+
- `private_clean_size` - Private Clean Memory Size (KB), the amount of private memory that is clean (not modified).
|
|
84
|
+
- `private_dirty_size` - Private Dirty Memory Size (KB), the amount of private memory that is dirty (modified).
|
|
85
|
+
- `referenced_size` - Referenced Memory Size (KB), active page-cache that isn't going to be reclaimed any time soon.
|
|
86
|
+
- `anonymous_size` - Anonymous Memory Size (KB), mapped memory that isn't backed by a file.
|
|
87
|
+
- `swap_size` - Swap Memory Size (KB), the amount of memory that has been swapped to disk.
|
|
88
|
+
- `proportional_swap_size` - Proportional Swap Memory Size (KB), the amount of memory that has been swapped to disk, excluding shared memory.
|
|
89
|
+
|
|
90
|
+
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/context/index.yaml
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Automatically generated context index for Utopia::Project guides.
|
|
2
|
+
# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
|
|
3
|
+
---
|
|
4
|
+
description: Provide detailed OS-specific process metrics.
|
|
5
|
+
metadata:
|
|
6
|
+
documentation_uri: https://socketry.github.io/process-metrics/
|
|
7
|
+
funding_uri: https://github.com/sponsors/ioquatix
|
|
8
|
+
source_code_uri: https://github.com/socketry/process-metrics.git
|
|
9
|
+
files:
|
|
10
|
+
- path: getting-started.md
|
|
11
|
+
title: Getting Started
|
|
12
|
+
description: This guide explains how to use the `process-metrics` gem to collect
|
|
13
|
+
and analyze process metrics including processor and memory utilization.
|
|
@@ -42,8 +42,8 @@ module Process
|
|
|
42
42
|
self.description = "Display a summary of memory usage statistics."
|
|
43
43
|
|
|
44
44
|
options do
|
|
45
|
-
option "--pid <integer>", "Report on a single process id.", type: Integer
|
|
46
|
-
option "-p/--ppid <integer>", "Report on all children of this process id.", type: Integer
|
|
45
|
+
option "--pid <integer>", "Report on a single process id.", type: Integer
|
|
46
|
+
option "-p/--ppid <integer>", "Report on all children of this process id.", type: Integer
|
|
47
47
|
|
|
48
48
|
option "--total-memory <integer>", "Set the total memory relative to the usage (MiB).", type: Integer
|
|
49
49
|
end
|
|
@@ -112,6 +112,11 @@ module Process
|
|
|
112
112
|
end
|
|
113
113
|
|
|
114
114
|
def call
|
|
115
|
+
# Validate required arguments: at least one of --pid or --ppid must be provided:
|
|
116
|
+
unless @options[:pid] || @options[:ppid]
|
|
117
|
+
raise Samovar::MissingValueError.new(self, "pid or ppid")
|
|
118
|
+
end
|
|
119
|
+
|
|
115
120
|
terminal = self.terminal
|
|
116
121
|
|
|
117
122
|
summary = Process::Metrics::General.capture(pid: @options[:pid], ppid: @options[:ppid])
|
|
@@ -34,12 +34,12 @@ module Process
|
|
|
34
34
|
def self.supported?
|
|
35
35
|
true
|
|
36
36
|
end
|
|
37
|
-
|
|
37
|
+
|
|
38
38
|
# Capture memory usage for the given process IDs.
|
|
39
|
-
def self.capture(
|
|
39
|
+
def self.capture(pid, **options)
|
|
40
40
|
usage = Memory.zero
|
|
41
41
|
|
|
42
|
-
|
|
42
|
+
begin
|
|
43
43
|
File.foreach("/proc/#{pid}/smaps_rollup") do |line|
|
|
44
44
|
if /(?<name>.*?):\s+(?<value>\d+) kB/ =~ line
|
|
45
45
|
if key = SMAP[name]
|
data/readme.md
CHANGED
|
@@ -12,6 +12,63 @@ Please see the [project documentation](https://socketry.github.io/process-metric
|
|
|
12
12
|
|
|
13
13
|
- [Getting Started](https://socketry.github.io/process-metrics/guides/getting-started/index) - This guide explains how to use the `process-metrics` gem to collect and analyze process metrics including processor and memory utilization.
|
|
14
14
|
|
|
15
|
+
## Releases
|
|
16
|
+
|
|
17
|
+
Please see the [project releases](https://socketry.github.io/process-metrics/releases/index) for all releases.
|
|
18
|
+
|
|
19
|
+
### v0.5.1
|
|
20
|
+
|
|
21
|
+
- Fixed Linux memory usage capture to correctly read memory statistics.
|
|
22
|
+
|
|
23
|
+
### v0.5.0
|
|
24
|
+
|
|
25
|
+
- Added `--total-memory` option for scaling memory usage graphs, allowing users to set custom total memory values.
|
|
26
|
+
- Improved support for proportional memory usage (PSS).
|
|
27
|
+
- Exposed total system memory information.
|
|
28
|
+
|
|
29
|
+
### v0.4.0
|
|
30
|
+
|
|
31
|
+
- Fixed command formatting in output display.
|
|
32
|
+
- Modernized codebase to use current Ruby conventions.
|
|
33
|
+
- Improved Darwin (macOS) support with better platform-specific handling.
|
|
34
|
+
|
|
35
|
+
### v0.3.0
|
|
36
|
+
|
|
37
|
+
- Added support for `smaps_rollup` on Linux for more efficient memory statistics collection.
|
|
38
|
+
- Fixed `smaps_rollup` detection (corrected file path).
|
|
39
|
+
- Removed `sz` metric (not supported on Darwin).
|
|
40
|
+
- Expanded test coverage.
|
|
41
|
+
- Improved documentation with better syntax highlighting and fixed links.
|
|
42
|
+
- Avoided abbreviations in naming conventions for better code clarity.
|
|
43
|
+
- Added missing dependencies: `bake-test-external` and `json` gem.
|
|
44
|
+
- Added summary lines for PSS (Proportional Set Size) and USS (Unique Set Size).
|
|
45
|
+
|
|
46
|
+
### v0.2.1
|
|
47
|
+
|
|
48
|
+
- Added missing dependency to gemspec.
|
|
49
|
+
- Added example of command line usage to documentation.
|
|
50
|
+
- Renamed `rsz` to `rss` (Resident Set Size) for consistency across Darwin and Linux platforms.
|
|
51
|
+
|
|
52
|
+
### v0.2.0
|
|
53
|
+
|
|
54
|
+
- Added `process-metrics` command line interface for monitoring processes.
|
|
55
|
+
- Implemented structured data using Ruby structs for better performance and clarity.
|
|
56
|
+
- Added documentation about PSS (Proportional Set Size) and USS (Unique Set Size) metrics.
|
|
57
|
+
|
|
58
|
+
### v0.1.1
|
|
59
|
+
|
|
60
|
+
- Removed `Gemfile.lock` from version control.
|
|
61
|
+
- Fixed process metrics to exclude the `ps` command itself from measurements.
|
|
62
|
+
- Fixed documentation formatting issues.
|
|
63
|
+
|
|
64
|
+
### v0.1.0
|
|
65
|
+
|
|
66
|
+
- Initial release with support for process and memory metrics on Linux and Darwin (macOS).
|
|
67
|
+
- Support for selecting processes based on PID or PPID (process group).
|
|
68
|
+
- Implementation of memory statistics collection using `/proc` filesystem on Linux.
|
|
69
|
+
- Better handling of process hierarchies.
|
|
70
|
+
- Support for older Ruby versions.
|
|
71
|
+
|
|
15
72
|
## Contributing
|
|
16
73
|
|
|
17
74
|
We welcome contributions to this project.
|
data/releases.md
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Releases
|
|
2
|
+
|
|
3
|
+
## v0.5.1
|
|
4
|
+
|
|
5
|
+
- Fixed Linux memory usage capture to correctly read memory statistics.
|
|
6
|
+
|
|
7
|
+
## v0.5.0
|
|
8
|
+
|
|
9
|
+
- Added `--total-memory` option for scaling memory usage graphs, allowing users to set custom total memory values.
|
|
10
|
+
- Improved support for proportional memory usage (PSS).
|
|
11
|
+
- Exposed total system memory information.
|
|
12
|
+
|
|
13
|
+
## v0.4.0
|
|
14
|
+
|
|
15
|
+
- Fixed command formatting in output display.
|
|
16
|
+
- Modernized codebase to use current Ruby conventions.
|
|
17
|
+
- Improved Darwin (macOS) support with better platform-specific handling.
|
|
18
|
+
|
|
19
|
+
## v0.3.0
|
|
20
|
+
|
|
21
|
+
- Added support for `smaps_rollup` on Linux for more efficient memory statistics collection.
|
|
22
|
+
- Fixed `smaps_rollup` detection (corrected file path).
|
|
23
|
+
- Removed `sz` metric (not supported on Darwin).
|
|
24
|
+
- Expanded test coverage.
|
|
25
|
+
- Improved documentation with better syntax highlighting and fixed links.
|
|
26
|
+
- Avoided abbreviations in naming conventions for better code clarity.
|
|
27
|
+
- Added missing dependencies: `bake-test-external` and `json` gem.
|
|
28
|
+
- Added summary lines for PSS (Proportional Set Size) and USS (Unique Set Size).
|
|
29
|
+
|
|
30
|
+
## v0.2.1
|
|
31
|
+
|
|
32
|
+
- Added missing dependency to gemspec.
|
|
33
|
+
- Added example of command line usage to documentation.
|
|
34
|
+
- Renamed `rsz` to `rss` (Resident Set Size) for consistency across Darwin and Linux platforms.
|
|
35
|
+
|
|
36
|
+
## v0.2.0
|
|
37
|
+
|
|
38
|
+
- Added `process-metrics` command line interface for monitoring processes.
|
|
39
|
+
- Implemented structured data using Ruby structs for better performance and clarity.
|
|
40
|
+
- Added documentation about PSS (Proportional Set Size) and USS (Unique Set Size) metrics.
|
|
41
|
+
|
|
42
|
+
## v0.1.1
|
|
43
|
+
|
|
44
|
+
- Removed `Gemfile.lock` from version control.
|
|
45
|
+
- Fixed process metrics to exclude the `ps` command itself from measurements.
|
|
46
|
+
- Fixed documentation formatting issues.
|
|
47
|
+
|
|
48
|
+
## v0.1.0
|
|
49
|
+
|
|
50
|
+
- Initial release with support for process and memory metrics on Linux and Darwin (macOS).
|
|
51
|
+
- Support for selecting processes based on PID or PPID (process group).
|
|
52
|
+
- Implementation of memory statistics collection using `/proc` filesystem on Linux.
|
|
53
|
+
- Better handling of process hierarchies.
|
|
54
|
+
- Support for older Ruby versions.
|
data.tar.gz.sig
CHANGED
|
Binary file
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: process-metrics
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.5.
|
|
4
|
+
version: 0.5.2
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Samuel Williams
|
|
@@ -37,7 +37,7 @@ cert_chain:
|
|
|
37
37
|
Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
|
|
38
38
|
voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
|
|
39
39
|
-----END CERTIFICATE-----
|
|
40
|
-
date:
|
|
40
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
41
41
|
dependencies:
|
|
42
42
|
- !ruby/object:Gem::Dependency
|
|
43
43
|
name: console
|
|
@@ -87,6 +87,8 @@ extensions: []
|
|
|
87
87
|
extra_rdoc_files: []
|
|
88
88
|
files:
|
|
89
89
|
- bin/process-metrics
|
|
90
|
+
- context/getting-started.md
|
|
91
|
+
- context/index.yaml
|
|
90
92
|
- lib/process/metrics.rb
|
|
91
93
|
- lib/process/metrics/command.rb
|
|
92
94
|
- lib/process/metrics/command/summary.rb
|
|
@@ -98,6 +100,7 @@ files:
|
|
|
98
100
|
- lib/process/metrics/version.rb
|
|
99
101
|
- license.md
|
|
100
102
|
- readme.md
|
|
103
|
+
- releases.md
|
|
101
104
|
homepage: https://github.com/socketry/process-metrics
|
|
102
105
|
licenses:
|
|
103
106
|
- MIT
|
|
@@ -112,14 +115,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
|
112
115
|
requirements:
|
|
113
116
|
- - ">="
|
|
114
117
|
- !ruby/object:Gem::Version
|
|
115
|
-
version: '3.
|
|
118
|
+
version: '3.2'
|
|
116
119
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
117
120
|
requirements:
|
|
118
121
|
- - ">="
|
|
119
122
|
- !ruby/object:Gem::Version
|
|
120
123
|
version: '0'
|
|
121
124
|
requirements: []
|
|
122
|
-
rubygems_version: 3.6.
|
|
125
|
+
rubygems_version: 3.6.9
|
|
123
126
|
specification_version: 4
|
|
124
127
|
summary: Provide detailed OS-specific process metrics.
|
|
125
128
|
test_files: []
|
metadata.gz.sig
CHANGED
|
Binary file
|