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 UI, 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 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 UI 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 body. To learn more about SignalFlow, see the topic Using SignalFlow.

The SignalFlow program for a chart can also link the chart to a detector. To learn more, see the section Linking charts and detectors.

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 in 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 sort values in list charts by specifying the options.sortBy property in the request to create or update a chart. You can sort on one of the MTS dimensions, a datapoint value, the metric name, or the publish() method label argument of the SignalFlow statement that generates 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 Alias in the UI Description

<dimension_name>

<dimension_name>

One of the MTS dimensions. To see the available dimensions, follow the instructions that appear after this table.

sf_metric

Plot Name

label argument 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

In addition, you can sort by any dimension of an MTS displayed in the chart.

To see a list of entities on which you can sort:

  1. In the UI, open the chart.

  2. Click the CHART OPTIONS tab.

  3. Open the Sort drop-down list.

In the list, Value is the alias for value, Plot Name is the alias for sf_metric, and metric is the alias for sf_originatingMetric. All other list items are dimension names.

Examples

To sort a list chart by value, specify the following in the request body:

1
2
3
4
5
6
{
    options: {
        "sortBy": "value",
    ...
    }
}

To sort by plot name, specify the following:

1
2
3
4
5
6
{
    options: {
        "sortBy": "sf_metric",
        ...
    }
}

To sort by the dimension demo_datacenter, specify the following:

1
2
3
4
5
6
{
    options: {
        "sortBy": "demo_datacenter",
        ...
    }
}

The following list chart is an example of sorting. It shows CPU utilization sorted by datapoint value in descending order. The top values are 100, which means that some CPUs are completely maxed out:

List Chart Sorting Example
List Chart Sorting Example

Prefix and Suffix Values

Prefix and suffix values can be added to help describe the values in 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. By default, the UI displays a sparkline secondary visualization. A sparkline 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, SignalFx might color a series of plot lines 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

In the API, you specify some chart colors by specifying a palette index value. The following table shows the values and their corresponding colors:

Table 5. Color palette
Index Hex value Color swatch
0#ea1849
1#eac24b
2#e5e517
3#aecf7f
4#6bd37e
5#999999
6#0077c2
7#00b9ff
8#6ca2b7
9#b04600
10#f47e00
11#e5b312
12#bd468d
13#e9008a
14#ff8dd1
15#876ff3
16#a747ff
17#ab99bc
18#007c1d
19#05ce00
20#0dba8f
21#98abbe
Table 6. Color vision deficiency 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

Considerations for chart properties

Tags

You can have no more than 50 tags per chart.

Linking charts and detectors

To link a chart and a detector using the API, add an alerts() block to the chart’s SignalFlow program specified in the programText property.

To learn more about linking charts and detectors, see the topic Linking Detectors to Charts.

Considerations for linking charts and detectors

  • Using the API, you can link a chart to a version 1 detector or a version 2 detector.

  • The alerts() block isn’t general-purpose SignalFlow, and you can use it only in a chart’s SignalFlow program that links a chart to a detector.

  • To link a chart and a detector, the detector must exist, but the chart can be new or existing.

  • To learn how to create a detector using the API, see the section Create a detector.

Linking an existing chart to a detector

For example, suppose you have a chart object with the SignalFlow program:

blkioRead = data('blkio.io_service_bytes_recursive.read', filter=filter('plugin', 'docker')).sum().publish(label='blkioRead')

To link the chart to an existing detector object with the SignalFx ID <DETECTOR_ID>, add the following line to the end of the program:

alertSignal = alerts(detector_id='<DETECTOR_ID>').publish(label='alertSignal')

The resulting SignalFlow program is this:

1
2
blkioRead = data('blkio.io_service_bytes_recursive.read', filter=filter('plugin', 'docker')).sum().publish(label='blkioRead')
alertSignal = alerts(detector_id='<DETECTOR_ID>').publish(label='alertSignal')

After you have modified the SignalFlow program, update the programText property for the chart using the operation PUT https://api.{REALM}.signalfx.com/v2/chart/{id}. For an example of updating a chart, see the section Update a chart.

Linking a new chart to a detector

To link a new chart to a detector, follow the instructions in the previous section Linking an existing chart to a detector, with these exceptions:

  • You need to write a new SignalFlow program for the chart itself.

  • You use the operation POST https://api.{REALM}.signalfx.com/v2/chart to create the 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.

Update a chart

This example updates a chart to link it with a detector.

Considerations for updating charts

  • The SignalFx API uses overwrite semantics for updates.

  • When you do an update using a PUT operation, the API deletes or sets to null the writeable properties you don’t specify in the request body. This happens even if the properties had existing values.

  • Read-only properties aren’t affected. If you want, you can delete them from a PUT request. If you leave them in, the API ignores them.

  • To avoid wiping out the properties you want to keep, follow these steps to update a chart:

    1. Find the SignalFx ID for the chart:

      • Using the web UI, open the chart. The browser address bar displays a URL similar to the following:
        https://app.signalfx.com/#/chart/v2/<CHART_ID>?groupId=<DASHBOARD_GROUP_ID>&configId=<CONFIG_ID>

      • Using the API, use the operation GET https://api.{REALM}.signalfx.com/v2/chart to search for charts, then get the chart ID from the appropriate chart.

    2. Use the operation GET https://api.{REALM}.signalfx.com/v2/chart/{<CHART_ID>} to get the properties for the chart. The response body is a JSON object.

    3. Modify the properties you want to update.

    4. Use the operation PUT https://api.{REALM}.signalfx.com/v2/chart/{<CHART_ID>} to update the chart, using the response body from the previous GET as the request body for the PUT. This ensures that the update doesn’t delete or null out existing properties.

Example PUT request for updating a chart

The following curl command updates an existing chart:

 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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
$ curl \
--request PUT \
--header "X-SF-TOKEN: <YOUR_ACCESS_TOKEN>" \
--header "Content-Type: application/json" \
--data \
'{
  "customProperties": {},
  "description": "Chart linked to detector",
  "id": "<CHART_ID>",
  "name": "Disk Read Bytes/sec",
  "options": {
    "areaChartOptions": {
      "showDataMarkers": false
    },
    "axes": [
      {
        "highWatermark": null,
        "highWatermarkLabel": null,
        "label": "bytes/sec",
        "lowWatermark": null,
        "lowWatermarkLabel": null,
        "max": null,
        "min": 0.0
      },
      {
        "highWatermark": null,
        "highWatermarkLabel": null,
        "label": "",
        "lowWatermark": null,
        "lowWatermarkLabel": null,
        "max": null,
        "min": null
      }
    ],
    "axisPrecision": null,
    "colorBy": "Dimension",
    "defaultPlotType": "AreaChart",
    "eventPublishLabelOptions": [],
    "histogramChartOptions": {
      "colorThemeIndex": 16
    },
    "includeZero": false,
    "legendOptions": {
      "fields": null
    },
    "lineChartOptions": {
      "showDataMarkers": false
    },
    "onChartLegendOptions": {
      "dimensionInLegend": null,
      "showLegend": false
    },
    "programOptions": {
      "disableSampling": false,
      "maxDelay": null,
      "minimumResolution": 0,
      "timezone": null
    },
    "publishLabelOptions": [
      {
        "displayName": "bytes/sec",
        "label": "A",
        "paletteIndex": 8,
        "plotType": null,
        "valuePrefix": null,
        "valueSuffix": null,
        "valueUnit": null,
        "yAxis": 0
      }
    ],
    "showEventLines": false,
    "stacked": false,
    "time": {
      "range": 3600000,
      "type": "relative"
    },
    "type": "TimeSeriesChart",
    "unitPrefix": "Binary"
  },
  "packageSpecifications": "",
  "programText": "A = data('cpu.usage.total').timeshift('12m').publish(label='A'); B = alerts(detector_id='<DETECTOR_ID>').publish('B')",
    "relatedDetectorIds": [
  ],
  "tags": null
}' \
https://api.{REALM}.signalfx.com/v2/chart

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 2020 Splunk, Inc.

Third-party license information