In December 2019, Infrastructure agent version 1.8.0 began supporting this new configuration format that makes use of a single configuration file (instead of two separate files), and provides other improvements. This document will explain how this newer format works.
The older legacy configuration format is also supported by current Infrastructure agents.
For an introduction to configuration, see Config overview.
An on-host integration's configuration YAML must have an
integrations top-level section containing a YAML array, where each entry represents an integration and its configuration.
For each integration entry, only the
name property is mandatory. The other properties are optional.
integrations: # New Relic integration that does not require any configuration - name: nri-docker # New Relic integration that gets its configuration from the environment - name: nri-mysql env: PORT: 3306 USERNAME: newrelic PASSWORD: 123456789 # to hide this field, read the secrets management documentation # Any free-form integration executed via a user-provided command - name: my-own-integration exec: python /opt/integrations/my-script.py --host=127.0.0.1
You can have as many configuration YAML files as you want and can group your integration instances.
We recommend linting the YAML configuration files before using them to avoid formatting issues.
This configuration format does not require an agent restart. When saved, changes are detected and implemented immediately. This means that saving intermediate configuration changes may cause the integration to stop working.
This is a list of the general properties used to configure an integration. For more details about using these properties, including example values, see the documentation following the table.
Name of the integration. This is the only mandatory configuration property across all on-host integrations. If the
Optional list of command line arguments when
Full path to the integration executable, plus arguments. It may be a single-line string or a string array. If left unspecified, the
YAML map containing the environment variables to be passed to the integration, where
Configuration that is written as an external file and the path that is passed to the integration with the
Any external file whose path is passed to the integration with the
Name of the user who runs the integration.
Time between consecutive executions of the integration. It must be a number followed by a time unit (
Allows overriding the category and term of the inventory source.
Map with labels that decorate the data (metrics, events, inventory) reported by the integration.
A number followed by a time unit (
Working directory for the integration binary.
Integration is only executed if the clause evaluates to true.
Conditions are defined below.
The remainder of this document describes config properties grouped by their functionality:
- Select an integration to run
- Pass configuration to the integration command
- Configure how the agent executes integrations
There are two properties to select which integration will run:
The only mandatory property across all on-host integrations is
name. The remaining properties specified in this document are optional.
integrations:- name: nri-docker- name: my-integrationexec: /usr/local/bin/my-integration --metrics --inventory
Often integration executables need to receive a configuration to work properly (for example, hostname and port of the monitored system, user credentials, etc.).
The Infrastructure agent allows you to configure the integration commands in three ways (which you can combine):
- Environment variables, using the
- Command-line arguments, passed in the
- Configuration files, whose path needs to be passed through environment variables or command-line arguments (see the config) property.
integrations:- name: my-integrationexec: /opt/path/bin/script --host 127.0.0.1 --port 8081- name: nri-mysqlenv:STATUS_URL: http://10.0.0.3/server-status?autoREMOTE_MONITORING: true
The properties of this section modify the way the Infrastructure agent executes and interacts with the integrations, or the way the agent decorates the integrations' data.
The main difference between these formats is that the older configuration format uses two separate configuration files (a
INTEGRATION_NAME-definition.yml file and a
INTEGRATION_NAME-config.yml file) and the newer version uses a single configuration file.
Here are some of the features added by the newer configuration functionality:
- Flexible configuration via command-line arguments, environment variables, or external files.
- Ability to group different integrations in the same file.
- Hot reload: adding a new integration or changing its configuration does not require restarting the agent.
- Timeouts: if an integration doesn't respond before a user-specified time, the integration process is killed and restarted.
Not all on-host integrations come with the newer configuration format, but you can update the configuration to the new format for all on-host integrations to take advantage of the new features.
The following YAML shows an example Apache integration configuration using the older configuration format. Note that this configuration will still work with newer agents, but we recommend updating your integrations to take full advantage of features.
integration_name: com.newrelic.apacheinstances:- name: apache-server-metricscommand: metricsarguments:status_url: http://127.0.0.1/server-status?autoremote_monitoring: truelabels:env: productionrole: load_balancer- name: apache-server-inventorycommand: inventoryarguments:remote_monitoring: truelabels:env: productionrole: load_balancer
To update an older integration configuration to the new format, use one of the following methods:
Using the New Relic CLI, run the following command to automatically convert your old definition/configuration files to the new configuration format:
$newrelic agent config migrateV3toV4 -d /path/definitionFile -c /path/configFile -o /path/outputFile
To convert the integration file manually:
- Rename the
instancestop-level section to
- Remove the
integration_nametop-level section, and add it to each integration entry. You are no longer required to keep a separate file for each integration type, and you can group your legacy integration entries in the same file as other integrations.
Here's an example of the new version of the Apache integration configuration:
integrations:- name: nri-apacheenv:METRICS: "true"STATUS_URL: http://127.0.0.1/server-status?autoREMOTE_MONITORING: trueinterval: 15slabels:env: productionrole: load_balancer- name: nri-apacheenv:INVENTORY: "true"STATUS_URL: http://127.0.0.1/server-status?autoREMOTE_MONITORING: trueinterval: 60slabels:env: productionrole: load_balancerinventory_source: config/apache
Please note that the older configuration format doesn't support hot reloading. Therefore, you need to restart the Infrastructure agent to remove the old integrations configuration. Otherwise, the old instances will coexist with the new ones.