You are looking at the README for the master branch of this gem. The latest released version lives in the stable-04 branch, see here for an online version.

influxdb-rails

Automatically instrument your Ruby on Rails applications and write the metrics directly into InfluxDB.

This gem is designed for Rails 4.0+, Ruby 2.2+ and InfluxDB 0.9+.

Install

$ [sudo] gem install influxdb-rails

Or add it to your Gemfile, etc.

Usage

To get things set up, just create an initializer:

$ cd /to/you/rails/application
$ touch config/initializers/influxdb-rails.rb

In this file, you can configure the InfluxDB::Rails adapter. The default config should look something like this:

InfluxDB::Rails.configure do |config|
  config.influxdb_database = "rails"
  config.influxdb_username = "root"
  config.influxdb_password = "root"
  config.influxdb_hosts    = ["localhost"]
  config.influxdb_port     = 8086

  # config.retry = false
  # config.async = false
  # config.open_timeout = 5
  # config.read_timeout = 30
  # config.max_delay = 300
  # config.time_precision = 'ms'

  # config.series_name_for_controller_runtimes = "rails.controller"
  # config.series_name_for_view_runtimes       = "rails.view"
  # config.series_name_for_db_runtimes         = "rails.db"
  # config.series_name_for_exceptions          = "rails.exceptions"
  # config.series_name_for_instrumentation     = "instrumentation"

  # Set the application name to something meaningful, by default we
  # infer the app name from the Rails.application class name.
  # config.application_name = Rails.application.class.parent_name
end

To see all default values, take a look into InfluxDB::Rails::Configuration::DEFAULTS, defined in lib/influxdb/rails/configuration.rb

Out of the box, you'll automatically get reporting of your controller, view, and db runtimes for each request. You can also call through to the underlying InfluxDB::Client object to write arbitrary data like this:

InfluxDB::Rails.client.write_point "events",
  tags:   { url: "/foo", user_id: current_user.id },
  values: { value: 0 }

Additional documentation for InfluxDB::Client lives in the influxdb-ruby repo.

Frequently Asked Questions

Q: I'm seeing far less requests recorded in InfluxDB than my logs suggest.

By default, this gem only sends data points with second time precision to the InfluxDB server. If you experience multiple requests per second, only the last point (with the same tag set) is stored.

See InfluxDB server docs for further details. To work around this limitation, set the config.time_precision to one of "ms" (milliseconds, 1·10^-3s), "us" (microseconds, 1·10^-6s) or "ns" (nanoseconds, 1·10^-9s).

Q: How does the measurement influence the response time?

This gem subscribes to the process_action.action_controller controller notification (via ActiveSupport::Notifications · guide · docs · impl), i.e. it runs after a controller action has finished.

The thread processing incoming HTTP requests however is blocked until the notification is processed. By default, this means calculating and enqueueing some data points for later processing (config.async = true), which usually is negligible. The asynchronuous sending happens in a seperate thread, which batches multiple data points.

If you, however, use a synchronous client (config.async = false), the data points are immediately sent to the InfluxDB server. Depending on the network link, this might cause the HTTP thread to block a lot longer.

Q: How does this gem handle an unreachable InfluxDB server?

By default, the InfluxDB client will retry indefinetly, until a write succeedes (see client docs for details). This has two important implcations, depending on the value of config.async:

if the client runs asynchronously (i.e. in a seperate thread), the queue might fill up with hundrets of megabytes of data points
if the client runs synchronously (i.e. inline in the request/response cycle), it might block all available request threads

In both cases, your application server might become inresponsive and needs to be restarted (which can happen automatically in cgroups contexts).

If you setup a maximum retry value (Integer === config.retry), the client will try upto that amount of times to send the data to the server and (on final error) log an error and discard the values.

Q: What happens with unwritten points, when the application restarts?

The data points are simply discarded.

Q: What happens, when the InfluxDB client or this gem throws an exception? Will the user see 500 errors?

No. The controller instrumentation is wrapped in a rescue StandardError clause, i.e. this gem will only write the error to the client.logger (Rails.logger by default) and not disturb the user experience.

Testing

git clone git@github.com:influxdata/influxdb-rails.git
cd influxdb-rails
bundle
bundle exec rake

Contributing

Fork this repository on GitHub.
Make your changes.
- Add tests.
- Add an entry in the CHANGELOG.md in the "unreleased" section on top.

Run the tests:

Either run them manually:

for gemfile in gemfiles/Gemfile.rails-*.x; do     \
  BUNDLE_GEMFILE=$gemfile bundle install --quiet; \
  BUNDLE_GEMFILE=$gemfile bundle exec rspec;      \
done

or wait for Travis to pick up your changes, after you made a pull request.