SignalFx Developers Guide

Working with Charts

Charts display the metrics you’re sending to SignalFx. They can contain a single plot of metrics over time, or multiple related plots. The different chart types that SignalFx provides help you get the best visualization for different types of data and different scenarios.

To learn more about chart features, see the Charts topic in the product documentation.

Chart-dashboard relationships in the API

In the web application, you always create charts within an existing dashboard. In the API, you have to create the chart first and then assign it to a dashboard. If you don’t, the chart won’t appear in the web UI; it becomes an "orphan". You can still view the chart directly by navigating to the URL https://app.{REALM}.signalfx.com/#/chart/v2/{CHART_ID}.

You can also view orphan charts in the web application catalog.

Charts and SignalFlow

A chart’s SignalFlow program controls its metrics and time frame. When you create a chart using the API, you specify the SignalFlow program in the programText property of the Create Chart request object. To learn more about SignalFlow, see the topic Using SignalFlow.

SignalFlow calendar window transformations for charts

SignalFlow programs for charts let you use calendar window transformations, which perform a computation over calendar intervals or windows, such as days, weeks, and months.

SignalFlow provides calendar window transformations for the following methods:

To learn more about SignalFlow calendar window transformations, see Calendar window transformations.

Timezones and SignalFlow calendar window transformations

By default, SignalFlow interprets calendar window transformations relative to the Coordinated Universal Time (UTC) time zone. To change this, use the options.programOptions.timezone property when you create or update a chart. The property value is a string that denotes the geographic region associated with the time zone. For example, the following JSON is part of a chart request body:

1
2
3
4
5
6
7
8
{
  "options": {
    ...
    "programOptions": {
      ...
      "timezone": "Europe/London"
    }
}

The section Supported SignalFlow time zones lists the supported time zones.

Chart types

SignalFx provides these types of charts:

Single value charts

Single value charts show a single value for a datapoint as it changes over time. In most cases, you use this type of chart to display important metrics as a single number. For example, use single value charts in a summary dashboard shown on a wall TV. The dashboard can display the number of active hosts, active processes, or number of requests served in the past 24 hours.

Single Value Chart Example
Single Value Chart Example

Single value charts rarely have a historical context; after a new datapoint arrives, the previous value can’t be restored or viewed again.

You can highlight the value using specific colors based on thresholds. For example, when the number of requests served over the past 24 hours meets the daily goal, you can set the color of the value to change from red to green.

If the input stream for a single value chart contains more than one MTS, the chart displays the first MTS it detects in the stream and ignores the others.

Prefix and suffix values

You can add prefix and suffix values to help describe the value being shown on the chart:

Single Value Chart Prefix and Suffix Example
Single Value Chart Prefix and Suffix Example

Secondary visualizations

You can add these secondary visualizations to a single value chart:

Sparkline

Shows recent trends of the value

Radial

Shows a dial that marks where the current value is among the expected range of values Linear: Shows a bar that marks where the current value is among the expected range of values including sparkline, radial, or linear visualizations

By default, a single value chart doesn’t show any additional visualizations.

The following images show examples of these visualizations:

Sparkline Secondary Visualization
Sparkline Secondary Visualization
Radial Secondary Visualization Example
Radial Secondary Visualization Example
Linear Secondary Visualization Example
Linear Secondary Visualization Example

List charts

List charts are similar to single value charts, but they display multiple datapoints at each point in time. They show recent trends in the data, but they don’t let you see large amounts of history.

A list chart can display up to 100 items at a time, but they work best with 20 or fewer items.

In most cases, you use a list chart to display the topmost n values for an MTS, such as the hosts with the highest CPU usage.

List Chart Example
List Chart Example

Sorting List Charts

The API lets you short values in list charts by specifying the options.sortBy property in the request to create or update a chart. You can sort on the datapoint value, the metric name, or the publish label of the SignalFlow statement that generated the data. To choose one of these options, you specify one of the keyword values shown in the following table:

Table 1. Sort options in API versus web UI
Keyword Corresponding option in the web UI Description

sf_metric

Plot Name

Label of the SignalFlow publish() that’s providing the displayed data. This is also the plot name of the corresponding signal in the web UI.

sf_originatingMetric

Metric

Name of the metric for the MTS being displayed

value

Value

Value the datapoint had when SignalFx received it

For example, the following list chart shows CPU utilization sorted by value in descending order. The top values are 100, which means that some of the cpus are completely maxed out:

List Chart Sorting Example
List Chart Sorting Example

In addition, you can sort by any dimension of an MTS displayed in the chart. To see list of available dimensions, create the chart, then click View SignalFlow to display the SignalFlow program editor. Enter the SignalFlow program for the chart, then switch to the Data Table view to see the list of dimensions. For example, consider this list chart:

List Chart Sort Options in Data Table
List Chart Sort Options in Data Table

Its Data Table shows that the following dimensions are available as sort options for a data stream containing the cpu.utilization MTS:

  • host

  • dnsname

  • plugin

  • plugin_instance

If you used a different SignalFlow program, you’d see different dimensions.

In addition to the dimensions, the Data Table lists the options for the three aforementioned keyword sort options. corresponding to the three keywords.

Another way to see the sort options is to look at the Chart Options > Sort dropdown menu for list charts. The results you see map directly to the options.sortBy property of a list chart. It show the same options as the previous technique, again equating Metric with sf_metric instead of the required value of sf_originatingMetric:

List Chart Sort Options from UI
List Chart Sort Options from UI

Because datapoints stream into SignalFx, the sort order of datapoints associated with a specific publish label changes depending on your sort criteria (including as you scroll through the list).

Prefix and Suffix Values

Prefix and suffix values can be added to help describe the values being shown on the chart:

Line Chart Prefix and Suffix Example
Line Chart Prefix and Suffix Example

Secondary Visualizations

List charts can have sparkline, radial, or linear secondary visualizations for each item in addition to the displayed value or just display the value without a secondary visualization; a sparkline secondary visualization is used by default (see above for an example of what this looks like). A sparkline visualization shows recent trends of the value, a radial visualization displays a dial indicating where the current value falls among the expected range of values, and a linear visualization displays a bar indicating where the current value falls among the expected range of values.

A list chart with a radial visualization might look like this:

Radial Secondary Visualization List Example
Radial Secondary Visualization List Example

A list chart with a linear visualization might look like this:

Linear Secondary Visualization Example
Linear Secondary Visualization Example

Time Series Charts

Time series charts expand the number of data points that can be displayed at once and retain a larger set of historical data with timestamps to make it easier to locate. Time series charts may include a legend indicating which color represents each value of a particular dimension of a plot. For example, a series of plot lines might be colored by AWS availability zone with red indicating us-east-1, green indicating us-east-2, and purple indicating eu-west-1.

Displaying units and other labels

Plots on a chart can specify a unit of value, which will be scaled up and down based on the value in order to improve readability. Units fall into three groups:

Bits

Table 2. Bit scale factors
Name Abbreviation Scale Factor

Bit

b

1

Kilobit

Kb

103

Megabit

Mb

106

Gigabit

Gb

109

Terabit

Tb

1012

Petabit

Pb

1015

Exabit

Eb

1018

Zettabit

Zb

1021

Yottabit

Yb

1024

Bytes

Table 3. Byte scale factors
Name Abbreviation Scale Factor

Byte

B

1

Kibibyte

KiB

1024

Mebibyte

MiB

10242

Gigibyte

GiB

10243

Tebibyte

TiB

10244

Pebibyte

PiB

10245

Exbibyte

EiB

10246

Zebibyte

ZiB

10247

Yobibyte

YiB

10248

Time

Table 4. Time scale factors
Name Abbreviation

Nanosecond

ns

Microsecond

μs

Millisecond

ms

Second

s

Minute

m

Hour

h

Day

d

Week

w

In addition, prefix and suffix values can be added to help describe the values being shown on the chart if no units are specified:

Time Series Chart Prefix and Suffix Example
Time Series Chart Prefix and Suffix Example

Visualizations

Time series charts may be visualized in any of four ways:

Line charts

The LineChart plot type displays the data in a plot with datapoints connected by a series of straight lines as follows:

Time Series Chart Line Chart Example
Time Series Chart Line Chart Example

Area charts

The AreaChart plot type displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in as follows:

Time Series Chart Area Chart Example
Time Series Chart Area Chart Example

Column charts

The ColumnChart plot type lists the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. By default each plot point is shown as an independent bar closely plotted next to each other as follows:

Time Series Chart Column Chart Example
Time Series Chart Column Chart Example

Column charts can also be stacked, meaning that the bars representing each value at each moment in time are stacked vertically on top of each other at the relevant time point along the x-axis rather than being grouped next to each other near that point as follows:

Time Series Chart Stacked Column Chart Example
Time Series Chart Stacked Column Chart Example

Histogram charts

Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar or darker shades of a single color might indicate a higher density of plot points with the relevant value than a higher shade of that same color as follows:

Time Series Chart Histogram Chart Example
Time Series Chart Histogram Chart Example

The values of a histogram plot display in a random order by default but may be organized into two levels of grouping to hone in on the behavior of specific sets of data. For example, data might be grouped by AWS region or availability zone to make it easier to track performance within each region or availability zone.

Heatmap charts

Heatmap charts present a series of squares each representing a single data point of the selected metric. The color of each square represents the value range of the metric allowing quick identification of values that are higher or lower than desired.

Heatmap Example
Heatmap Example

Grouping

The data points in a heatmap can be grouped by up to two properties to highlight the health of a specific aspect of the data being viewed. For example, the following heatmap groups CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping.

Heatmap Example with Grouping
Heatmap Example with Grouping

Prefix and suffix values can be added to help describe the value being shown on the chart:

Heatmap Prefix and Suffix Example
Heatmap Prefix and Suffix Example

Text charts

Text charts allow users to add descriptive text or other information to a dashboard. The chart displays any specified GitHub style Markdown within the chart location and is used to provide information about one or more other charts in the same dashboard.

Text Chart Example
Text Chart Example

Chart color palettes

Some elements of SignalFx charts are restricted to a color palette of or based on 21 specific colors referenced by a 0-based index.

The default colors represented by the color index are:

Table 5. Color palette
Index Hex Value Color Swatch

0

#999999

1

#0077c2

2

#00b9ff

3

#6ca2b7

4

#b04600

5

#f47e00

6

#e5b312

7

#bd468d

8

#e9008a

9

#ff8dd1

10

#876ff3

11

#a747ff

12

#ab99bc

13

#007c1d

14

#05ce00

15

#0dba8f

16

#ea1849

17

#eac24b

18

#e5e517

19

#acef7f

20

#6bd37e

These colors may be swapped out for colorblind-friendly alternatives by users who select such options:

Table 6. Colorblind-friendly alternatives
Index Normal Setting Red-Green Color blindness Setting Yellow-Blue Color-blindness Setting

0

#999999

#999999

#005160

1

#0077c2

#000982

#007186

2

#00b9ff

#0814b6

#0089a2

3

#6ca2b7

#0b1ae4

#00a2c0

4

#b04600

#7c730b

#85005e

5

#f47e00

#aba734

#a40074

6

#e5b312

#c5bf1c

#c20089

7

#bd468d

#dad30a

#e400a1

8

#e9008a

#535353

#555555

9

#ff8dd1

#787878

#666666

10

#876ff3

#b0b0b0

#787878

11

#a747ff

#c1c1c1

#888888

12

#ab99bc

#bc82b6

#999999

13

#007c1d

#b36dac

#aaaaaa

14

#05ce00

#b241a6

#bbbbbb

15

#0dba8f

#b0009d

#cccccc

16

#ea1849

#b0009d

#e400a1

17

#eac24b

#7c730b

#005160

18

#e5e517

#aba734

#007186

19

#acef7f

#c5bf1c

#0089a2

20

#6bd37e

#c1c1c1

#c1c1c1

This happens automatically, and you can’t change it with API settings.

Considerations for chart properties

Tags

You can have no more than 50 tags per chart.

Examples

Create a chart

The following curl command creates a simple chart.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$ curl \
    --request POST \
    --header "X-SF-TOKEN: <YOUR_ACCESS_TOKEN>" \
    --header "Content-Type: application/json" \
    --data \
    '{
  	    "name": "CPU load",
  	    "programText": "data(\"cpu.utilization\").publish()"
	 }' \
    https://api.{REALM}.signalfx.com/v2/chart

The response body contains the chart ID that SignalFx assigns to the new chart, along with default and auto-generated values. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
    "created": <CREATED_TIMESTAMP>,
    "creator": "<CREATOR_ID>",
    "customProperties": {},
    "description": "",
    "id": "<CHART_ID>",
    "lastUpdated": <UPDATED_TIMESTAMP>,
    "lastUpdatedBy": "<UPDATER_ID>",
    "name": "CPU load",
    "options": {
        "type": "TimeSeriesChart",
        "areaChartOptions": null,
        "axes": [
            {
                "highWatermark": null,
                "label": null,
                "lowWatermark": null,
                "max": null,
                "min": null
            }
        ],
        "colorBy": "Dimension",
        "defaultPlotType": "LineChart",
        "legendOptions": null,
        "lineChartOptions": null,
        "programOptions": null,
        "showEventLines": false,
        "stacked": false,
        "time": {
            "type": "relative",
            "range": 900000
        },
        "unitPrefix": "Metric"
    },
    "programText": "data(\"cpu.load\").publish()",
    "tags": []
}

You can view a chart in the web UI using the following URL:

http://app.{REALM}.signalfx.com/#/chart/{CHART_ID}

By default, SignalFx creates a line chart from the specified SignalFlow program. The API provides all the request properties you need to fully customize charts when you create or update them. To see all the properties, read the Charts API reference.

Create a dashboard

The following example creates a new dashboard for the newly-created chart, and adds the dashboard to an existing dashboard group.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
$ curl \
    --request POST \
    --header "X-SF-TOKEN: <YOUR_ACCESS_TOKEN>" \
    --header "Content-Type: application/json" \
    --data \
    '{
        "name": "My new dashboard",
        "groupId": "<DASHBOARD_GROUP_ID>"
        "charts": [
            {
                "chartId": "<CHART_ID>",
                "column": 0,
                "height": 1,
                "row": 0,
                "width": 6
            }
        ]
    }' \
    https://api.{REALM}.signalfx.com/v2/dashboard

SignalFx responds with the properties of the new dashboard object:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "charts": [
        {
            "chartId": "<CHART_ID>",
            "column": 0,
            "height": 1,
            "row": 0,
            "width": 6
        }
    ],
    "created": <CREATED_TIMESTAMP>,
    "creator": "<CREATOR_ID>",
    "customProperties": {},
    "description": "",
    "filters": null,
    "groupId": "<DASHBOARD_GROUP_ID>",
    "id": "<CHART_ID>",
    "lastUpdated": <UPDATED_TIMESTAMP>,
    "lastUpdatedBy": "<UPDATER_ID>",
    "name": "My new dashboard",
    "tags": []
}

Since you didn’t provide the ID of an existing dashboard group, SignalFx created a new one.

© Copyright 2019 SignalFx.

Third-party license information