Build a custom visualization for dashboards

Building your own visualizations for New Relic dashboards enables you and your organization to query data from any source and display it on your dashboard. In this guide, you'll learn how to use the CLI to generate a visualization file structure, run it locally where you can quickly test and iterate, and then deploy it for use in a dashboard.

Before you begin

To get started, make sure you have a New Relic account.

To complete this guide, you need the New Relic One CLI (command line interface). If you haven't already installed it, do the following:

Install Node.js.
Complete all the steps in the CLI quick start.

Create a new visualization

In this first set of steps you will use the CLI to quickly generate the boilerplate for a new visualization.

Step 1 of 3

Ensure you're working with the latest version of the New Relic One CLI:

bash

$nr1 update

Step 2 of 3

Start with a new Nerdpack. If you just installed the New Relic One CLI, then you have a new Nerdpack project directory (called something like my-awesome-nerdpack). If you need to create one, run nr1 create and select the nerdpack option.

bash

$nr1 create --type nerdpack --name my-awesome-nerdpack

Tip

Note: If you only want to build a visualization in your Nerdpack, you can remove the nerdlets/ and launchers/ folders from the nerdpack

Step 3 of 3

Navigate to the root of your Nerdpack project and run the nr1 create command, selecting the visualization option.

bash

$cd my-awesome-nerdpack
$nr1 create --type visualization --name my-awesome-visualization

As a result, you have a new visualization directory matching the name you gave your visualization. It is located in the visualizations directory in the root of your Nerdpack project.

The files created provide an example visualization – a radar chart populated by a basic NRQL query.

The nr1.json file provides metadata. The configuration key in this metadata defines the prop-input fields to be shown in the UI. These are the fields users will fill in to create an instance of the visualization. Supported input types are:

boolean
string
number
json
enum: a developer-defined list of string options.
nrql: a single NRQL query string.
namespace: a group of input fields to be displayed together under a shared heading in the prop-editing UI.
collection: a repeatable group of input fields to be displayed together under a shared heading in the prop-editing UI. The nrqlQueries entry is an example of a collection type.

The index.js file is where you define the React component that receives the props and renders the visualization. You can install and import any JavaScript libraries you find useful. The example component imports Recharts, a library that wraps D3 submodules for easy-to-compose visualizations.

If your visualization queries data over a time range and you want it to utilize the platform time range setting, you will need to utilize the timeRange value from PlatformStateContext. The timeRange can be passed directly to the NrqlQuery component. Setting the NrqlQuery component's pollInterval prop to NrqlQuery.AUTO_POLL_INTERVAL automatically handles calculating an appriate data polling interval.

<PlatformStateContext.Consumer>
  {({timeRange}) => (
    <NrqlQuery
      timeRange={timeRange}
      pollInterval={NrqlQuery.AUTO_POLL_INTERVAL}
    >
      ...

Render the visualization in local development

Now run the generated visualization locally, and view it in Custom Visualizations. There you can quickly test changes to your code.

Step 1 of 7

Start the local Node server for your Nerdpack.

bash

$nr1 nerdpack:serve

Important

To see changes to the nr1.json file take effect, restart the local Node server. Changes to the definition of the configuration field will not show up in the prop configuration side bar of the Custom Visualizations UI until you stop the local Node server and start it back up.

Step 2 of 7

In a browser, open https://one.newrelic.com/?nerdpacks=local. This url is also shown in the terminal when the Node server starts. The nerdpacks=local query string will direct the UI to load your new visualization artifact from the local Node server.

Advanced nerdpack configuration

See the advanced nerdpack configuration section for detailed information about how your local Node server is proxied to the browser and how you can override webpack configuration if needed.

Step 3 of 7

Open the Apps page, and navigate to Custom Visualizations, which you will find favorited by default.

Apps navigation is located in the New Relic One top navigation

Step 4 of 7

In the Custom Visualizations listing, find and click on the tile for your visualization. If the tile is not showing up or it is not indicating that it is running locally, restart the Node server and refresh the browser.

When you select your locally running visualization, the visualization hosted by your local Node server is rendered with prop-configuration inputs. Here you can take advantage of the features outlined in the following steps.

Step 5 of 7

You can set prop values and see the visualization update automatically. The prop inputs are listed as defined in the prop definitions located in the nr1.json file in the visualization folder (for example ./visualizations/my-awesome-visualization/nr1.json). Fill in values for the props and see the visualization update automatically. As you change props in the sidebar, a render cycle of your visualization's React component is triggered.

Generated visualization rendered in the Visualization Builder

Step 6 of 7

Modify the visualization's Javascript code and see the result automatically update in the UI. For example, you can change the value for fillOpacity on the Radar component in index.js. Upon save, you will see the page automatically update.

fillOpacity={1.0}

visualizations/your-visualization/index.js

Step 7 of 7

To add more props, you must update the configuration field in the nr1.json file for your visualization and restart the local Node server. The props you define in the configuration field allow New Relic One to cleanly display a prop-editing UI for users interacting with your visualization. See above for more information about the configuration field.

Deploy and use your visualization

When your visualization is ready to be added to a dashboard, just follow these steps.

Step 1 of 2

Open and follow the guide to publish and deploy the Nerdpack to New Relic One and subscribe accounts to it.

Step 2 of 2

Then you can add your visualization to a dashboard.

Summary

Congratulations on completing the steps in this example! You've learned how to:

Create a visualization and run it locally
Quickly test and iterate on visualization code changes in Custom Visualizations
Deploy a visualization
Add a custom visualization to a dashboard

Additional resources

New Relic Quick Tips video: Dashboards and Custom Visualizations (6 minutes)
New Relic NerdBytes video: Configuring custom visualizations for dashboards (7 minutes)
New Relic Nerdlog live stream: Custom Data Visualizations on New Relic (30 minutes)