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 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 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'] || '[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.