Controlling when the Ruby agent starts


The Ruby agent is not properly starting and reporting data to your New Relic dashboard.


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 your New Relic dashboards, 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