New Relic Infrastructure on-host integrations can use one of two types of configuration formats. This document explains the older, standard configuration format. This format is used by most on-host integrations and is supported by newer Infrastructure agents (which also support a newer, improved configuration format).
For an introduction to configuration, see Config overview.
An on-host integration that uses the standard configuration format requires two configuration files:
The definition file has a naming format like
INTEGRATION_NAME-definition.yml. This file provides descriptive information about the integration, such as: the version of the JSON protocol it supports, a list of commands it can execute, and arguments that it accepts. It lives in this directory:
Windows:C:\Program Files\New Relic\newrelic-infra\newrelic-integrations
Here's an example of an NGINX integration definition file with two command sections on a Linux system:
name: com.myorg.nginxprotocol_version: 2description: Collect metric and configuration data from NGINXos: linuxcommands:metrics:command:- myorg-nginx- --metricsinterval: 15inventory:command:- myorg-nginx- --inventoryinterval: 120prefix: integration/myorg-nginx
A definition file can be broken down into two parts:
Here are explanations of a definition file's header elements:
Definition header field
Required. A unique name
Required. The version number of the protocol. New Relic uses this to ensure compatibility between the integration and the agent. If the agent does not recognize an integration's version, it will filter out that integration and create a log message.
The current version of the JSON protocol is
Optional. Human-friendly explanation of what the integration does.
Optional. The operating system where the integration runs. New Relic uses this to filter integrations that you intend to run only on specific operating systems.
Default: Run the integration regardless of the
To restrict the integration to a specific operating system, use either of these options:
After the header is a list of commands. The commands section defines:
- One or more independent operating modes for the executable
- The runtime data required for it to be executed
The commands section is a YAML map of command definitions, where each key is the unique alias name of the command in the integration's config file that specifies the executable to run.
Required. The actual command line to be executed as a YAML array of command parts. These are assembled to run the actual command. For simple commands, the array might be only a single element.
Additional command rules include:
Optional. The number of seconds between two consecutive executions of the command, in particular between the end of the previous execution and the start of the next execution.
Optional. The categorization of the inventory in the form of
The prefix is not a platform-specific path. The forward slash is the correct separator between the category and
The prefix can have a maximum of two levels. Otherwise inventory will not be reported.
Default value if not set:
The configuration file has a naming format like
INTEGRATION_NAME-config.yml. This file specifies which executables to run and the parameters required to run them. It lives in this directory:
Windows:C:\Program Files\New Relic\newrelic-infra\integrations.d
We recommend linting the YAML configuration files before using them to avoid formatting issues.
Here's an example of a config file with one instance defined. Explanations of these fields are explained below the example.
integration_name: com.myorg.nginxinstances:- name: nginx1.myorg.com-metricscommand: metricsarguments:status_url: http://127.0.0.1/statuslabels:environment: productionrole: load_balancer
Another example of a config file with two instances defined.
integration_name: com.myorg.nginxinstances:- name: nginx1.myorg.com-metricscommand: metricsarguments:status_url: http://one.url/statuslabels:environment: productionrole: load_balancer- name: nginx2.myorg.com-metricscommand: metricsarguments:status_url: http://another.url/statuslabels:environment: productionrole: load_balancer
Config file field
Required. This is the header and is used to identify which executables to run. This name must exactly match the name specified in the integration's definition file.
Recommendation: To ensure unique names, use reverse domain name notation.
Required. This is the name for the specific invocation (instance) of the integration. This is used to help identify any log messages generated by this integration and is also useful for troubleshooting.
Required. This is the command to be executed. This must exactly match one of the unique alias names specified in the integration's definition file.
Optional. A YAML object where:
Optional. A YAML object where:
Optional. String with the name the agent will use for executing the integration binary.
Default: depends on the
When present, the Infrastructure agent will execute the integration binary as the specified user. For example, to run the integration binary as the root user when running the agent in a
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.