Connect hosts to your account

You can control which hosts connect to your account by using environment-specific settings in the New Relic agent configuration file. You can set some configuration properties for all of your environments or modify them for an individual environment. For more information, see the configuration documentation for your agent.

Default settings

Many New Relic customers use a common configuration across multiple environments (for example, staging and production), but they may only run New Relic on hosts in one of those environments. Other customers may have multiple New Relic accounts at different subscription levels, and they need to control which host connects to which accounts. In both of these situations, you can use environment-specific settings.

Default settings for common environments appear at the bottom of the configuration file. Here is an example for production and staging:

New Relic .yml file example: This shows the default settings for production and staging environments.

Customized settings

You can edit these settings as needed. You can also add custom environment sections for unique situations. For example, YAML provides node references ( * ) and hash merges (<<) that refer to a node labeled with an anchor (&) tag. The New Relic agent's default configuration file ships with common configuration options set to the &*default_settings* tag, but you can create your own to share configuration options across environments.

To control which hosts are allowed to connect to your account simply set the '*monitor_mode*' to true or false in the appropriate environment. To have your staging hosts connect to one account and your production hosts connect to another account, set the '*license_key*' in each environment according to how you would like to have them connected. As you can see in the screenshot above, you can also set the '*app_name*' and any other setting you may want specific to a given environment.


The New Relic agent determines the environment where it is running. For example:

  • Ruby: From the standard *RAILS_ENV OS environment variable
  • Java: From a *JAVA_ENV OS environment variable, or from the -Dnewrelic.environment=development system property on the command line

If neither are specified, the default environment is production.

For more help

Join the discussion about New Relic APM 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