• EnglishEspañol日本語한국어Português
  • Log inStart now

On-host integrations: Standard configuration format

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.

Configuration structure

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.

Here's an example configuration featuring two integrations: our built-in Docker integration, which requires no configuration, and our MySQL integration:

  # 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
      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=

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.

Each configuration YAML file can also contain discovery and variables top-level sections.


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.

List of configuration properties

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 exec field is not set it will also be the name of the integration executable.


Optional list of command line arguments when name is used to provide the integration executable. Available since agent version 1.13.0.


Full path to the integration executable, plus arguments. It may be a single-line string or a string array. If left unspecified, the exec field defaults to the name field.


YAML map containing the environment variables to be passed to the integration, where key is the environment variable name, and value is the variable value.


Configuration that is written as an external file and the path that is passed to the integration with the CONFIG_PATH environment variable or the ${config.path} variable placeholder.


Any external file whose path is passed to the integration with the CONFIG_PATH environment variable or the ${config.path} variable placeholder. Its usage allows applying discovery and secrets binding to any external configuration.


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 (s, m or h), without spaces.


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 (ms, s, m or h). An integration that hasn't responded in this time period is killed and restarted.


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

There are two properties to select which integration will run: name and exec.

The only mandatory property across all on-host integrations is name. The remaining properties specified in this document are optional.


- name: nri-docker
- name: my-integration
exec: /usr/local/bin/my-integration --metrics --inventory

Pass configuration to the integration executable

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 env property. (recommended)
  • Command-line arguments, passed in the exec property.
  • Configuration files, whose path needs to be passed through environment variables or command-line arguments (see the config) property.


- name: my-integration
exec: /opt/path/bin/script --host --port 8081
- name: nri-mysql

Configure how the agent executes your integrations

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.

Update older integration configuration

In December 2019, the Infrastructure agent version 1.8.0 began using a different configuration format.

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.apache
- name: apache-server-metrics
command: metrics
remote_monitoring: true
env: production
role: load_balancer
- name: apache-server-inventory
command: inventory
remote_monitoring: true
env: production
role: load_balancer

To update an older integration configuration to the new format, use one of the following methods:

Assisted method

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


Manual method

To convert the integration file manually:

  1. Rename the instances top-level section to integrations.
  2. Remove the integration_name top-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:

- name: nri-apache
METRICS: "true"
interval: 15s
env: production
role: load_balancer
- name: nri-apache
interval: 60s
env: production
role: load_balancer
inventory_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.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.