Controlling when the Ruby agent starts


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


  1. Check your Ruby agent version and environmental factors that may be disabling startup of the agent.

    Ruby agent version earlier than 3.6.1

    If you are running a version of the Ruby agent earlier than 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.

    Ruby agent version 3.6.1 or higher

    If you are running Ruby agent version 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 if it detects it is in one 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.

  2. If neither the agent upgrade nor the version 3.6.1 procedures enable agent startup, you may have to force the agent to start or use configuration variables in newrelic.yml to customize auto-start behaviors.

    Forcing 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
    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.

    Variable Description
    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.


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.

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