memstat 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8ec36521d002d4099ef4e46fb1624da8b15522ac
-  data.tar.gz: 96e5eadf3d6e07bfcf903968a406f2f9fecb8640
+  metadata.gz: 90119832e41e4b1f94fa4d5ed312c21d8b7a152b
+  data.tar.gz: b4b527bfb4596bda0a4597beef32b6fb402a1d2a
 SHA512:
-  metadata.gz: ca72214b5821d4ebad26c842294a32b2977c853442fcf17d69396ea2d982ae7fb71b62c4825be63757edb7d5463cb944fd64a360c164e07b69cabf0cb1d9f809
-  data.tar.gz: 50af05127512b938d5a13f59848566825fb84db649334b35c4f5cf55a289f514fa82780de43174031c14e0c1c67d287021a8361b9a3fea4cfa24e252c2db69d1
+  metadata.gz: 60a9c14475244b516db3eac3f375cb4cbf39161849a91e58949b4cd16ee75f1802a05fd3fa0f593aea0f4a81cda6eb1d59e767cb89ebec7a32589a0db8688709
+  data.tar.gz: c82ce0b893f7ac0b7e3a4f5202fc11e3dcf4b33333104b4e4114dee2c609cbe3f26d836463923d86108d3ca08b17257d5be901f0dbb2670749cf48b5361b88bb

data/README.md

@@ -1,4 +1,4 @@
-# Memstat: Fast memory statistics & Better Out-of-band GC
+# Memstat: Fast memory statistics & better out-of-band GC
 
 Ruby 2.1 introduced generational garbage collection. It is a major improvement in terms of shorter GC pauses and overall higher throughput, but that comes with a [drawback of potential memory bloat](http://www.omniref.com/blog/blog/2014/03/27/ruby-garbage-collection-still-not-ready-for-production/).
 
@@ -10,26 +10,39 @@ If you've ever called the `ps -o rss` command from inside a Ruby process to capt
 
 That's because shelling out `ps` creates an entire copy of the ruby process - typically 70-150MB for a Rails app - then wipe out those memory with the executable of `ps`. Even with copy-on-write and POSIX-spawn optimization, you can't beat the speed of directly reading statistics from memory that is maintained by the kernel.
 
-With a minimal Ruby program, memstat is 10 times faster than `ps -o rss`. The speed diff only gets wider when your Ruby process is bigger.
+For a typical Rails app, memstat is 130 times faster than `ps -o rss`:
+
+```ruby
+Benchmark.bm(10) do |x|
+  x.report("ps:")       { 100.times.each { `ps -o rss -p #{Process.pid}`.strip.to_i } }
+  x.report("memstat:")  { 100.times.each { Memstat::Proc::Status.new(:pid => Process.pid).rss } }
+end
 
-```
                  user     system      total        real
-ps:          0.010000   0.040000   0.160000 (  0.168328)
-memstat:     0.020000   0.000000   0.020000 (  0.017127)
+ps:          0.110000   4.280000   6.260000 (  6.302661)
+memstat:     0.040000   0.000000   0.040000 (  0.048166)
 ```
 
+Tested on [Linode](https://www.linode.com) with a Rails app of 140MB memory usage.
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'memstat'
+```ruby
+gem 'memstat'
+```
 
 Or install it yourself as:
 
-    $ gem install memstat
+```sh
+$ gem install memstat
+```
 
 ## Usage
 
+Check the memory usage, and run GC if it's too big. Note that current version only supports Linux.
+
 ```ruby
 if Memstat.linux?
   status = Memstat::Proc::Status.new(pid: Process.pid)
@@ -47,6 +60,57 @@ require 'memstat'
 use Memstat::OobGC::Unicorn, 150*(1024**2)  # Invoke GC if the process is bigger than 150MB
 ```
 
+Other methods are:
+
+```ruby
+status.peak   # Peak VM size
+status.size   # Current VM size
+status.lck    # mlock-ed memory size (unswappable)
+status.pin    # pinned memory size (unswappable and fixed physical address)
+status.hwm    # Peak physical memory size
+status.rss    # Current physical memory size
+status.data   # Data area size
+status.stk    # Stack size
+status.exe    # Text (executable) size
+status.lib    # Loaded library size
+status.pte    # Page table size
+status.swap   # Swap size
+```
+
+See [details](http://ewx.livejournal.com/579283.html) for each item.
+
+## Commandline
+
+memstat also comes with a command line utility to report detailed memory statistics by aggregating `/proc/[pid]/smaps`.
+
+This is useful to examine the effectiveness of copy-on-write for forking servers like Unicorn.
+
+Usage:
+
+```sh
+$ memstat smaps [PID]
+```
+
+will give you the following result:
+
+```sh
+Process:             13405
+Command Line:        unicorn master -D -E staging -c /path/to/current/config/unicorn.rb
+Memory Summary:
+  size                      274,852 kB
+  rss                       131,020 kB
+  pss                        66,519 kB
+  shared_clean                8,408 kB
+  shared_dirty               95,128 kB
+  private_clean                   8 kB
+  private_dirty              27,476 kB
+  swap                            0 kB
+```
+
+In this case, 103,536 kB out of 131,020 kB is shared, which means 79% of its memory is shared with worker processes.
+
+For more details, [read this gist](https://gist.github.com/kenn/5105175).
+
 ## Contributing
 
 1. Fork it

data/lib/memstat/version.rb

@@ -1,3 +1,3 @@
 module Memstat
-  VERSION = "0.1.0"
+  VERSION = '0.1.1'
 end

data/memstat.gemspec

@@ -4,19 +4,19 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'memstat/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "memstat"
+  spec.name          = 'memstat'
   spec.version       = Memstat::VERSION
-  spec.authors       = ["Kenn Ejima"]
-  spec.email         = ["kenn.ejima@gmail.com"]
-  spec.description   = %q{Fast memory statistics}
-  spec.summary       = %q{Fast memory statistics}
-  spec.homepage      = ""
-  spec.license       = "MIT"
+  spec.authors       = ['Kenn Ejima']
+  spec.email         = ['kenn.ejima@gmail.com']
+  spec.description   = %q{Fast memory statistics and better out-of-band GC}
+  spec.summary       = %q{Fast memory statistics and better out-of-band GC}
+  spec.homepage      = 'https://github.com/kenn/memstat'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files`.split($/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'

data/test/test_memstat.rb

@@ -35,7 +35,6 @@ class TestCli < Minitest::Test
     assert_equal status.hwm,  131044  * 1024
     assert_equal status.rss,  131044  * 1024
     assert_equal status.data, 133064  * 1024
-    assert_equal status.peak, 277756  * 1024
     assert_equal status.stk,  136     * 1024
     assert_equal status.exe,  4       * 1024
     assert_equal status.lib,  21524   * 1024
@@ -46,8 +45,8 @@ class TestCli < Minitest::Test
   def test_benchmark
     n = 100
     Benchmark.bm(10) do |x|
-      x.report("ps:")       { n.times.each { `ps -o rss -p #{$$}`.strip.split.last.to_i } }
-      x.report("memstat:")  { n.times.each { Memstat::Proc::Status.new(:path => STATUS_PATH).rss } }
+      x.report("ps:")       { n.times.each { `ps -o rss -p #{Process.pid}`.strip.split.last.to_i } }
+      x.report("memstat:")  { n.times.each { Memstat::Proc::Status.new(:pid => Process.pid).rss } }
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memstat
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kenn Ejima
@@ -66,7 +66,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Fast memory statistics
+description: Fast memory statistics and better out-of-band GC
 email:
 - kenn.ejima@gmail.com
 executables:
@@ -91,7 +91,7 @@ files:
 - test/files/smaps.txt
 - test/files/status.txt
 - test/test_memstat.rb
-homepage: ''
+homepage: https://github.com/kenn/memstat
 licenses:
 - MIT
 metadata: {}
@@ -114,7 +114,7 @@ rubyforge_project:
 rubygems_version: 2.2.0.rc.1
 signing_key: 
 specification_version: 4
-summary: Fast memory statistics
+summary: Fast memory statistics and better out-of-band GC
 test_files:
 - test/files/smaps.txt
 - test/files/status.txt