• /
  • EnglishEspañol日本語한국어Português
  • Log inStart now

Customize open-source Nerdpacks

Most Nerdpacks in the Instant Observability catalog are open-source. This means you can clone or fork their repositories, customize them to suit your specific needs, and re-publish them to use with your account. In this guide, you customize a Nerdpack with visualizations and publish it to your account. However, to customize any Nerdpack, you follow the same steps.

Before you begin

If you haven't already:

View a Nerdpack

Subscribe to the Victory Charts Visualizations Nerdpack and open the Circular progress bar visualization in New Relic.

Go to one.newrelic.com > All capabilities > Apps.

Click the Victory Charts Visualizations Nerdpack in the catalog.

Add Victory Charts Visualizations to your account.

Go to one.newrelic.com > All capabilities > Apps, open Custom visualizations.

From the list of visualizations in Custom visualizations click Circular progress bar, which you installed as part of the Victory Charts Visualizations Nerdpack.

Under Configure visualization properties, select your account and enter a NRQL query.

Now you see a circular chart that shows a percentage based on your query.

Tip

Read our documentation for instructions on how to configure the progress bar visualization.

Notice a few things about this visualization:

  • You don't control the color of the chart

  • The sections of the chart have rounded edges

    For the sake of this tutorial, imagine this chart represents your data exactly how you want it to, except for two things. You'd like to use straight edges and control the chart's colors manually. In the real world you may come across Nerdpacks like this where you like what they offer, but you'd like them better if you could tweak them. Well, you can tweak them, and next, you'll learn how!

Because you're going to use a tweaked version of the Victory Charts Visualizations Nerdpack instead of the one you subscribed to, you can unsubscribe from our version now.

Clone a Nerdpack

Find the source code repository from the Nerdpack's catalog entry and clone it to your local machine.

In the UI, go to + Integrations & Agents.

Click the Victory Charts Visualizations Nerdpack in the catalog.

Go to the Nerdpack's source code repository.

All open-source Nerdpacks in the catalog have links to their source code in their catalog information.

Clone the repository:

bash
$
nr1 nerdpack:clone -r https://github.com/newrelic/nr1-victory-visualizations.git

Now you have a local version of the Victory Charts Visualizations Nerdpack! Notice that you used nr1 nerdpack:clone instead of git clone to copy the repo. nr1 nerdpack:clone offers built-in functionality to help keep your local copy distinct from the original Nerdpack in the Instant Observability public catalog. Specifically, it generates a new Nerdpack UUID so you don't have to do this yourself:

bash
Re-generating UUID...
Committing new UUID...

If you change to the nr1-victory-visualizations directory, and look at the git log, you'll see the new commit:

bash
$
git log -1 -p
commit e356bb5b10c3ecc8f93bae66d5739e1676ee21ef (HEAD -> main)
Author: New Relic CLI <nr1@newrelic.com>
Date:   Tue May 25 14:29:37 2021 -0400
    "chore: Auto-generated UUID"
diff --git a/nr1.json b/nr1.json
index 054de52..7a107b5 100644
--- a/nr1.json
+++ b/nr1.json
@@ -1,6 +1,6 @@
 {
   "schemaType": "NERDPACK",
-  "id": "cf5f13d9-815f-4907-a21d-83d02fa2a4fb",
+  "id": "ab123c45-678d-9012-efg3-45hi6jkl7890",
   "displayName": "Victory charts visualizations",
   "description": "Visualizations built on top of Victory charts"
 }

In nr1-victory-visualizations/nr1.json, change your Nerdpack's displayName:

{
  "schemaType": "NERDPACK",
  "id": "269055dd-67e8-4713-8da3-bff01c6a8687",
  "displayName": "My custom Victory Charts visualizations",
  "description": "Visualizations built on top of Victory charts"
}
nr1-victory-visualizations/nr1.json

Now when you serve or publish your custom Nerdpack, you can easily distinguish it from the original.

Customize a Nerdpack

Tweak the Circular progress bar visualization to use straight edges and customizable colors.

Circular progress bar renders a VictoryPie with some predefined fields. The fields you'll tweak are:

In your local Nerdpack, open nr1-victory-visualizations/visualizations/circular-progress-bar/nr1.json.

nr1.json is the Circular progress bar visualization's metadata file. Use this file to add a configurable colorScale option, which corresponds to the colorScale field on VictoryPie.

Add a collection of string fields for you to customize your chart's colors:

{
  "schemaType": "VISUALIZATION",
  "id": "circular-progress-bar",
  "displayName": "Circular progress bar",
  "description": "",
  "configuration": [
    {
      "name": "nrqlQueries",
      "title": "NRQL Queries",
      "type": "collection",
      "items": [
        {
          "name": "accountId",
          "title": "Account ID",
          "description": "Account ID to be associated with the query",
          "type": "account-id"
        },
        {
          "name": "query",
          "title": "Query",
          "description": "NRQL query for visualization",
          "type": "nrql"
        }
      ]
    },
    {
      "name": "thresholds",
      "title": "Thresholds",
      "type": "namespace",
      "items": [
        {
          "name": "criticalThreshold",
          "title": "Critical threshold",
          "description": "Value at which progress is displayed as critical",
          "type": "number"
        },
        {
          "name": "highValuesAreSuccess",
          "title": "Above threshold is success",
          "description": "If toggled on, values above the threshold display as successful. Otherwise, values at or above the threshold display as critical.",
          "type": "boolean"
        }
      ]
    },
    {
      "name": "colors",
      "title": "Colors",
      "type": "collection",
      "items": [
        {
          "name": "segmentColor",
          "title": "Segment color",
          "description": "The color of a bar segment.",
          "type": "string"
        }
      ]
    }
  ]
}
nr1.json

The VictoryPie field that you'll use with this update is called colorScale. It accepts an array of colors and applies each color to a segment of the progress bar. So, in your visualization's configuration options, you've specified a collection of strings that you use to pass colors to your chart.

In the same visualization directory, open index.js.

In render(), set the VictoryPie component's colorScale prop:

import React from 'react';
import PropTypes from 'prop-types';
import { VictoryPie, VictoryAnimation, VictoryLabel } from 'victory';
import {
  Card,
  CardBody,
  HeadingText,
  NrqlQuery,
  Spinner,
  AutoSizer,
} from 'nr1';
import NrqlQueryError from '../../src/nrql-query-error';
import { baseLabelStyles } from '../../src/theme';
import { getUniqueAggregatesAndFacets } from '../../src/utils/nrql-validation-helper';
import Colors from '../../src/colors';


const BOUNDS = {
  X: 400,
  Y: 400,
};


const LABEL_SIZE = 24;
const LABEL_PADDING = 10;
const CHART_WIDTH = BOUNDS.X;
const CHART_HEIGHT = BOUNDS.Y - LABEL_SIZE - LABEL_PADDING;


export default class CircularProgressBar extends React.Component {
  // Custom props you wish to be configurable in the UI must also be defined in
  // the nr1.json file for the visualization. See docs for more details.
  static propTypes = {
    /**
     * An array of objects consisting of a nrql `query` and `accountId`.
     * This should be a standard prop for any NRQL based visualizations.
     */
    nrqlQueries: PropTypes.arrayOf(
      PropTypes.shape({
        accountId: PropTypes.number,
        query: PropTypes.string,
      })
    ),


    /**
     * Configuration that determines what values to display as critical or
     * successful.
     */
    thresholds: PropTypes.shape({
      criticalThreshold: PropTypes.number,
      highValuesAreSuccess: PropTypes.bool,
    }),
  };


  /**
   * Restructure the data for a aggregate NRQL query with no TIMESERIES and no
   * FACET into a for our visualization works well with.
   */
  transformData = (data) => {
    const {
      data: [series],
      metadata: { color: colorFromData, name: label },
    } = data[0];


    const percent = series.y * 100;
    const color = this.getColor(percent, colorFromData);


    return {
      percent,
      label,
      series: [
        { x: 'progress', y: percent, color },
        { x: 'remainder', y: 100 - percent, color: 'transparent' },
      ],
    };
  };


  nrqlInputIsValid = (data) => {
    const { data: seriesEntries } = data[0];
    const { uniqueAggregates, uniqueFacets } = getUniqueAggregatesAndFacets(
      data
    );
    const isNonTimeseries = seriesEntries.length === 1;


    return (
      uniqueAggregates.size === 1 && uniqueFacets.size === 0 && isNonTimeseries
    );
  };


  getColor = (value, colorFromData) => {
    const { red6: red, green6: green } = Colors.base;
    const {
      thresholds: { criticalThreshold, highValuesAreSuccess },
    } = this.props;


    const threshold = parseFloat(criticalThreshold);


    if (isNaN(threshold)) {
      return colorFromData;
    }


    if (highValuesAreSuccess) {
      return value > threshold ? green : red;
    }


    return value < threshold ? green : red;
  };


  render() {
    const { nrqlQueries, colors } = this.props;
    const colorScale = Array.from(colors, (x) => x.segmentColor);


    const nrqlQueryPropsAvailable =
      nrqlQueries &&
      nrqlQueries[0] &&
      nrqlQueries[0].accountId &&
      nrqlQueries[0].query;


    if (!nrqlQueryPropsAvailable) {
      return <EmptyState />;
    }


    return (
      <AutoSizer>
        {({ width, height }) => (
          <NrqlQuery
            query={nrqlQueries[0].query}
            accountId={parseInt(nrqlQueries[0].accountId)}
            pollInterval={NrqlQuery.AUTO_POLL_INTERVAL}
          >
            {({ data, loading, error }) => {
              if (loading) {
                return <Spinner />;
              }


              if (error) {
                return (
                  <NrqlQueryError
                    title="NRQL Syntax Error"
                    description={error.message}
                  />
                );
              }


              if (!this.nrqlInputIsValid(data)) {
                return (
                  <NrqlQueryError
                    title="Unsupported NRQL query"
                    description="The provided NRQL query is not supported by this visualization. Please make sure to have exactly 1 aggregate function in the SELECT clause and no FACET or TIMESERIES clauses."
                  />
                );
              }


              const { percent, label, series } = this.transformData(data);


              return (
                <svg
                  viewBox={`0 0 ${BOUNDS.X} ${BOUNDS.Y}`}
                  width={width}
                  height={height}
                  className="CircularProgressBar"
                >
                  <VictoryPie
                    standalone={false}
                    animate={{ duration: 1000 }}
                    data={series}
                    width={CHART_WIDTH}
                    height={CHART_HEIGHT}
                    padding={10}
                    innerRadius={135}
                    cornerRadius={25}
                    labels={() => null}
                    colorScale={colorScale}
                  />
                  <VictoryAnimation duration={1000} data={percent}>
                    {(percent) => (
                      <VictoryLabel
                        textAnchor="middle"
                        verticalAnchor="middle"
                        x={CHART_WIDTH / 2}
                        y={CHART_HEIGHT / 2}
                        text={`${Math.round(percent)}%`}
                        style={{ ...baseLabelStyles, fontSize: 45 }}
                      />
                    )}
                  </VictoryAnimation>
                  <VictoryLabel
                    text={label}
                    lineHeight={1}
                    x={CHART_WIDTH / 2}
                    y={BOUNDS.Y - LABEL_SIZE}
                    textAnchor="middle"
                    style={{ ...baseLabelStyles, fontSize: LABEL_SIZE }}
                  />
                </svg>
              );
            }}
          </NrqlQuery>
        )}
      </AutoSizer>
    );
  }
}


const EmptyState = () => (
  <Card className="EmptyState">
    <CardBody className="EmptyState-cardBody">
      <HeadingText
        spacingType={[HeadingText.SPACING_TYPE.LARGE]}
        type={HeadingText.TYPE.HEADING_3}
      >
        Please provide a NRQL query & account ID pair
      </HeadingText>
      <HeadingText
        spacingType={[HeadingText.SPACING_TYPE.MEDIUM]}
        type={HeadingText.TYPE.HEADING_4}
      >
        This Visualization supports NRQL queries with a single SELECT clause
        returning a percentage value (0 to 100 rather than 0 to 1). For example:
      </HeadingText>
      <code>
        {'FROM Transaction SELECT percentage(count(*), WHERE duration < 0.1)'}
      </code>
    </CardBody>
  </Card>
);
index.js

First, you created a new constant, called colorScale, which is an array of the segmentColor values from this.props.colors. Then, you set the VictoryPie component's colorScale prop. Finally, you removed VictoryPie.style because the colors are now controlled by colorScale.

From your Nerdpack's root directory, run a local server:

bash
$
nr1 nerdpack:serve

Once the server is running, find the url for your local circular-progress-bar:

bash
Visualizations:
 ⁎  circular-progress-bar https://one.nr/04ERPALBYjW
 ⁎  range-chart https://one.nr/0oqQaxezJj1
 ⁎  stacked-bar-chart https://one.nr/0PLRElq3bwa

Open your locally served visualization and configure your chart with your account, data query, and segment colors.

Tip

To add a second color, click the + in the top right of the Colors property.

Because there are two segments, you add two colors. The first color is for the progress section. The second color is for the remaining percentage.

In index.js, remove the VictoryPie component's cornerRadius prop:

import React from 'react';
import PropTypes from 'prop-types';
import { VictoryPie, VictoryAnimation, VictoryLabel } from 'victory';
import {
  Card,
  CardBody,
  HeadingText,
  NrqlQuery,
  Spinner,
  AutoSizer,
} from 'nr1';
import NrqlQueryError from '../../src/nrql-query-error';
import { baseLabelStyles } from '../../src/theme';
import { getUniqueAggregatesAndFacets } from '../../src/utils/nrql-validation-helper';
import Colors from '../../src/colors';


const BOUNDS = {
  X: 400,
  Y: 400,
};


const LABEL_SIZE = 24;
const LABEL_PADDING = 10;
const CHART_WIDTH = BOUNDS.X;
const CHART_HEIGHT = BOUNDS.Y - LABEL_SIZE - LABEL_PADDING;


export default class CircularProgressBar extends React.Component {
  // Custom props you wish to be configurable in the UI must also be defined in
  // the nr1.json file for the visualization. See docs for more details.
  static propTypes = {
    /**
     * An array of objects consisting of a nrql `query` and `accountId`.
     * This should be a standard prop for any NRQL based visualizations.
     */
    nrqlQueries: PropTypes.arrayOf(
      PropTypes.shape({
        accountId: PropTypes.number,
        query: PropTypes.string,
      })
    ),


    /**
     * Configuration that determines what values to display as critical or
     * successful.
     */
    thresholds: PropTypes.shape({
      criticalThreshold: PropTypes.number,
      highValuesAreSuccess: PropTypes.bool,
    }),
  };


  /**
   * Restructure the data for a aggregate NRQL query with no TIMESERIES and no
   * FACET into a for our visualization works well with.
   */
  transformData = (data) => {
    const {
      data: [series],
      metadata: { color: colorFromData, name: label },
    } = data[0];


    const percent = series.y * 100;
    const color = this.getColor(percent, colorFromData);


    return {
      percent,
      label,
      series: [
        { x: 'progress', y: percent, color },
        { x: 'remainder', y: 100 - percent, color: 'transparent' },
      ],
    };
  };


  nrqlInputIsValid = (data) => {
    const { data: seriesEntries } = data[0];
    const { uniqueAggregates, uniqueFacets } = getUniqueAggregatesAndFacets(
      data
    );
    const isNonTimeseries = seriesEntries.length === 1;


    return (
      uniqueAggregates.size === 1 && uniqueFacets.size === 0 && isNonTimeseries
    );
  };


  getColor = (value, colorFromData) => {
    const { red6: red, green6: green } = Colors.base;
    const {
      thresholds: { criticalThreshold, highValuesAreSuccess },
    } = this.props;


    const threshold = parseFloat(criticalThreshold);


    if (isNaN(threshold)) {
      return colorFromData;
    }


    if (highValuesAreSuccess) {
      return value > threshold ? green : red;
    }


    return value < threshold ? green : red;
  };


  render() {
    const { nrqlQueries, colors } = this.props;
    const colorScale = Array.from(colors, (x) => x.segmentColor);


    const nrqlQueryPropsAvailable =
      nrqlQueries &&
      nrqlQueries[0] &&
      nrqlQueries[0].accountId &&
      nrqlQueries[0].query;


    if (!nrqlQueryPropsAvailable) {
      return <EmptyState />;
    }


    return (
      <AutoSizer>
        {({ width, height }) => (
          <NrqlQuery
            query={nrqlQueries[0].query}
            accountId={parseInt(nrqlQueries[0].accountId)}
            pollInterval={NrqlQuery.AUTO_POLL_INTERVAL}
          >
            {({ data, loading, error }) => {
              if (loading) {
                return <Spinner />;
              }


              if (error) {
                return (
                  <NrqlQueryError
                    title="NRQL Syntax Error"
                    description={error.message}
                  />
                );
              }


              if (!this.nrqlInputIsValid(data)) {
                return (
                  <NrqlQueryError
                    title="Unsupported NRQL query"
                    description="The provided NRQL query is not supported by this visualization. Please make sure to have exactly 1 aggregate function in the SELECT clause and no FACET or TIMESERIES clauses."
                  />
                );
              }


              const { percent, label, series } = this.transformData(data);


              return (
                <svg
                  viewBox={`0 0 ${BOUNDS.X} ${BOUNDS.Y}`}
                  width={width}
                  height={height}
                  className="CircularProgressBar"
                >
                  <VictoryPie
                    standalone={false}
                    animate={{ duration: 1000 }}
                    data={series}
                    width={CHART_WIDTH}
                    height={CHART_HEIGHT}
                    padding={10}
                    innerRadius={135}
                    labels={() => null}
                    colorScale={colorScale}
                  />
                  <VictoryAnimation duration={1000} data={percent}>
                    {(percent) => (
                      <VictoryLabel
                        textAnchor="middle"
                        verticalAnchor="middle"
                        x={CHART_WIDTH / 2}
                        y={CHART_HEIGHT / 2}
                        text={`${Math.round(percent)}%`}
                        style={{ ...baseLabelStyles, fontSize: 45 }}
                      />
                    )}
                  </VictoryAnimation>
                  <VictoryLabel
                    text={label}
                    lineHeight={1}
                    x={CHART_WIDTH / 2}
                    y={BOUNDS.Y - LABEL_SIZE}
                    textAnchor="middle"
                    style={{ ...baseLabelStyles, fontSize: LABEL_SIZE }}
                  />
                </svg>
              );
            }}
          </NrqlQuery>
        )}
      </AutoSizer>
    );
  }
}


const EmptyState = () => (
  <Card className="EmptyState">
    <CardBody className="EmptyState-cardBody">
      <HeadingText
        spacingType={[HeadingText.SPACING_TYPE.LARGE]}
        type={HeadingText.TYPE.HEADING_3}
      >
        Please provide a NRQL query & account ID pair
      </HeadingText>
      <HeadingText
        spacingType={[HeadingText.SPACING_TYPE.MEDIUM]}
        type={HeadingText.TYPE.HEADING_4}
      >
        This Visualization supports NRQL queries with a single SELECT clause
        returning a percentage value (0 to 100 rather than 0 to 1). For example:
      </HeadingText>
      <code>
        {'FROM Transaction SELECT percentage(count(*), WHERE duration < 0.1)'}
      </code>
    </CardBody>
  </Card>
);
index.js

This will revert the bar corners to the default 90-degrees instead of being rounded. While your local server is running, it automatically recognizes changes to index.js. So, view your visualization in your browser to see the update.

Perfect! You cloned and updated the open-source Circular progress bar visualization from the Instant Observability catalog. The only thing left to do is publish your version to the catalog so your accounts can subscribe to it.

Now that you're ready to publish your Nerdpack, stop your local server with CTRL+C.

Add a custom visualization to a dashboard

Publish your version of the Victory charts Nerdpack to the catalog. Then subscribe to it and use your visualization in a dashboard.

Tip

Because you used nr1 clone to clone the Nerdpack's repository, your local copy already has its own UUID. This is a prerequisite for publishing your version to the Instant Observability catalog. If you used git clone to copy, you need to update the Nerdpack's UUID manually:

bash
$
nr1 nerdpack:uuid -gf
The new generated id is ab123c45-678d-9012-efg3-45hi6jkl7890

From its root directory, publish your Nerdpack:

bash
$
nr1 nerdpack:publish

Subscribe to your Nerdpack:

bash
$
nr1 nerdpack:subscribe

Here, you subscribed to your Nerdpack with the CLI. This is effectively the same action you performed earlier in this guide within the web UI, but from your terminal.

Go to the Apps view in New Relic.

From Apps, open Custom visualizations.

From here, click the Circular progress bar visualization. Update your visualization's configuration options like you did when you were serving your Nerdpack locally.

Click Add to dashboard.

Go to your dashboard and see your new, customized circular progress bar.

Summary

In this guide, you:

  • Subscribed to a Nerdpack from the Instant Observability catalog.
  • Cloned an open-source Nerdpack.
  • Edited an existing visualization to meet your needs.
  • Published and subscribed to your own custom Nerdpack.
  • Added a visualization from your custom Nerdpack to a dashboard.

Now you know how to build off the foundation of open-source Nerdpacks, you can use the work of the New Relic developer community to fast-track the creation of apps and visualizations.

Tip

If you want to maintain your own version in a remote repository, consider forking the original repo.

Copyright © 2024 New Relic Inc.
CareersTerms of ServiceDMCA PolicyPrivacy NoticeCookie PolicyUK Slavery Act

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.