On-host integrations: Standard configuration format

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.

Configuration file structure

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

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:

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.

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

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.

For more help