---
title: Control when the Ruby agent starts
source: https://docs.newrelic.com/docs/apm/agents/ruby-agent/troubleshooting/control-when-ruby-agent-starts
---
## Problem
The Ruby agent isn't starting or isn't reporting data to New Relic.
## Solution
To solve this problem:
**Check your Ruby agent version.**
Check your [Ruby agent version](https://docs.newrelic.com/docs/release-notes/agent-release-notes/ruby-release-notes), and update 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; for example:
````sh
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** |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Constants | ```` autostart.denylisted_constants ``` * 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 ``` * 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 ``` * 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. ```` |
## Problem
The Ruby agent starts in contexts where I don't want it to start.
## Solution
**Customize your configuration to control when the agent starts**
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`](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#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:*`](https://guides.rubyonrails.org/command_line.html#bin-rails-db) as well as `rails solid_queue:start`, and other Rails commands related to Rake tasks.
- [`autostart.denylisted_executables`](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#autostart-denylisted_executables)
This configuration controls executables, like `rspec` and `irb`.
- [`autostart.denylisted_rake_tasks`](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#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.
**Manually start and stop the agent**
The [`NewRelic::Agent.manual_start`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent#manual_start-instance_method) 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.
````ruby
NewRelic::Agent.manual_start(agent_enabled: true)
```
If you want to stop the agent before the process ends, you can call [`NewRelic::Agent.shutdown`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent#shutdown-instance_method).
````