Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Metrics for ruby - a Ruby implementation of metrics inspired by @coda's JVM metrics for those of us in Ruby land

branch: reporting_infr…

This branch is 0 commits ahead and 34 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.md

What is this?

This is a Ruby version of performance metrics inspired by metrics developed by Coda Hale at Yammer. Currently this is under heavy development -- it needs Gem packaging, more features, validation of metrics, more functional testing, and a little better test coverage. Pull requests happily accepted, please include docs and tests where possible!

What needs to be done?

Among other important things, this needs to be made more thread-safe. I'm currently looking at Mr. Nutter's ruby-atomic gem for making this less tedious but any suggestions are welcome!

What's in this?

Right now, I have:

  • Counters
  • Meters
  • Gauges
  • Histograms w/ uniform sampling
  • Histograms w/ exponentially decaying sampling
  • Timers

Getting Started

The goal of ruby-metrics is to get up and running quickly. You start an agent, register some instruments, and they're exported over HTTP via JSON. For example, getting started with a counter would look like this:

@metrics = Metrics::Agent.new

counter = @metrics.counter :my_counter
counter.incr
counter.incr

puts @metrics.to_json
#=> {"my_counter":"2"}

Integration

Integrating ruby-metrics into existing applications is entirely up to your needs. Provided options include:

  • Embedded WEBrick listener:

    This runs a background thread and enables HTTP access to a local port (8001 by default) for a JSON representation of the current metrics.

require 'ruby-metrics/integration/webrick'
@agent = Metrics::Agent.new
@agent.start(:port => 8081)
  • Rack Middleware:

    This will add metrics such as requests (a timer) as well as counters for each class of HTTP status code (1xx, 2xx, etc). Also counts uncaught exceptions before reraising. Provides a configurable path option (:show) to trigger the return of the metrics (as JSON) when the request path matches exactly (a string), as a regular expression, or as any object that responds to call for custom logic (passed the whole env).

require 'ruby-metrics'
@agent = Metrics::Agent.new

use Metrics::Integration::Rack::Middleware, :agent => @agent, :show => '/stats'

run app
  • Rack Endpoint:

    Use this to expose an endpoint for external consumption for your metrics. Works best when used with a URLMap or mounted in addition to other routes, like Rails' mount route matcher.

require 'ruby-metrics'
@agent = Metrics::Agent.new

run Metrics::Integration::Rack::Endpoint.new(:agent => @agent)

or

# in config/router.rb
mount Metrics::Integration::Rack::Endpoint.new(:agent => @agent)

License

Copyright 2011 John Ewart john@johnewart.net. Released under the MIT license. See the file LICENSE for further details.

Something went wrong with that request. Please try again.