How do I force the Ruby agent to start?

When the Ruby agent code initializes it needs to determine whether to install instrumentation and start the agent, or remain disabled. When scripts, rake tasks, and consoles start up it's important that the agent not start up and connect to the server for a number of reasons.

The agent does its best to determine if it is running inside a web dispatcher so it can start the agent, but in some cases it may not detect a dispatcher and not start up. The most obvious indication of this is that there is no newrelic_agent.log output. In some cases the application may be running with an undetectable dispatcher (like FastCgi) or you may be running a standalone ruby script or daemon.

In these cases you need to take extra measures to ensure the agent starts. There are several ways to do this, in order of preference:

1. Indicate the dispatcher in an environment variable NEWRELIC_DISPATCHER. Set this variable to the name of the web dispatcher you are using.
   

2. Do a manual start of the agent in the code. This is most often done in background jobs and scripts when you need monitoring turned on. Using the technique you can also pass any option which appears in the newrelic.yml file to override those defaults. Here's an example:

   require 'newrelic_rpm' NewRelic::Agent.manual_start :app_name => 'Nightly Maintenance'

3. Set the environment variable 'NEWRELIC_ENABLE' to true.

4. Set agent_enabled to true in the newrelic.yml file.