Controlling when the Ruby agent starts


The Ruby agent is not properly starting, or is not reporting data to New Relic.


To solve this problem:

Check your Ruby agent version.

Check your Ruby agent version, and upgrade if necessary.

Check the app environment used.

When the newrelic_rpm Ruby gem is required in your application environment, it will attempt to determine whether to start monitoring automatically and begin transmitting metrics to New Relic, or to remain disabled.

  • Production and staging: The agent typically is configured to monitor automatically in these environments.
  • Test and development: The agent typically remains disabled in these environments.

To control this logic, set the monitor_mode configuration key to true or false in each environment section of newrelic.yml.

Force the agent to start.

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

NEW_RELIC_AGENT_ENABLED=true rake assets:precompile

Customize the auto-start configuration variables.

If you are running Ruby agent version 3.6.1 or higher, there are a few reasons the agent will refuse to start:

  • The agent detects it is in an interactive session; for example, a rails console or irb session.
  • The agent detects it is in one of Rails' built-in rake tasks; for example, assets:precompile or db:migrate.

You can use configuration variables in your Ruby agent newrelic.yml file to customize auto-start behavior for constants, script names, and rake tasks.

Variable Description
  • 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.
Rake tasks
  • Rake tasks the agent should not monitor; for example, assets:precompile. Accepts a comma separated list.
  • New Relic does not disable the agent in all rake tasks, because tasks like resque:work generally are monitored.
  • A list of script names, such as irb, that will prevent the agent from starting automatically. Accepts a comma separated list.
  • 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

Join the discussion about Ruby in the New Relic Community Forum! The Community Forum is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at