To help you build a New Relic One application, we provide you with the New Relic One SDK. This page will explain SDK components that control chart displays and other data visualizations. For a hands-on procedure showing how to work with chart components, see our workshop.
The New Relic One SDK provides a set of charts that you can configure to visualize your data. All charts are React components that can be identified by the Chart suffix.
You have access to React components representing the major types of charts that we use in the New Relic UI. Select a chart type below to see and interact with the React component:
Each of these components accepts accountId and query prop (to make a NRQL query to the New Relic backend), or data prop instead (providing data to be rendered manually). We also provide a query component called NrqlQuery that can fetch data and provide it back as a JavaScript object. See how both of these are equivalent here:
<BillboardChart accountId={1234} query="SELECT count(*) FROM Transaction" />
// Is equivalent to:
<NrqlQuery accountId={1234} query="SELECT count(*) FROM Transaction">
{({data}) => <BillboardChart data={data} />}
</NrqlQuery>
All charts use a standard data format that can either come from a NrqlQuery (when formatType is FORMAT_TYPE.CHART) or hand-crafted externally, meaning you can create this data on the fly through JavaScript, or expose it from an external, third-party service that returns it. For instance, you can do:
const data = [
{
metadata: {
id: 'series-1',
name: 'My series',
},
data: [
{
x: 0,
y: 0,
},
{
x: 20,
y: 10,
},
],
},
];
<LineChart data={data} />
Or, to modify data queried:
<NrqlQuery accountId={1} query="SELECT count(*) FROM Transaction TIMESERIES">
{({data}) => {
const newData = data.concat(
{
metadata: {
id: 'series-1',
name: 'My series',
viz: 'target-line',
},
data: [
{
y: 20,
},
],
},
);
return <LineChart data={newData} />;
}}
</NrqlQuery>
The format is always composed of an Array of Objects, where each object is a series. A series represents a set of data points that, depending on the visualization chosen, will be presented to the user in some format.
Each series Object is, in turn, composed of two keys: metadata and data. The metadata defines how the data will be represented, and the data what to represent.
type ChartFormat = Array<ChartSeries>;
type ChartSeries = {
metadata: ChartMetadata,
data: ChartData,
};
The series metadata is an Object with a particular set of properties:
type ChartMetadata = {
id: string,
name: string,
color: string,
viz: 'main' | 'line' | 'area' | 'event' | 'target-line',
units: ChartPoint,
}
idUnique identifier for the series. Two series having the same id are considered to be the same series, regardless of where they are located.
In general, you'll want different ids per series so that every series is unique. However, when the same series has the same origin and is repeated across charts, keeping the id consistent between different charts can help with some cross-chart functionality (like highlighting multiple charts simultaneously).
nameDefines the name of the series. This is often used in legends, tooltips, etc. to indicate which series you’re looking at. When fetching data from NRQL, this often refers to the facet name, like hostnames, countries, etc.
colorThe color that represents the series. Most visualizations use this value to differentiate series; some visualizations, like the BillboardChart or the JsonChart, ignore it.
Colors are usually passed in hex format (i.e. #RRGGBB), although any valid CSS color representation is allowed, like hsl(HHH, SS%, LL%) or rgba(RR, GG, BB, .AA). We discourage tweaking the alpha value because it’s a feature often used by charts to highlight or dim certain series, so changing that might cause confusion.
The standard charting palette used by New Relic One has been crafted to look best in monitors and provide contrast between values.
vizDescribes how the series will be represented. The field accepts many different values, although the one you will use the most is main:
main: The given series will be charted based on the chart component where it is being passed. For instance, this series will be charted as a line in a LineChart, but as an area in an AreaChart.
line: The series will be charted as a line, regardless of the chart where it is being passed. This setting only applies to AreaCharts and ScatterCharts; in other charts the series will not be shown.
area: The series will be charted as an area, regardless of the chart where it’s being passed. This setting only applies to LineCharts and ScatterCharts; in other charts the series will not be shown.
event: The series will be charted as an event, which is represented as a vertical area behind the main visualization. Events are often used to show alerts. This setting only applies to AreaCharts, LineCharts and ScatterCharts; in other charts the series will not be shown. A vertical marker is also created using an event, in which its start and end values are the same. Vertical markers are often used to show deployment markers.
target-line: The series is charted as a vertical line. This setting only applies to AreaCharts, LineCharts and ScatterCharts; in other charts the series will not be shown.
unitsEach value passed in each data point can have a unit assigned to it. Based on that unit, charts will pick the best possible way to represent them. Units are provided as a static string, with different values:
UNKNOWN: the unit of the field is unknown, and will be left as-is when showing it in the UI.
COUNT: the provided value is a count, without any particular unit associated to it. Values are then formatted with their International System prefix (k for thousands, M for millions, G for billions, etc).
PERCENTAGE: the provided value is a ratio, usually ranging from 0 to 1. A value of 1 is formatted as 100%, a value of 2 is formatted as 200%, and a value of 0.01 is formatted as 1%.
MILLISECONDS: the provided value is a duration, in milliseconds. If the given value is higher than 1, time is incrementally formatted as human-readable (e.g. 60,000 milliseconds are shown as 1 minute). If the given value is lower than 1, it is formatted following the SI prefixes (e.g. 0.001 milliseconds are shown as 1 μs).
TIMESTAMP: the provided value is a timestamp, in milliseconds, counted from the UNIX Epoch. It will be formatted as a date, providing the amount of detail needed to be correctly interpreted.
BITS: formats the value as bits, using the b unit. When upscaling, the decimal prefixes are used, instead of the binary ones. This means that 1,000 bits are 1 kb, and formatted as such.
BYTES: same as BITS, except that the value is formatted as bytes, using B as a unit. 1,000 bytes are represented as 1 kB.
The series data is an Array, containing data points represented as Objects:
type ChartSeries = Array<ChartPoint>;
type ChartPoint = {
[string]: any,
};
Data points can contain any arbitrary set of values (which you can read back, for instance, in callbacks), although charts will always use a fixed set of values. Depending on what are you trying to represent, you can use:
Unidimensional series: values are read from the y property, which is interpreted as the dependent variable, and makes the format compatible with two-dimensional series. This is the format is used in funnels and pies.
Two-dimensional series: values are read from x and y properties. This is the format used in lines, areas, scatters, and sparklines.
Event series: events that span for an interval, are read from the x0 and x1 values, being x0 the starting point, and x1 as the ending point. To make a vertical marker, pass both x0 and x1 with the same value.
Histogram series: histograms are a combination of the two points above: columns will span from x0 to x1, and will have a height of y. This is the format used in histograms and heat maps.
We described the chart data format as Array of series, but charts also accept some particular values to indicate particular states:
Passing null or undefined triggers the “loading” mode, showing the default placeholder. This can be useful for providing visual feedback while data is loaded.
Passing [] triggers the “no data” mode, where visual feedback is provided about the lack of data. This is made to be compatible for valid data with no available series.
Under some circumstances, you might want to synchronize different actions over charts, like enabling the chart needle to move simultaneously over multiple charts at the same time, or to synchronize dragging over a chart section. To achieve this, you need to use the ChartGroup component. All charts under it will then share these events:
<ChartGroup>
<Stack>
<StackItem>
<LineChart accountId={1} query="SELECT count(*) FROM Transaction SINCE 1 hour ago" />
</StackItem>
<StackItem>
<AreaChart accountId={1} query="SELECT count(*) FROM Synthetics SINCE 1 day ago" />
</StackItem>
</Stack>
</ChartGroup>
To minimize confusion, it’s better to only group charts that are related to the same concept, and keep different concepts under separate groups.
The JsonChart “chart” is an exception because it’s able to process any kind of valid data, not only the CHART format type, but also RAW, or any other valid JavaScript object.
When shown in dashboards, the RAW format type is shown by default because this is the one our customers are the most accustomed to.