On-host integrations: Legacy configuration format

New Relic Infrastructure on-host integrations can use one of two types of configuration formats. This document explains the older, legacy configuration format.

Important

New Relic recommends using the new standard improved configuration format. To update your configuration file to this new format, check the update section

For an introduction to configuration, see Config overview.

Configuration file structure

An on-host integration that uses the standard configuration format requires two configuration files:

A definition file
A configuration file

Definition file

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:

Linux:
```
/var/db/newrelic-infra/newrelic-integrations
```

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.nginx
protocol_version: 2
description: Collect metric and configuration data from NGINX
os: linux
commands:
  metrics:
    command:
      - myorg-nginx
      - --metrics
    interval: 15
  inventory:
    command:
      - myorg-nginx
      - --inventory
    interval: 120
    prefix: integration/myorg-nginx

A definition file can be broken down into two parts:

The header
The commands section

Definition file header

Here are explanations of a definition file's header elements:

Definition header field	Description
`name`	Required. A unique name `name` to identify the integration for logging, internal metrics, etc. When the agent loads the config file, New Relic uses the `name` to look up the integration in the agent's registry.
`protocol_version`	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 `2`. For more on protocol changes, see SDK changes.
`description`	Optional. Human-friendly explanation of what the integration does.
`os`	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 `os` value. To restrict the integration to a specific operating system, use either of these options: `linux` `windows`

Definition file commands

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.

Definition commands	Description
`command`	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: `command` arguments: The command and any command line arguments that are shared for all instances of the integration configuration. `command` execution: The command will be executed in the same directory as the definition file. `command` path: Any commands available on the host's `$PATH` can be used. Executables located in the same directory as the definition file, or in a subdirectory of it, can be executed using a relative path. For example: Linux: To run an executable called `myorg-nginx` in the same directory as the definition file, you could use `myorg-nginx` or `./myorg-nginx`. Linux systems will execute `myorg-nginx` as if the user used `./myorg-nginx`. Windows: To run an executable called `myorg-nginx.exe` in the same directory as the definition file, you could use `\myorg-nginx.exe` or `.\myorg-nginx.exe`. Windows systems writing `myorg-nginx.exe` will be executed as if indicating the current path: `.\myorg-nginx.exe`. To use a command installed inside a directory on the host's `$PATH`, simply use the command name. Example: `python`. To run any other executable which is neither on the host's `$PATH` nor within the integration's directory, use an absolute path to the executable. Example: `/opt/jdk/bin/java`. If the given executable name exists within the integration's directory but also exists elsewhere on the system `$PATH`, the version in the integration's directory takes precedence.
`interval`	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. Default for metric polling: 30 seconds. Minimum (floor): 15 seconds. Alerts: For metrics being used for alerts, use an interval of 30 seconds or less.
`prefix`	Optional. The categorization of the inventory in the form of `category/short_integration_name`. Example: `integration/myorg-nginx`. The prefix is not a platform-specific path. The forward slash is the correct separator between the category and `short_integration_name`. The prefix can have a maximum of two levels. Otherwise inventory will not be reported. Default value if not set: `integration/integration_name`.

Definition commands

Description

command

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:

command arguments: The command and any command line arguments that are shared for all instances of the integration configuration.
command execution: The command will be executed in the same directory as the definition file.
command path: Any commands available on the host's $PATH can be used. Executables located in the same directory as the definition file, or in a subdirectory of it, can be executed using a relative path. For example:
- Linux: To run an executable called myorg-nginx in the same directory as the definition file, you could use myorg-nginx or ./myorg-nginx. Linux systems will execute myorg-nginx as if the user used ./myorg-nginx.
- Windows: To run an executable called myorg-nginx.exe in the same directory as the definition file, you could use \myorg-nginx.exe or .\myorg-nginx.exe. Windows systems writing myorg-nginx.exe will be executed as if indicating the current path: .\myorg-nginx.exe.
- To use a command installed inside a directory on the host's $PATH, simply use the command name. Example: python.
- To run any other executable which is neither on the host's $PATH nor within the integration's directory, use an absolute path to the executable. Example: /opt/jdk/bin/java.
If the given executable name exists within the integration's directory but also exists elsewhere on the system $PATH, the version in the integration's directory takes precedence.

interval

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.

Default for metric polling: 30 seconds.
Minimum (floor): 15 seconds.
Alerts: For metrics being used for alerts, use an interval of 30 seconds or less.

prefix

Optional. The categorization of the inventory in the form of category/short_integration_name. Example: integration/myorg-nginx.

The prefix is not a platform-specific path. The forward slash is the correct separator between the category and short_integration_name.

The prefix can have a maximum of two levels. Otherwise inventory will not be reported.

Default value if not set: integration/integration_name.

Configuration file

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:

Linux:
```
/etc/newrelic-infra/integrations.d/
```

Windows:

C:\Program Files\New Relic\newrelic-infra\integrations.d

Tip

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.nginx
instances:
  - name: nginx1.myorg.com-metrics
    command: metrics
    arguments:
      status_url: http://127.0.0.1/status
    labels:
      environment: production
      role: load_balancer

Another example of a config file with two instances defined.

integration_name: com.myorg.nginx
instances:
  - name: nginx1.myorg.com-metrics
    command: metrics
    arguments:
      status_url: http://one.url/status
    labels:
      environment: production
      role: load_balancer
 - name: nginx2.myorg.com-metrics
   command: metrics
   arguments:
     status_url: http://another.url/status
   labels:
     environment: production
     role: load_balancer

Config file field definitions

Config file field	Description
`integration_name`	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.
`name`	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.
`command`	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.
`arguments`	Optional. A YAML object where: Keys: The argument name. Transformed to upper case when set as environment variable. Values: The argument values. Passed through as is. The arguments are made available to an integration as a set of environment variables. Arguments in the config file cannot be capitalised and should use underscores to separate words.
`labels`	Optional. A YAML object where: Keys: The label name. Values: The defined label value.
`integration_user`	Optional. String with the name the agent will use for executing the integration binary. Default: depends on the `usermode`. By default, integrations are executed with the same user that's running the integration agent, nri-agent for privileged and unprivileged mode and root user for root mode. 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 `usermode` different than `root`, just add `integration_user: root` to the configuration file.