Configure the Infrastructure agent

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

To configure Infrastructure integrations, see the specific integration's documentation.

For more information, check out New Relic University’s tutorial Creating and viewing custom attributes in Infrastructure Or, go directly to the full online course Getting started with Infrastructure.

Configuration management tools

To dynamically create your configuration file and manage the Infrastructure agent with configuration management tools, see the Infrastructure documentation for:

Configuration methods and precedence

The default method to configure the Infrastructure agent is with 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:

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 (newrelic-infra.yml) location and description

To configure the Infrastructure agent, use the 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

Only use environment variables 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. The config options in this document include their corresponding environment variables, labeled as Environ variable.

Using environment variable passthroughs with on-host integrations

You can use environment variables to control config settings for on-host integrations, which can then be passed through to the Infrastructure agent. Variables that can be used with each on-host integration are listed in the documentation for each integration, then you can pass through by using one of the following two options:

  • From inside the config file: add an entry to the Infrastructure agent config file to allow the agent to pick up on the environment variables you've set. Example:

    passthrough_environment:
      - HTTPS_PROXY
      - HTTP_PROXY
  • From the command line: use another environment variable to pass through these settings. Example:

    NRIA_PASSTHROUGH_ENVIRONMENT="HTTPS_PROXY,HTTP_PROXY"

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 with 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
ca_bundle_dir
Type String
Default (none)

If your https_proxy option references to a proxy with self-signed certificates, this option allows you specify the directory where the proxy certificate is available.

The certificates in the directory must end with the .pem extension.

Windows example:

ca_bundle_dir: C:\Certificates

Linux example:

ca_bundle_dir: /etc/my-certificates	
ca_bundle_file
Type String
Default (none)

If your https_proxy option references to a proxy with self-signed certificates, this option allows you specify your proxy certificate file.

For example (Windows):

ca_bundle_file: C:\Certificates\secureproxy.pem

For example (Linux):

ca_bundle_file: /etc/my-certificates/secureproxy.pem
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:

proxy: https://proxy_user:access_10@proxy_01:1080
proxy_validate_certificates

Type Boolean
Default false

If set to true, when the proxy is configured to use an HTTPS connection, it will only work when the HTTPS proxy has certificates from a valid Certificate Authority, or when the ca_bundle_file or ca_bundle_dir configuration properties contain the HTTPS proxy certificates.

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, in case the agent requires to not using an existing system proxy, and connect directly to the New Relic metrics collector.

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 to 1.0.944: the default log location is C:\%APPDATA%\Roaming\New Relic\newrelic-infra\newrelic-infra.log

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

For example:

Using Linux:

log_file: /tmp/nr_debug_log

Using Windows:

log_file: C:\temp\nr-infra.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
replace_v2_loopback_entity_names
Type Boolean (true or false)
Default false

As of Infrastructure agent version 1.2.25 or higher, by default the loopback address replacement on entity names is applied to data received by integrations that use the v3 protocol.

With this option you can enable the replacement for integrations using the v2 protocol:

replace_v2_loopback_entity_names: true

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 YAML config settings. Using environment variables with Infrastructure is ideal for containerized environments. For a containerized version of the Infrastructure agent, see our Docker image.

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_CA_BUNDLE_DIR
Type String
Default (none)

If your NRIA_HTTPS_PROXY option references to a proxy with self-signed certificates, this option allows you specify the directory where the proxy certificate is available.

The certificates in the directory must end with the .pem extension.

For example:

NRIA_CA_BUNDLE_DIR="/etc/my-certificates"
NRIA_CA_BUNDLE_FILE
Type String
Default (none)

If your NRIA_HTTPS_PROXY option references to a proxy with self-signed certificates, this option allows you specify your proxy certificate file.

For example:

NRIA_CA_BUNDLE_FILE="/etc/my-certificates/certificate.pem"
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_PROXY_VALIDATE_CERTIFICATES
Type Boolean
Default false
If set to true, when the proxy is configured to use an HTTPS connection, it will only work when the HTTPS proxy has certificates from a valid Certificate Authority, or when the NRIA_CA_BUNDLE_FILE or NRIA_CA_BUNDLE_DIR configuration properties contain the HTTPS proxy certificates.
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, in case the agent requires to not using an existing system proxy, and connect directly to the New Relic metrics collector.

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

You can use the network interface filters configuration to hide unused or uninteresting network interfaces from the Infrastructure agent. This helps reduce resource usage, work, and noise in your data.

Environment variables are not supported for this configuration setting.

The configuration uses 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. Default lists are available for both Linux and Windows:

Linux

Default network interface filters for Linux:

  • 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

Default network interface filters for Windows:

  • 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: