Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Report key app statistics to the Librato Metrics service and easily track your own custom metrics
Ruby JavaScript
Pull request Compare This branch is 1 commit ahead, 27 commits behind librato:master.
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status

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


In your Gemfile add:

gem 'metrics-rails'

Then run bundle install.


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:

  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: 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:


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


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

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

Metrics.measure 'jobs.queued', 3


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)


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: 'memcached' do |g|
  g.measure 'gets', 20
  g.measure 'sets', 2
  g.measure 'hits', 18

Symbols can be used interchangably with strings for metric names.


  • 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 (c) 2012 Librato Inc. See LICENSE for details.

Something went wrong with that request. Please try again.