Configure the Infrastructure agent

New Relic Infrastructure includes a configuration file (newrelic-infra.yml) to fine-tune agent behavior. Only the license_key setting is required for the agent to work correctly.

To configure New Relic AWS integrations, see Connect AWS to Infrastructure.

Configuration management tools

To dynamically create your configuration file and manage the Infrastructure agent with configuration management tools, see the Infrastructure documentation on Ansible, Chef, and Puppet.

Configuration methods and precedence

The default method to configure the Infrastructure agent is via the config file (newrelic-infra.yml). However, you can also override the config file by setting environment variables, which is ideal for containerized environments.

Here are detailed descriptions of each configuration method:

Configuration file (newrelic-infra.yml) location and description

The Infrastructure agent is configured via a YAML-formatted file named newrelic-infra.yml. The default location of the file is:

  • Linux: /etc/newrelic-infra.yml
  • Windows: C:\Program Files\New Relic\newrelic-infra\newrelic-infra.yml

For a sample config file, see Infrastructure config file template.

Environment variable syntax and description

Environment variables should only be used with containerized environments. To set an environment variable, use the variable name from the config file in all caps and prefix with NRIA_. For example, NRIA_LICENSE_KEY. Environment variables are also documented below under individual config options as the Environ variable.

infrastructure config cascade (orders of precedence).png
For the Infrastructure agent, environment variables override the config file. The config file overrides the agent defaults.

Configuration file structure

If you edit newrelic-infra.yml, you must conform to the YAML format . Use a YAML validator to ensure the syntax is accurate before using the file with New Relic's Infrastructure agent, and adhere to the following rules:

  • YAML files are case sensitive.
  • All indentations are in similar increments, typically of two space characters. Data in the same stanza of the file must use the same level of indentation. Indent any sub-stanzas by an additional two spaces (see examples in custom attributes and Network Interface Filters).
  • You must restart your agent (newrelic-infra process) for changes to take effect.

Always restart the agent or your web server after changing settings.

General configuration settings

Use these settings or refer to the sample template to configure basic agent behavior.

The default method to configure the Infrastructure agent is via the config file (newrelic-infra.yml). However, you can also override the config file by setting environment variables, which is ideal for containerized environments.

license_key (REQUIRED)
Type String
Default (none)

Specifies the license key for your New Relic account. The agent uses this key to associate your server's metrics with your New Relic account. This setting is created as part of the standard installation process.

For example:

license_key: 1234567890abcdefghijklmnopqrstuvwxyz1234
display_name
Type String
Default (none)

Override the auto-generated hostname for reporting. This is useful when you have multiple hosts with the same name, since Infrastructure uses the hostname as the unique identifier for each host.

For example:

display_name: Tesla One
proxy
Type String
Default (none)

Your system may have firewall rules that require the agent to use a proxy to communicate with New Relic. If so, set the proxy URL in the form https://user:password@hostname:port. Can be HTTP or HTTPS.

HTTPS proxy support was added for Windows since agent release v1.0.956. There is no HTTPS proxy support for Linux at the moment, when proxy option is set with and https:// value the agent will degrade the protocol to plain HTTP.

In order to use an HTTPS proxy, the config option proxy needs to start with `https://` and config must include the certificate file path ca_bundle_file or directory ca_bundle_dir.

For example:

proxy: https://proxy_user:access_10@proxy_01:1080
ignore_system_proxy
Type Boolean (true or false)
Default false

When ignore_system_proxy is set to true, the HTTPS_PROXY and HTTP_PROXY environment variables are ignored, and the unique source of configuration for the proxy is the above proxy or NRIA_PROXY options.

For example:

ignore_system_proxy: true
verbose
Type Integer (0 or 1)
Default 0

When verbose is set to 0, verbose logging is off, but the agent still creates logs. Set this to 1 to create verbose logs to use in troubleshooting the agent.

Verbose logging can generate a lot of data very quickly. Run the agent in verbose mode only for as long as necessary to reproduce your issue, then set verbose: 0 and restart your agent to disable verbose logging.

For example:

verbose: 1
log_file
Type String
Default (none)

To log to another location, provide a full path and file name.

Providing a logfile path that does not yet exist will cause the agent to fail on startup.

When not set, the agent logs to the system log files. Typical default locations:

  • Amazon Linux, CentOS, RHEL: /var/log/messages
  • Debian, Ubuntu: /var/log/syslog
  • Windows Server:

    • Agent versions 1.0.752 and lower: the default log location is C:\Program Files\New Relic\newrelic-infra\newrelic-infra.log

    • Agent versions 1.0.775 and higher: the default log location is C:\%APPDATA%\Roaming\New Relic\newrelic-infra\newrelic-infra.log

For example:

log_file: /tmp/nr_debug_log
log_to_stdout
Type Boolean (true or false)
Default true

When this option is true or not explicitly set, the agent logs to the console, which is typically configured to write to system log files.

If you have a log file set through the log_file option, the agent writes to both the specified file and the console when log_to_stdout is true or not explicitly set. Setting this option to false restricts output to the specified file only.

For example:

log_to_stdout: false
payload_compression
Type Integer (only accepts 0)
Default Unset (enabled by default when unset)

In Infrastructure agent version 1.0.804 or higher, data sent from the agent is compressed by default. New Relic recommends not changing this setting. However, you can disable payload compression by setting the payload_compression_level configuration setting to 0.

To disable payload compression in the config file, add:

payload_compression_level: 0

Custom attributes

Custom attributes are key-value pairs (similar to tags in other tools) used to annotate the data from the Infrastructure agent. You can use this metadata to build filter sets, group your results, and annotate your Insights data. For example, you might indicate a machine's environment (staging or production), the service a machine hosts (login service, for example), or the team responsible for that machine.

The agent collects many details about your environment as part of its default attributes, including Amazon Elastic Compute Cloud (Amazon EC2) tags.

custom_attributes
Type Key-value pairs
Default (none)

A list of custom attributes to annotate the data from this agent instance. Separate keys and values with colons :, as in KEY: VALUE, and separate each key-value pair with a line break. Keys can be any valid YAML except slashes /. Values can be any YAML string, including spaces.

For example:

custom_attributes:
  environment: production
  service: login service
  team: alpha-team

An example using the environment variable:

NRIA_CUSTOM_ATTRIBUTES='{"customAttribute_1":"SOME_ATTRIBUTE","customAttribute_2": "SOME_ATTRIBUTE_2"}'

Environment variables

Environment variables take the highest precedence and override the system properties and yml config settings. Using environment variables with Infrastructure is ideal for containerized environments.

Because Infrastructure environment variables are for containerized environments, using environment variables in other capacities is not supported. This affects different aspects of the way the Infrastructure agent behaves and is not recommended.

NRIA_LICENSE_KEY
Type String
Default (none)

Specifies the license key for your New Relic account. The agent uses this key to associate your server's metrics with your New Relic account. This setting is created as part of the standard installation process.

For example:

NRIA_LICENSE_KEY=1234567890abcdefghijklmnopqrstuvwxyz1234
NRIA_DISPLAY_NAME
Type String
Default (none)

Override the auto-generated hostname for reporting. This is useful when you have multiple hosts with the same name, since Infrastructure uses the hostname as the unique identifier for each host.

For example:

NRIA_DISPLAY_NAME="Tesla One"
NRIA_PROXY
Type String
Default (none)

Your system may have firewall rules that require the agent to use a proxy to communicate with New Relic. If so, set the proxy URL in the form https://user:password@hostname:port. Can be HTTP or HTTPS.

For example:

NRIA_PROXY="https://proxy_user:access_10@proxy_01:1080"
NRIA_IGNORE_SYSTEM_PROXY
Type Boolean (true or false)
Default false

When NRIA_IGNORE_SYSTEM_PROXY is set to true, the HTTPS_PROXY and HTTP_PROXY environment variables are ignored, and the unique source of configuration for the proxy is the above proxy or NRIA_PROXY options.

For example:

NRIA_IGNORE_SYSTEM_PROXY=true
NRIA_VERBOSE
Type Integer (0 or 1)
Default 0

When verbose is set to 0, verbose logging is off, but the agent still creates logs. Set this to 1 to create verbose logs to use in troubleshooting the agent.

Verbose logging can generate a lot of data very quickly. Run the agent in verbose mode only for as long as necessary to reproduce your issue, then set verbose: 0 and restart your agent to disable verbose logging.

For example:

  NRIA_VERBOSE="1"
  
NRIA_LOG_FILE
Type String
Default (none)

To log to another location, provide a full path and file name.

Providing a logfile path that does not yet exist will cause the agent to fail on startup.

When not set, the agent logs to the system log files. Typical default locations:

  • Amazon Linux, CentOS, RHEL: /var/log/messages
  • Debian, Ubuntu: /var/log/syslog
  • Windows Server:

    • Agent versions 1.0.752 and lower: the default log location is C:\Program Files\New Relic\newrelic-infra\newrelic-infra.log

    • Agent versions 1.0.775 and higher: the default log location is C:\%APPDATA%\Roaming\New Relic\newrelic-infra\newrelic-infra.log

For example:

  NRIA_LOG_FILE="/tmp/nr_debug_log"
  
NRIA_LOG_TO_STDOUT
Type Boolean
Default True

When this option is true or not explicitly set, the agent logs to the console, which is typically configured to write to system log files.

If you have a log file set through the log_file option, the agent writes to both the specified file and the console when log_to_stdout is true or not explicitly set. Setting this option to false restricts output to the specified file only.

For example:

NRIA_LOG_TO_STDOUT="false"
NRIA_CUSTOM_ATTRIBUTES
Type String
Default (none)

A list of custom attributes to annotate the data from this agent instance. Separate keys and values with colons :, as in KEY: VALUE, and separate each key-value pair with a line break. Keys can be any valid YAML except slashes /. Values can be any YAML string, including spaces.

For example:

NRIA_CUSTOM_ATTRIBUTES='{"customAttribute_1":"SOME_ATTRIBUTE","customAttribute_2": "SOME_ATTRIBUTE_2"}'

Network Interface Filters

The Network Interface Filters configuration is used to hide unused or uninteresting network interfaces from the Infrastructure agent to reduce resource usage, work, and noise in your data.

Currently the environment variable is not supported for this configuration setting

The configuration makes use of a simple pattern matching mechanism that can look for interfaces that start with a specific sequence of letters or numbers following either pattern:

  • {name}[other characters] where you specify the name using the prefix option.
  • [number]{name}[other characters] where you specify the name using the index-1 option.

New Relic Infrastructure implements a curated default list that you can modify as desired. Default lists are available for both Linux and Windows:

Linux

The default network interface filters for Linux are:

  • Network interfaces that start with dummy, lo, vmnet, sit, tun, tap, or veth.
  • Network interfaces that contain tun or tap.

The following example (added to your configuration file) overrides the default filters. This will ignore network interfaces that start with dummy or lo , or contain tun preceded by a sequence of numbers, and followed by other characters :

network_interface_filters:
  prefix:
    - dummy
    - lo
  index-1:
    - tun
Windows

The default network interface filters for Windows are:

  • Network interfaces that start with Loop, isatap, or Local.

The following example (added to your configuration file) overrides the default filters. This will ignore network interfaces that start with Loop:

network_interface_filters:
  prefix:
    - Loop

For more help

Recommendations for learning more: