Integration executable file specifications

A New Relic Infrastructure integration contains at least three files: an executable file, a definition file, and a config file. The executable file generates the data sent to New Relic. This document explains how to create an executable file as part of creating your own custom integration. For more information, see the integration example, which includes executable files.

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; for example:

  • Shell script
  • Scripting language script
  • Compiled binary

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

Make sure your executable file meets these requirements:

  • The executable file must export JSON data that meets the specifications in this document.
  • The payload must be in a single line format.

This JSON example contains two parts:

This example shows the format of an executable's JSON output recording all three types of data. For readability, this output example is separated into individual lines ("pretty printed").

{
    "name": "com.myorg.nginx",
    "protocol_version": "1",
    "integration_version": "1.0.0",
    "metrics": [{
        "event_type": "MyorgNginxSample",
        "net.connectionsActive": 54,
        "net.requestsPerSecond": 21,
        "net.connectionsReading": 23
    }],
    "inventory": {
        "events/worker_connections": {
            "value": 1024
        },
        "http/gzip": {
            "value": "on"
        }
    },
    "events": [{
        "summary": "More than 10 request errors logged in the last 5 minutes",
        "category": "notifications"
    }]
}

General specifications

Here are general specifications for the executable 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.

Executable file header

Here's an example of an executable's JSON header output and field definitions.

"name":"com.myorg.nginx",
"protocol_version":"1",
"integration_version":"1.0.0",

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.

Executable header field 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.

Currently there is only one version (1). If new versions are introduced, protocol_version will be used to ensure backwards compatibility.

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.

Executable file data

Data values follow the executable file header. You can record three Infrastructure data types with an integration:

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 metric data JSON output, which follows the header JSON, and field definitions.

[ 
    {
         "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)
    }
]
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"
   }
]
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 payload, which follows the header JSON, and field definitions.

{
    "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: