Integration executable file specifications

When using the New Relic Infrastructure Integrations SDK to build a custom integration, an integration will consist of at least three files: an executable file, a definition file, and a config file. The executable file generates JSON data that is consumed by the New Relic Infrastructure agent and sent to New Relic.

This document explains the JSON specifications that must be generated by the executable file.

Access to this feature depends on your subscription level.

Executable file requirements

The executable can be any file that runs from a command-line interface. Some examples:

  • A shell script
  • A scripting language script
  • A compiled binary

The only requirement of your executable file is:

  • It exports JSON data, in a single line format, that meets the specifications in this document.

New Relic recommends using Go to create integrations; it is the language New Relic uses to create Infrastructure integrations and the integration building tools. However, you can create an integration in any language.

Example JSON output

The JSON includes:

  • A header, with basic integration data (name, version)
  • A data list, which includes:

    • One or more entities reporting data (metric, inventory, and/or event data)

This diagram shows this structure:

New Relic Integrations SDK data structure diagram

Here is an example JSON output (formatted with line breaks for readability). Definitions and specifications are below this example.

{
  "name": "my.company.integration",
  "protocol_version": "2",
  "integration_version": "x.y.z",  
  "data": [
    {
      "entity": {
        "name": "my_garage",
        "type": "building"
      },
      "metrics": [
        {
          "temperature": 25.3,
          "humidity": 0.45,
          "displayName": "my_garage",
          "entityName": "building:my_garage",
          "event_type": "BuildingStatus"
        }
      ],
      "inventory": {
        "out_door": {
          "status": "open"
        }
      },
      "events": []
    },
    {
      "entity": {
        "name": "my_family_car",
        "type": "car"
      },
      "metrics": [
        {
          "speed": 95,
          "fuel": 768,
          "displayName": "my_family_car",
          "entityName": "car:my_family_car",
          "event_type": "VehicleStatus"
        }
      ],
      "inventory": {
        "motor": {
          "brand": "renault",
          "cc": 1800
        }
      },
      "events": [
        {
          "category": "gear",
          "summary": "gear has been changed"
        }
      ]
    }
  ]
}

JSON: General specifications

Here are general specifications for the JSON output:

Data is emitted to stdout (standard output) in JSON format. The agent will treat stdout and stderr file descriptors as line-wise buffers.

Use standard JSON, not "pretty printed" JSON, for the output. Recommendation: Include an optional command line switch (for example, --pretty) to make JSON "pretty printed" for debugging purposes.

Error and debug information must be emitted to stderr (standard error). Follow New Relic's recommendations and best practices for integration logging.

The exit code must exit with a 0 status code and follow platform-specific conventions. For example:

  • Linux: 0 == EX_OK
  • Windows: 0 == ERROR_SUCCESS

If the executable exits with a non-zero status, the agent will discard any data from stdout and write a message to its log file with the name of the integration, the exit code, and any diagnostic information it can gather.

JSON: Header

Here's an example of the first part of an on-host integration's JSON output:

"name":"com.myorg.nginx",
"protocol_version":"2",
"integration_version":"1.0.0",
"data": [ {entity data}...]

A minimal payload would be a JSON object with only the header fields. Recommendation: If there is no data to collect, use the program return code and log messages written to stderr.

JSON header fields Description
name

Required. Must be identical to the name field in the configuration file.

Recommendation: Use reverse domain names to generate unique integration names.

protocol_version

Required. The version number of the exchange protocol between the integration and the agent that the integration executable is using.

The current version is (2). This protocol requires Infrastructure agent 1.0.859 or higher. Protocol 1 is compatible with all agents. For more on this, see SDK changes.

integration_version

Optional. The integration version. Used to track the integration version running on each host.

An integration can have more than one executable. Therefore this is not simply the executable's version.

data

Required for reporting data. A list containing the data reported from one or more entities.

JSON: Entity data

Inside the data list of the JSON output are one or more entities and their data. The entity entry has two fields:

Entity JSON fields Description
name

Required. The identifier/name of the entity.

Recommendation: Use reverse domain names to generate unique integration names.

type

Required. The kind of entity. It will be used by the Infrastructure agent as a namespace to compose a unique identifier, in conjunction with the name.

JSON: Metric, inventory, and event data

Data values follow the executable file header. You can record three data types:

From the perspective of New Relic Insights, the Infrastructure metrics and events are both classified as event data types. To find both Infrastructure metrics and Infrastructure events, use the Insights Event data explorer, not the Metric data explorer.

Infrastructure metric data typically is used for simple numeric data; for example:

  • Count of MySQL requests in a queue per second
  • Count of active connections to a specific system per minute

Besides associated metadata, a metric is essentially just a metric name and a numeric value. To view this data, use the New Relic Insights Event data explorer.

Here's an example of an entity's metric data JSON:

[ 
    {
         "event_type":"MyorgNginxSample",
         "net.connectionsActive": 54,  # metric data (a key/value pair)
         "net.requestsPerSecond": 21,  # metric data (a key/value pair)
         "net.reading": 23,   # metric data (a key/value pair)
    }
]
JSON metric data field Description
event_type

Required. event_type defines where the metrics will be stored. Each set of metrics is stored as a sample inside the specified event type. Each integration must store its data in its own event type. If you are generating multiple types of samples from the same integration, use different event types for each.

Recommendation: To ensure the event types used by your integration are unique, prefix the event type with your company name or acronym. For example, if your custom integration captures Cassandra node metrics and Cassandra column family metrics as different samples, store them in different event types, such as MyOrgCassandraSample and MyOrgCassandraColumnFamilySample.

If the event type does not exist, it will be created automatically when New Relic receives data from your integration and make it available in Insights.

One or more metric data key/value pairs

Required (at least one). A metric measurement containing a name (key) and its value. Make sure these generally conform to the entity type's specification for maximum compatibility with Infrastructure features.

Recommendation: Prefix your metric with a category to help when navigating through metrics in the New Relic UI. New Relic integrations currently use:

  • net: Number of connections, web server requests, bytes transmitted over the network, etc.; for example, net.connectionsActive.
  • query: Metrics directly related to database queries; for example, query.comInsertPerSecond.
  • db: Internal database metrics; for example, db.openTables.

Use multilevel prefixes for additional grouping when it makes sense; for example, db.innodb.bufferPoolPagesFree

Use the innerCamelCase naming format; for example: net.requestsPerSecond.

Use a metric name as close to the original one as possible while respecting the other specifications. For example:

  • original name: Qcache_hits
  • metric name: db.qCacheHits

Measurement unit: Recommendation: Specify the measurement unit using a unit suffix if it is not already included in the original metric name, as in the following examples:

  • Percentages: Use Percent; for example: cpuUtilPercent.
  • Rates: Use a format such as PerSecond. Seconds is the standard rate measurement, but you can also use other units, such as PerMinute or PerDay.
  • Byte measurements: Use Bytes. Recommendation: If a metric is captured in a different unit, such as Megabytes, convert it to Bytes. For example: db.allMemtablesOffHeapSizeBytes.
  • Time measurements: Use Milliseconds. Recommendation: If a metric is captured in a different unit, such as Seconds, convert it to Milliseconds. For example: query.readLatency50thPercentileMilliseconds

Value: Use a string or a number (integer or float). Strings can be used as associated metadata, allowing data to be filtered in the New Relic UI. A boolean would need to be expressed as either a string ("true", "false") or an integer (1, 0). Do not use complex types of values, such as arrays or hashes.

Infrastructure event data represents arbitrary, one-off messages for key activities on a system; for example:

  • Starting up a specific service
  • Creating a new table

You can view this data in the Infrastructure Events page and Infrastructure events heatmap. You can also query the InfrastructureEvent event type in Insights.

Here's an example of an integration's event data JSON payload, which follows the header JSON, and field definitions.

[
   {
      "summary":"More than 10 request errors logged in the last 5 minutes",
      "category": "notifications"
   }
]
JSON event field Description
summary Required. The message to be sent. Use a simple string.
category Optional. String value of one of the existing categories used in the Infrastructure product, or a new category. The default value is notifications. Examples of categories:
  • applications
  • automation
  • configuration
  • metadata
  • notifications
  • os
  • packages
  • services
  • sessions
  • system
  • users

Infrastructure inventory data captures live state system information; for example:

  • Configuration data
  • System versions installed
  • Other system metadata

You can view this data in the Infrastructure Inventory page and Infrastructure events heatmap. You can also query data related to inventory changes in Insights.

The inventory data type is a hash of one or more JSON sub-objects containing:

  • A unique inventory id key (required): The inventory item's identifier. This is used in combination with the integration's prefix to create a path to the inventory item's data. Like paths combine across entities and show possible variance. This ID points to a hash.
  • A hash of key/value pairs, one per inventory attribute. At least one is required.
  • Keys should be strings.
  • Values may either be a scalar type (string or number) or another hash object of key/values. New Relic supports hierarchy, but the final value nodes must be a scalar.

Here's an example of an integration's inventory data JSON:

{
    "events/worker_connections": {
        "value": 1024
                },
    "http/gzip" : {
        "value": "on"
                }
}

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: