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: '[email protected]'
  token: 'api key'

staging:
  user: '[email protected]'
  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.
• 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.
• 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_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, but it will break reporting for processes that receive web requests (normal rails processes) because reporting will start before the environment is fully loaded. More information is available in Monitoring Background 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'] || '[email protected]' %>
  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.