metriks 0.8.1

data/Gemfile

@@ -0,0 +1,7 @@
+source :rubygems
+
+gemspec
+
+group :test do
+  gem 'turn'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2012 Eric Lindvall
+
+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,333 @@
+# Metriks Client
+
+This is an experiment in making a threadsafe, low impact library to measure
+aspects of your ruby.
+
+The library is very much a work-in-progress. It is being developed as
+I find needs while developing [Papertrail](https://papertrailapp.com/).
+
+
+# Installing
+
+Everything is still in flux, so for the time being I have been installing
+the gem from git with bundler. If I get a request, I can definitely start
+releasing a gem.
+
+To install, add this to your `Gemfile`:
+
+    gem 'metriks', :git => 'git://github.com/eric/metriks.git'
+
+and re-run `bundle`.
+
+
+# Metric API Overview
+
+## Counters
+
+Basic atomic counter. Used as an underlying metric for many of the other
+more advanced metrics.
+
+
+### increment(incr = 1)
+
+Increment the counter. Without an argument it will increment by `1`.
+
+``` ruby
+  counter = Metriks.counter('calls')
+  counter.increment
+```
+
+### decrement(decr = 1)
+
+Decrement the counter. Without an argument it will decrement by `1`.
+
+``` ruby
+  counter = Metriks.counter('calls')
+  counter.decrement
+```
+
+#### count()
+
+Return the current value of the counter.
+
+``` ruby
+  counter = Metriks.counter('calls')
+  puts "counter: #{counter.count}"
+```
+
+## Meters
+
+A meter that measures the mean throughput and the one-, five-, and
+fifteen-minute exponentially-weighted moving average throughputs.
+
+### mark(val = 1)
+
+Record an event with the meter. Without an argument it will record one event.
+
+``` ruby
+  meter = Metriks.meter('requests')
+  meter.mark
+```
+
+### count()
+
+Returns the total number of events that have been recorded.
+
+``` ruby
+  meter = Metriks.meter('requests')
+  puts "total: #{meter.count}"
+```
+
+### one_minute_rate()
+
+Returns the one-minute average rate.
+
+``` ruby
+  meter = Metriks.meter('requests')
+  puts "rate: #{meter.one_minute_rate}/sec"
+```
+
+### five_minute_rate()
+
+Returns the five-minute average rate.
+
+``` ruby
+  meter = Metriks.meter('requests')
+  puts "rate: #{meter.five_minute_rate}/sec"
+```
+
+### fifteen_minute_rate()
+
+Returns the fifteen-minute average rate.
+
+``` ruby
+  meter = Metriks.meter('requests')
+  puts "rate: #{meter.fifteen_minute_rate}/sec"
+```
+
+### mean_rate()
+
+Returns the mean (average) rate of the events since the start of the process.
+
+``` ruby
+  meter = Metriks.meter('requests')
+  puts "rate: #{meter.mean_rate}/sec"
+```
+
+## Timers
+
+A timer that measures the average time as well as throughput metrics via
+a meter.
+
+### update(duration)
+
+Records the duration of an operation. This normally wouldn't need to be
+called — the `#time` method is provided to simplify recording a duration.
+
+``` ruby
+  timer = Metriks.timer('requests')
+  t0 = Time.now
+  work
+  timer.update(Time.now - t0)
+```
+
+### time(callable = nil, &block)
+
+Measure the amount of time a proc takes to execute. Takes either a block
+or an object responding to `#call` (normally a `proc` or `lambda`).
+
+``` ruby
+  timer = Metriks.timer('requests')
+  timer.time do
+    work
+  end
+```
+
+If neither a block or an object is passed to the method, an object that
+responds to `#stop` will be returned. When `#stop` is called, the time
+will be recorded.
+
+``` ruby
+  timer = Metriks.timer('requests')
+  t = timer.time
+  work
+  t.stop
+```
+
+### count()
+
+Returns the number of measurements that have been made.
+
+``` ruby
+  timer = Metriks.timer('requests')
+  puts "calls: #{timer.count}"
+```
+
+### one_minute_rate()
+
+Returns the one-minute average rate.
+
+``` ruby
+  meter = Metriks.timer('requests')
+  puts "rate: #{meter.one_minute_rate}/sec"
+```
+
+### five_minute_rate()
+
+Returns the five-minute average rate.
+
+``` ruby
+  meter = Metriks.timer('requests')
+  puts "rate: #{meter.five_minute_rate}/sec"
+```
+
+### fifteen_minute_rate()
+
+Returns the fifteen-minute average rate.
+
+``` ruby
+  meter = Metriks.timer('requests')
+  puts "rate: #{meter.fifteen_minute_rate}/sec"
+```
+
+### mean_rate()
+
+Returns the mean (average) rate of the events since the start of the process.
+
+``` ruby
+  meter = Metriks.timer('requests')
+  puts "rate: #{meter.mean_rate}/sec"
+```
+
+### min()
+
+Returns the minimum amount of time spent in the operation.
+
+``` ruby
+  meter = Metriks.timer('requests')
+  puts "time: #{meter.min} seconds"
+```
+
+### max()
+
+Returns the maximum time spent in the operation.
+
+``` ruby
+  meter = Metriks.timer('requests')
+  puts "time: #{meter.max} seconds"
+```
+
+### mean()
+
+Returns the mean (average) time spent in the operation.
+
+``` ruby
+  meter = Metriks.timer('requests')
+  puts "time: #{meter.mean} seconds"
+```
+
+### stddev()
+
+Returns the standard deviation of the mean spent in the operation.
+
+``` ruby
+  meter = Metriks.timer('requests')
+  puts "time: #{meter.stddev} seconds"
+```
+
+
+## Utilization Timer
+
+A specialized `Timer` that calculates the percentage (between `0.0` and `1.0`) of
+wall-clock time that was spent. It includes all of the methods of `Timer`.
+
+
+### one_minute_utilization()
+
+Returns the one-minute average utilization as a percentage between `0.0` and `1.0`.
+
+``` ruby
+  meter = Metriks.utilization_timer('requests')
+  puts "utilization: #{meter.one_minute_utilization * 100}%"
+```
+
+### five_minute_utilization()
+
+Returns the five-minute average utilization as a percentage between `0.0` and `1.0`.
+
+``` ruby
+  meter = Metriks.utilization_timer('requests')
+  puts "utilization: #{meter.five_minute_utilization * 100}%"
+```
+
+### fifteen_minute_utilization()
+
+Returns the fifteen-minute average utilization as a percentage between `0.0` and `1.0`.
+
+``` ruby
+  meter = Metriks.utilization_timer('requests')
+  puts "utilization: #{meter.fifteen_minute_utilization * 100}%"
+```
+
+### mean_utilization()
+
+Returns the mean (average) utilization as a percentage between `0.0` and `1.0`
+since the process started.
+
+``` ruby
+  meter = Metriks.utilization_timer('requests')
+  puts "utilization: #{meter.mean_utilization * 100}%"
+```
+
+
+# Reporter Overview
+
+How to get metrics out of the process.
+
+## Proc Title Reporter
+
+Provides a simple way to get up-to-date statistics from a process by
+updating the proctitle every 5 seconds (default).
+
+```ruby
+  reporter = Metriks::Reporter::ProcTitle.new :interval => 5
+
+  reporter.add 'reqs', 'sec' do
+    Metriks.meter('rack.requests').one_minute_rate
+  end
+
+  reporter.start
+```
+
+will display:
+
+```
+501      17015 26.0  1.9 416976 246956 ?       Ss   18:54  11:43 thin reqs: 273.3/sec
+```
+
+
+# Plans
+
+An incomplete list of things I would like to see added:
+
+* Rack middleware to measure utilization, throughput and worker time
+* Basic reporters:
+  * Rack endpoint returning JSON
+  * Logger reporter to output metrics on a time interval
+  * [Statsd](https://github.com/etsy/statsd) reporter
+  * [Librato Metrics](http://metrics.librato.com) reporter
+* Metaprogramming instrumentation hooks like [Shopify's statsd-instrument](https://github.com/Shopify/statsd-instrument)
+
+
+# Credits
+
+Most of the inspiration for this project comes from the amazing talk that
+Code Hale gave at CodeConf and his sweet
+[Metrics](https://github.com/codahale/metrics) Java library.
+
+
+# License
+
+Copyright (c) 2012 Eric Lindvall
+
+Published under the MIT License, see LICENSE

data/Rakefile

@@ -0,0 +1,150 @@
+require 'rubygems'
+require 'rake'
+require 'date'
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def rubyforge_project
+  name
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+end
+
+#############################################################################
+#
+# Standard tasks
+#
+#############################################################################
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+desc "Generate RCov test coverage and open in your browser"
+task :coverage do
+  require 'rcov'
+  sh "rm -fr coverage"
+  sh "rcov test/*_test.rb"
+  sh "open coverage/index.html"
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "#{name} #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/#{name}.rb"
+end
+
+#############################################################################
+#
+# Custom tasks (add your own tasks here)
+#
+#############################################################################
+
+
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+desc "Create tag v#{version} and build and push #{gem_file} to Rubygems"
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{name}-#{version}.gem"
+end
+
+desc "Build #{gem_file} into the pkg directory"
+task :build => :gemspec do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+desc "Generate #{gemspec_file}"
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+  #comment this out if your rubyforge_project has a different name
+  replace_header(head, :rubyforge_project)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg)/ }.
+    map { |file| "    #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+desc "Validate #{gemspec_file}"
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts "A `VERSION` file at root level violates Gem best practices."
+    exit!
+  end
+end