Integration definition file specifications

A New Relic Infrastructure on-host integration built using the Integrations SDK contains at least three files: an executable file, a definition file, and a config file. The definition file is a YAML-format file that provides descriptive information about the integration, such as:

  • What version of the protocol it supports
  • What commands it can execute
  • What arguments that it accepts

This document explains how to create a definition file as part of creating a custom integration.

Access to this feature depends on your subscription level.

Definition file example

Here's an example of a 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
      - myorg-nginx 
      - --metrics
    interval: 15
      - myorg-nginx 
      - --inventory
    interval: 120
    prefix: integration/myorg-nginx

Definition file requirements

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.

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 protocol is 2. For more on protocol changes, see SDK changes.


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

Required. The actual command line to be executed as a YAML array of command parts. These will be 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 go here.
  • 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.


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.

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.

Place and activate integration files

Follow New Relic's procedures to place the integration files and activate the integration.

For more help

Recommendations for learning more: