Configuration Version 1.x

Note: Wiki covers configuration for version 1.x. For version 2.x configuration, please visit Configuration.

There are two primary ways to configure librato-rails. You can either use a yaml-based config file, environment variables, or a combination of the two.

When using a config file you configure each environment separately. Environment variables differ in that they will be used by all environments when present.

Config file

To use a config file, create a file named librato.yml in the config directory of your rails project. Here's a sample config file:

production:
  user: 'foo@bar.com'
  token: 'api key'

staging:
  user: 'foo@bar.com'
  token: 'api key'
  prefix: 'staging'

The following options can be set per environment in config files:

• user - the email address of your Librato Metrics account
• token - the api key of your Librato Metrics account
• source - the source metrics will be reported from (default: machine hostname). If you are overriding this you likely want to set it to a different value per host or host group.
• source_prefix - an optional prefix that is prepended to all source names reported by librato-rails. An additional gem is require for this to function properly.
• prefix - an optional prefix which will be attached to all metric names reported by librato-rails. For example, if the prefix is set to foo, rails.request.total will be reported as foo.rails.request.total.
• suites - specify which metrics librato-rails will report. See more in Metric Suites
• proxy - HTTP proxy to use when connecting to the Librato API.
• log_level - useful for debugging, default level is info, available levels are [off, error, warn, info, debug, trace].
• flush_interval - how often aggregated metrics will be sent, in seconds (default: 60). Useful in local debugging to force more frequent flushes. Don't use this in production - it will not give you more frequent data on Metrics, but it may affect performance of your application.

Environment variables

• LIBRATO_USER - the email address of your Librato Metrics account
• LIBRATO_TOKEN - the api key of your Librato Metrics account
• LIBRATO_SOURCE - the default source metrics will be reported from
• LIBRATO_PREFIX - optional prefix, see prefix above
• LIBRATO_SUITES - specify which metrics librato-rails will report. See more in Metric Suites
• LIBRATO_PROXY - HTTP proxy to use when connecting to the Librato API (can also use the https_proxy or http_proxy environment variable commonly supported by Linux command line utilities).
• LIBRATO_LOG_LEVEL - useful for debugging, see above
• LIBRATO_AUTORUN - if set to '0', forces librato-rails not to start, see more below

Note that most environment variables will be ignored if a librato.yml file is present. For convenience LIBRATO_LOG_LEVEL and LIBRATO_AUTORUN will override values specified in a librato.yml file.

Heroku users: If you are using the Librato Heroku add-on, the LIBRATO_USER and LIBRATO_TOKEN will be automatically set already in your environment.

More about LIBRATO_AUTORUN

LIBRATO_AUTORUN was introduced in v0.10 and controls two related behaviors.

If set to 0 it will prevent the librato-rails reporter from starting. Instrumentation classes/methods will still be available for convenience, but nothing will ever be sent to Librato.

If set to 1 it will force the reporter to start immediately, instead of waiting for the process to receive a request. This can be useful with some kinds of background workers which won't report otherwise. However, be sure not to use this setting with normal rails web processes! Reporting will be broken because it is forced to start before the web-serving environment is fully loaded.

See Monitoring Background Workers for more information about using LIBRATO_AUTORUN with workers.

Combining config files and environment variables

If you want to use a librato.yml file but still have the versatility of environment variables for setting some features per-environment, you can include environment variables in your config file using erb. For example:

production:
  user: <%= ENV['LIBRATO_USER'] %>
  token: <%= ENV['LIBRATO_TOKEN'] %>

development:
  user: <%= ENV['LIBRATO_USER'] || 'devuser@mysite.com' %>
  token: <%= ENV['LIBRATO_TOKEN'] || 'mydevtoken' %>

Note that you can use any environment variables you wish in this fashion, you are not locked into the standard variables that librato-rails would look for if it was inspecting the environment for configuration.