Control when the Ruby agent starts

Check your Ruby agent version, and update if necessary.

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.

To override the agent's auto-start logic, the easiest mechanism is to set a NEW_RELIC_AGENT_ENABLED=true environment variable; for example:

NEW_RELIC_AGENT_ENABLED=true rake assets:precompile

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
  Constants	autostart.denylisted_constants Copy Ruby constants that should prevent the agent from starting. Accepts a comma separated list. Defaults to "Rails::Console". Set to "" to tell the agent to start when Rails::Console is in the environment.
  Rake tasks	autostart.denylisted_rake_tasks Copy Rake tasks you do not want the agent to monitor; for example, assets:precompile. Accepts a comma-separated list. We do not disable the Ruby agent in all rake tasks, because tasks like resque:work generally are monitored.
  Executables	autostart.denylisted_executables Copy 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.

The Ruby agent makes some assumptions about the contexts most customers want the agent to automatically start.

There are three configuration options available to customize this behavior:

• autostart.denylisted_constants Most of the constants on this list are Rails commands that perform operations that rarely benefit from monitoring.

  The list doesn't include Rails::Command::RakeCommand, which powers commands like rails db:* as well as rails solid_queue:start, and other Rails commands related to Rake tasks.

• autostart.denylisted_executables This configuration controls executables, like rspec and irb.

• autostart.denylisted_rake_tasks Prior to Rails 5.1, rake was used instead of thor for many commands, such as db:migrate. The default values for this configuration lists many commands from that time. You can also add your own rake commands to this list.

The NewRelic::Agent.manual_start API can be used to start the agent in specific contexts. If you set :agent_enabled to false in your configuration file or set the environment variable NEW_RELIC_AGENT_ENABLED=false, you can still manually start the agent using this API.

NewRelic::Agent.manual_start(agent_enabled: true)

If you want to stop the agent before the process ends, you can call NewRelic::Agent.shutdown.