metrics-rails

metrics-rails

Report key statistics for your Rails app to Librato Metrics, easily track your own custom metrics. Currently supports Rails 3.0+.

NOTE: This is currently in alpha development and is not yet officially supported

Installation

In your Gemfile add:

gem 'metrics-rails'

Then run bundle install.

Configuration

If you don't have a Metrics account already, sign up. In order to send measurements to Metrics you need to provide your account credentials to metrics-rails. You can provide these one of two ways:

Create a config/metrics.yml like the following:

production:
  email: <your-email>
  api_key: <your-api-key>
  

OR provide METRICS_EMAIL and METRICS_API_KEY environment variables. If both env variables and a config file are present, environment variables will take precendence.

Note that using a configuration file allows you to specify configurations per-environment. Submission will be disabled in any environment without credentials. However, if environment variables are set they will be used in all environments.

Full information on configuration options is available on the configuration wiki page.

Automatic Measurements

After installing metrics-rails and restarting your app and you will see a number of new metrics appear in your Metrics account. These track request performance, sql queries, mail handling, and other key stats. All built-in performance metrics start with the prefix rails by convention — for example: rails.request.total is the total number of requests received during an interval.

If you have multiple apps reporting to the same Metrics account you can change this prefix in your configuration.

Custom Measurements

Tracking anything that interests you is easy with Metrics. There are four primary helpers available:

increment

Use for tracking a running total of something across requests, examples:

# increment the 'sales_completed' metric by one
Metrics.increment 'sales_completed'

# increment by five
Metrics.increment 'items_purchased', 5

Other things you might track this way: user signups, requests of a certain type or to a certain route, total jobs queued or processed, emails sent or received

measure

Use when you want to track an average value per-request. Examples:

Metrics.measure 'user.social_graph.nodes', 212

Metrics.measure 'jobs.queued', 3

timing

Like Metrics.measure this is per-request, but specialized for timing information:

Metrics.timing 'twitter.lookup.time', 21.2

The block form auto-submits the time it took for its contents to execute as the measurement value:

Metrics.timing 'twitter.lookup.time' do
  @twitter = Twitter.lookup(user)
end

group

There is also a grouping helper, to make managing nested metrics easier. So this:

Metrics.measure 'memcached.gets', 20
Metrics.measure 'memcached.sets', 2
Metrics.measure 'memcached.hits', 18

Can also be written as:

Metrics.group 'memcached' do |g|
  g.measure 'gets', 20
  g.measure 'sets', 2
  g.measure 'hits', 18
end

Symbols can be used interchangably with strings for metric names.

Contribution

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
• Fork the project and submit a pull request from a feature or bugfix branch.
• Please include tests. This is important so we don't break your changes unintentionally in a future version.
• Please don't modify the gemspec, Rakefile, version, or changelog. If you do change these files, please isolate a separate commit so we can cherry-pick around it.

Copyright

Copyright (c) 2012 Librato Inc. See LICENSE for details.