linux_process_memory 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31ab74b4c6400c74e5b44f8e566b3814f4967aad8f6921c243c9d6cc9c8cec6b
+  data.tar.gz: 9fad9bf95d085146dcdb427f09c5a1670e49b65f56c611f726caa2e003ac9d7b
+SHA512:
+  metadata.gz: 34e6e1eb617e34c402355a13441585cb0f8c38bf239da87be5f04257815ef9d4ce1342f4c9ab9c1531fd85247a379ab88d1a040e4b37c3e91293930024147b7e
+  data.tar.gz: 90e4549cb6d9d3428343d7cdc0d4f0e01193b8b5a0b5df626390816367ceff839fd69f9e91c2f25edcc4e48188344b40a6101fe3431e6d141a685b1cc8133db4

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 1.0.0
+
+### Added
+- Initial release.

data/MIT-LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright 2023 Brian Durand
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# Linux Process Memory Ruby Gem
+
+[![Continuous Integration](https://github.com/bdurand/linux_process_memory/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/linux_process_memory/actions/workflows/continuous_integration.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+
+Ruby gem to get a breakdown of the memory being used by a Linux process. It is specific to Linux and will not work on other operating systems even if they are Linux-like (i.e. MacOS, Windows, FreeBSD, etc.). The breakdown takes into account shared memory and swap memory. It is most useful for monitoring memory usage of processes that use shared memory.
+
+If you need similar functionality like this on other platforms, you can use the [get_process_mem gem](https://github.com/zombocom/get_process_mem).
+
+## Usage
+
+Pass in a process pid to get a breakdown of the memory being used by that process.
+
+```ruby
+memory = LinuxProcessMemory.new(1234)
+```
+
+If you don't pass in a pid, it will get the memory for the current process.
+
+```ruby
+memory = LinuxProcessMemory.new
+```
+
+The memory breakdown is captured at the time the object is created. To get the memory breakdown at a different time, create a new object.
+
+Memory is complicated in Linux and there are many different ways to measure it depending on how you want to count shared memory and swap. This gem provides a few different ways to measure memory usage. The following methods are available:
+
+```ruby
+memory = LinuxProcessMemory.new
+memory.total # => total memory used by the process (resident + swap)
+memory.swap # => swap memory used
+memory.shared # => shared memory used
+memory.rss # => resident set size (i.e. non-swap memory allocated)
+memory.resident # same as rss
+memory.pss # => proportional set size (resident size + shared memory / number of processes)
+memory.proportional # same as pss
+memory.uss # => unique set size (resident memory not shared with other processes)
+memory.unique # same as uss
+memory.referenced # => memory actively referenced by the process (i.e. non-freeable memory)
+```
+
+These measurements tend to be the mose useful ones especially if your processes are using shared memory:
+
+- [Resident Set Size](https://en.wikipedia.org/wiki/Resident_set_size)
+- [Proportional Set Size](https://en.wikipedia.org/wiki/Proportional_set_size)
+- [Unique Set Size](https://en.wikipedia.org/wiki/Unique_set_size)
+
+Values are returned in bytes, but you can request different units by passing in an optional argument to indicate the unit. Note that requesting a unit other than bytes will return a `Float` instead of an `Integer`.
+
+```ruby
+memory = LinuxProcessMemory.new
+memory.total(:kb) # => total memory used by the process in kilobytes
+memory.total(:mb) # => total memory used by the process in megabytes
+memory.total(:gb) # => total memory used by the process in gigabytes
+```
+
+This gem is specific to Linux. If you try to use it on a non-Linux platform then memory values will always be returned as -1. If you want to check if the gem is supported on your platform, you can use the `supported?` method.
+
+```ruby
+if LinuxProcessMemory.supported?
+  memory = LinuxProcessMemory.new
+end
+```
+
+### Example
+
+Here's an example of how you might use this gem to collect memory information on your processes by logging resident memory every minute.
+
+```ruby
+if LinuxProcessMemory.supported?
+  logger = Logger.new($stderr)
+  Thread.new do
+    loop do
+      memory = LinuxProcessMemory.new
+      logger.info("Proportional memory: #{memory.pss(:mb).round} MB (pid: #{Process.pid})")
+      sleep(60)
+    end
+  end
+end
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "linux_process_memory"
+```
+
+Then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install linux_process_memory
+```
+
+## Contributing
+
+Open a pull request on [GitHub](https://github.com/bdurand/linux_process_memory).
+
+Please use the [standardrb](https://github.com/testdouble/standard) syntax and lint your code with `standardrb --fix` before submitting.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/linux_process_memory.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+# This class will read the smap files for a process on a Linux system and report
+# the memory usage for that process.
+class LinuxProcessMemory
+  VERSION = File.read(File.expand_path("../VERSION", __dir__)).strip.freeze
+
+  LINUX_MATCHER = /linux/i
+  private_constant :LINUX_MATCHER
+
+  UNIT_CONVERSION = {
+    "bytes" => 1,
+    "kilobytes" => 1024,
+    "megabytes" => 1024 * 1024,
+    "gigabytes" => 1024 * 1024 * 1024,
+    "kb" => 1024,
+    "mb" => 1024 * 1024,
+    "gb" => 1024 * 1024 * 1024,
+    "k" => 1024,
+    "m" => 1024 * 1024,
+    "g" => 1024 * 1024 * 1024
+  }.freeze
+  private_constant :UNIT_CONVERSION
+
+  attr_reader :pid
+
+  class << self
+    # Returns true if the current platform is Linux.
+    #
+    # @return [Boolean]
+    def supported?
+      RUBY_PLATFORM.match?(LINUX_MATCHER)
+    end
+  end
+
+  # Create a memory snapshot for the specified process.
+  #
+  # @param pid [Integer] The process ID to snapshot. Defaults to the current process.
+  def initialize(pid = Process.pid)
+    @pid = pid
+    @stats = (self.class.supported? ? read_smaps : Hash.new(-1))
+  end
+
+  # Returns the total memory usage for the process.
+  #
+  # @param units [Symbol] The units to return the memory usage in.
+  #   Valid values are :bytes, :kilobytes, :megabytes, :gigabytes, :kb, :mb, :gb, :k, :m, :g.
+  #   Defaults to :bytes.
+  # @return [Numberic]
+  def total(units = :bytes)
+    convert_units(@stats[:Rss] + @stats[:Swap], units)
+  end
+
+  # Returns the resident set size for the process.
+  #
+  # @param units [Symbol] The units to return the memory usage in.
+  #   Valid values are :bytes, :kilobytes, :megabytes, :gigabytes, :kb, :mb, :gb, :k, :m, :g.
+  #   Defaults to :bytes.
+  # @return [Numberic]
+  def rss(units = :bytes)
+    convert_units(@stats[:Rss], units)
+  end
+
+  alias_method :resident, :rss
+
+  # Returns the proportional set size for the process.
+  #
+  # @param units [Symbol] The units to return the memory usage in.
+  #   Valid values are :bytes, :kilobytes, :megabytes, :gigabytes, :kb, :mb, :gb, :k, :m, :g.
+  #   Defaults to :bytes.
+  # @return [Numberic]
+  def pss(units = :bytes)
+    convert_units(@stats[:Pss], units)
+  end
+
+  alias_method :proportional, :pss
+
+  # Returns the uniq set size for the process.
+  #
+  # @param units [Symbol] The units to return the memory usage in.
+  #   Valid values are :bytes, :kilobytes, :megabytes, :gigabytes, :kb, :mb, :gb, :k, :m, :g.
+  #   Defaults to :bytes.
+  # @return [Numberic]
+  def uss(units = :bytes)
+    convert_units(@stats[:Private_Clean] + @stats[:Private_Dirty], units)
+  end
+
+  alias_method :unique, :uss
+
+  # Returns the swap used by the process.
+  #
+  # @param units [Symbol] The units to return the memory usage in.
+  #   Valid values are :bytes, :kilobytes, :megabytes, :gigabytes, :kb, :mb, :gb, :k, :m, :g.
+  #   Defaults to :bytes.
+  # @return [Numberic]
+  def swap(units = :bytes)
+    convert_units(@stats[:Swap], units)
+  end
+
+  # Returns the shared memory used by the process.
+  #
+  # @param units [Symbol] The units to return the memory usage in.
+  #   Valid values are :bytes, :kilobytes, :megabytes, :gigabytes, :kb, :mb, :gb, :k, :m, :g.
+  #   Defaults to :bytes.
+  # @return [Numberic]
+  def shared(units = :bytes)
+    convert_units(@stats[:Shared_Clean] + @stats[:Shared_Dirty], units)
+  end
+
+  # Returns the referenced memory size for the process (i.e. memory that is actively being used)
+  # that cannot be reclaimed.
+  #
+  # @param units [Symbol] The units to return the memory usage in.
+  #   Valid values are :bytes, :kilobytes, :megabytes, :gigabytes, :kb, :mb, :gb, :k, :m, :g.
+  #   Defaults to :bytes.
+  # @return [Numberic]
+  def referenced(units = :bytes)
+    convert_units(@stats[:Referenced], units)
+  end
+
+  private
+
+  def read_smaps
+    stats = Hash.new(0)
+    return stats unless File.exist?(smap_rollup_file)
+
+    data = File.read(smap_rollup_file).split("\n")
+    data.shift # remove header
+    data.each do |line|
+      key, value, unit = line.split
+      key = key.chomp(":").to_sym
+
+      multiplier = UNIT_CONVERSION.fetch(unit.to_s.downcase, 1)
+      numeric_value = (value.to_f * multiplier).round
+      stats[key] += numeric_value if numeric_value > 0
+    end
+
+    stats
+  end
+
+  def convert_units(value, units)
+    return -1 if value < 0
+
+    divisor = UNIT_CONVERSION[units.to_s.downcase]
+    raise ArgumentError.new("Unknown units: #{units}") unless divisor
+
+    return value if divisor == 1
+
+    value.to_f / divisor
+  end
+
+  def smap_rollup_file
+    "/proc/#{pid}/smaps_rollup"
+  end
+end

data/linux_process_memory.gemspec

@@ -0,0 +1,35 @@
+Gem::Specification.new do |spec|
+  spec.name = "linux_process_memory"
+  spec.version = File.read(File.expand_path("../VERSION", __FILE__)).strip
+  spec.authors = ["Brian Durand"]
+  spec.email = ["bbdurand@gmail.com"]
+
+  spec.summary = "Get a breakdown of the memory being used by a Linux process including resident, shared, private, and swap memory."
+
+  spec.homepage = "https://github.com/bdurand/linux_process_memory"
+  spec.license = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  ignore_files = %w[
+    .
+    Appraisals
+    Gemfile
+    Gemfile.lock
+    Rakefile
+    config.ru
+    assets/
+    bin/
+    gemfiles/
+    spec/
+  ]
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.5"
+
+  spec.add_development_dependency "bundler"
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: linux_process_memory
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brian Durand
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-08-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- bbdurand@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE.txt
+- README.md
+- VERSION
+- lib/linux_process_memory.rb
+- linux_process_memory.gemspec
+homepage: https://github.com/bdurand/linux_process_memory
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: Get a breakdown of the memory being used by a Linux process including resident,
+  shared, private, and swap memory.
+test_files: []