New Relic Flex: Build your own integration

New Relic provides integrations and quickstarts for many popular services and frameworks. If you're already using New Relic and want to report data from a service we don't have an integration for, there are several ways you can create your own integration:

• With infrastructure monitoring, you can use our lightweight Flex tool (recommended, documented below) or, to build a complete on-host integration, see our Integrations SDK.
• For telemetry (metrics, traces) monitoring solutions, use our Telemetry SDKs.
• Build a custom New Relic app that uses your own JavaScript UI functionality.

What is Flex?

New Relic Flex is an application-agnostic, all-in-one tool that allows you to collect metric data from a wide variety of services. It comes bundled with our infrastructure agent. You can instrument any app that exposes metrics over a standard protocol (HTTP, file, shell) in a standard format (for example, JSON or plain text): you create a YAML config file, start the infrastructure agent, and your data is reported to New Relic.

Flex can send event and metric data to New Relic from a wide range of sources. Using a simple YAML config file, you can run HTTP/HTTPS requests, run shell commands, and parse file content. You can also use standard regex expressions to customize and control the data gathered from those inputs. See an example config.

After collecting and cleaning up the data, you can then query Flex data in New Relic, create custom charts for it, and use that data in your dashboards.

Requirements

Flex comes bundled with our infrastructure agent version 1.10.7 or higher (update | check version) running on Linux, Windows, or Kubernetes.

How does Flex work?

Flex uses infrastructure to execute commands that generate the data you want to report. Here's a brief overview of how Flex works to report data:

1. You define the data you want to report in a YAML configuration file, located in the infrastructure agent package. See an example configuration:

   Example config

   The following is an example of a Flex configuration for monitoring the uptime of a Linux server. This configuration is placed in a file named flex-uptime.yml. This would be placed in the infrastructure agent's integration configuration section, located at /etc/newrelic-infra/integrations.d/flex-uptime.yml.

   integrations:
     - name: nri-flex    
       config:
         name: linuxUptimeIntegration
         apis:
           - name: Uptime
             commands:
               - run: 'cat /proc/uptime'
                 split: horizontal
                 split_by: \s+
                 set_header: [uptimeSeconds,idletimeSeconds]

   Copy

   Some notes on what this configuration does:

   • run defines the command to execute.
   • The name indicated by name: Uptime is appended with Sample to generate an event called UptimeSample.
   • The name should not start with the ESX or PCF prefix.
   • The split_by: \s+ splits the fields based on the space character.
   • The command generates attributes attached to the UptimeSample event. The attributes are named uptimeSeconds and idletimeSeconds.

2. The infrastructure agent runs Flex at a frequency based on its own configuration (default: every 30 seconds) and sends the data to New Relic.

3. You can then query your data, create custom charts with it, and add it to dashboards.

Troubleshooting

When you encounter an issue with Flex configuration, first follow these basic troubleshooting steps:

• Test the configuration without the infrastructure agent: You can manually test a config file to ensure the output meets your expectations by running a command like this, replacing <FILE_NAME> with the name of your config file:

# Linux default path: /opt/newrelic-infra/newrelic-integrations/bin/ 
./nri-flex -verbose -pretty -config_path /etc/newrelic-infra/integrations.d/<FILE_NAME>

# Windows default path: C:\Program Files\New Relic\newrelic-infra\newrelic-integrations
.\nri-flex.exe -verbose -pretty -config_path "C:\Program Files\New Relic\newrelic-infra\integrations.d\<FILE_NAME>"

This will give you an output showing debug logging and JSON payload that will be integrated with the infrastucture agent. Make sure Flex is obtaining and formatting your telemetry as expected before continue with the rest of the troubleshooting steps. Learn more about testing Flex configurations from the GitHub repository.

• Test with the infrastructure agent in dry-run mode: Use the dry-run flag in the infrastructure agent to test your Flex configuration. Verify the output contains the telemetry you expect to be reported to New Relic.

• Debug the integration with the infrastructure agent: Finally, ensure the agent is reporting the telemetry data as expected by enabling debug logs in the infrastructure agent.

Learn more

The Flex integration comes bundled with the infrastructure agent, and it can be configured like any other on-host integration. Learn more about configuration options.

See more Flex documentation on GitHub:

• README
• Tutorial