Controlling when the Ruby agent starts

When the newrelic_rpm Ruby gem is required into your application environment, it will attempt to determine whether it is appropriate to start automatically and begin monitoring or to remain disabled.

Typically, the agent will be configured to monitor in "production" or "staging" environments, and remain disabled in "test" and "development" environments. This logic can be controlled by setting the monitor_mode configuration key to true or false in each environment section of newrelic.yml. If the agent detects it is in a unmonitored environment (such as test) it will remain disabled.

When the agent determines it is in a monitored environment (such as production) it will typically start automatically and begin transmitting metrics to your New Relic dashboard. There are a few exceptions, like interactive consoles, where the agent will not start automatically. The agent also provides several mechanisms for customizing when the agent will start and when it will remain disabled.

The agent will not start

If you are running a version of the newrelic_rpm gem before 3.6.1, the best thing to do is upgrade. Previous versions of the agent would not start unless they detected a supported web server library, which meant they would refuse to start in many less common configurations.

If you are running newrelic_rpm 3.6.1 or higher, there are a few reasons the agent would refuse to start. If the agent detects it is in an interactive session, for example a rails console or irb session, it will remain disabled. The agent will also refuse to start it detects it is in on of Rails' built in rake tasks, for example assets:precompile or db:migrate. The agent provides a way to configure (via newrelic.yml) what constants, rake tasks, and executable names should prevent the agent from starting.

Forcing the agent to start

To override the agent's auto-start logic, the easiest mechanism is to set a NEWRELIC_AGENT_ENABLED=true environment variable. You can typically do this by envoking a process like this:

NEWRELIC_AGENT_ENABLED=true rake assets:precompile

Using auto-start configurations

There are 3 configuration variables you can use to configure which constants, script names, and rake tasks the agent will assume should not be monitored. These can be put in newrelic.yml to customize autostart behavior.

autostart.blacklisted_constants: Ruby constants that should prevent the agent from starting. Accepts a comma separated list. Defaults to "Rails::Console". Set to "" to convince the agent to start when Rails::Console is in the environment.

autostart.blacklisted_rake_tasks: Rake tasks the agent should not monitor, for example assets:precompile. Accepts a comma separated list. We don't disable the agent in all rake tasks since tasks like resque:work are generally monitored.

autostart.blacklisted_executables: A list of script names, such as irb that will prevent the agent from starting automatically. Accepts a comma separated list. You could set this to "rake" to prevent the agent from starting in rake tasks, or "rake,my_ruby_script.rb" to prevent it from starting in rake and a custom script.

For more help

If you need additional help, get support at