Related Answers
Download topic as PDF
Single value and single value radial
Use a single value visualization to show a metric and its context. Single value visualizations display results and context for searches returning a discrete number.
A single value can be a count or other aggregation of specific events. For example, this search:
index = _internal source = "*splunkd.log" log_level = "error" | stats count
creates the following single value radial visualization.
A caption, unit notation, and range colors add emphasis. If the timechart command is used, a trend indicator to the right of the value and a sparkline underneath show how data has changed over time.
Data formatting
Single value visualizations work best for queries that create a time series chart using the timechart command or aggregate data using the stats command.
Use timechart to generate a single value
This search and visualization use timechart to track daily errors for a Splunk deployment.
index=_internal source="*splunkd.log" log_level="error" | timechart count
To access sparklines and trend indicators, it is important that the search includes the timechart command. Using timechart means that time series data becomes available to sparkline and trend indicator processing.
In order to use timechart command and to enable threshoding, sparklines, and trends, you must modify the encoding section using the field setting in the fill area to change the default from primary[0] to primary[1]. This is because the first column returned is the timestamp and not the actual value.
Generate a single value or single value radial visualization
- Select single value or single value radial using the visual editor by clicking the Add Chart button (
) in the editing toolbar and either browsing through the available charts, or by using the search option. - Select the chart on your dashboard so that it's highlighted with the blue editing outline.
- (Optional) Set up a new data source by adding a query to the Search window.
- To choose an existing search, close the window and select the visualization. If the Configuration panel doesn't appear, click the Configuration button (
) to bring up the Configuration panel and click +Setup Primary Data Source to choose an existing search.
Configuration Panel options for single value and single value radial gauges
You can use the Configuration panel to configure the following components.
Title
Give your visualization a title. This is also helpful when searching for individual visualizations in the dashboard definitions. This name is not the same as the automatically assigned unique ID.
Description
Give your visualization a description to explain what the user is viewing.
Data Configurations
Choose an existing ad hoc search or create a new one.
Position & Size
You can use your mouse to change the size or location of the visualization, or the Position & Size section of the Configuration panel for pixel perfect sizing and placement.
Visualization Settings
- Check the Show Trending Value box to add an arrow pointing in the direction of the trend and a trending value, also known as a delta value.
- Use the Trend Display as to choose to show the trending value as either a percent or an absolute number.
- Check the Show Sparkline box If you want to show a line that displays the trend of the displayed values over time.
- Select Before, After, or Below to place your sparkline.
Font Settings (single value only)
- Choose a major font size in pixels for the displayed value.
- Choose a delta font size in pixels for the displayed trending, or delta, value.
Threshold Settings
Use Thresholding Settings to set range values and their associated colors. This will change the background color of the visualization, and will take precedence over any background color you've set. See Configure thresholding.
Background color
To change the background color of the gauge panel, click the color box to select from a palette or enter a hex code, for example, enter #ff7189 for a shade of pink.
Number Formatting
- Use Digit Precision to choose the number of decimal places displayed.
- Use the Unit field to choose a unit. For example, a percentage (%) symbol to indicate that the returned value is a percent.
- Use the Position dropdown menu to choose where to place the unit symbol
Drilldown
Click + Add Drilldown to allow a user to click the value of a visualization to link to a an external or internal URL.
Code
Select your visualization or its search to view and edit the source code in real-time.
Configure thresholding
Configure thresholding on the single value visualization, single value radial, single value icons, filler gauges, marker gauges, and shapes to determine the color of the value or background of the visualization, which indicates the current status of the value being measured.
Thresholding allows you to configure the colors you want for various numerical value ranges resulting from a dynamic search. The color is meant to indicate the current value and will change when it enters different ranges.
Apply thresholding for numerical values
This capability is supported by all visualizations that support thresholding.
- In edit mode, select the single value visualization for which you want to configure thresholds.
- In the Configuration panel, expand Threshold Settings.
- Toggle Thresholds to enable thresholding for the visualization.
The following are the default values and their associated colors:
- If the value is below 10, the visualization is blue.
- If the value is greater than or equal to 10 or below 30, the visualization is green.
- If the value is greater than or equal to 30 or below 50, the visualization is yellow.
- If the value is greater than or equal to 50 or below 70, the visualization is orange.
- If the value is greater than or equal to 70 or below 100, the visualization is dark orange.
- If the value is greater than or equal to 100 and above, the visualization is red.
You can change the colors by clicking the color box and either selecting from the options in the panel or by entering a hex color code.
Thresholding depends on the first field column returned by your search for most visualizations and will sometimes render incorrectly depending on how your data is structured as a result of your SPL search. This column is represented by the setting "primary[0]" in the "field" property in the encoding section of the visualization stanza. You can specify a different column or the actual field name. For example, if the you want thresholding applied to the second column of returned values, and the field name is countyou can either specify "primary[1]" or the name of the field, "primary.count".
Apply thresholding to strings
For single value and single value radial visualizations, you can also apply thresholding to match colors with string results using the property matchvalue. For example, if you have a search that returns a value "cherry" and you want it to be red, you can assign a hex value for red to that value. You can do this in combination with the "fill" property to have the background display the color, or with the "majorValue" property for the string value to display the color. To learn more about how to display color, see Apply thresholding to the value instead of background.
If you want to use thresholding depending on strings, you must change the field value type from fieldValue to matchvalue. You must also have a correct search string, for example:
| makeresults| eval word="cherry"| fields word
The following dashboard displays all of the thresholding formatting options that you can use with matchvalue.
Expand the window to see the dashboard definition of the example dashboard.
Expand this window to copy/paste the dashboard definition into your own dashboard.
{
"visualizations": {
"viz_Sl1H0oE5": {
"type": "viz.singlevalue",
"options": {},
"dataSources": {
"primary": "ds_CDFE3AMM"
},
"encoding": {
"fill": {
"field": "primary.word",
"format": {
"type": "matchvalue",
"matches": [
{
"match": "apple",
"value": "#FFA500"
},
{
"match": "grape",
"value": "#FFFF00"
},
{
"match": "pear",
"value": "#800080"
},
{
"match": "strawberry",
"value": "#0000FF"
},
{
"match": "cherry",
"value": "#A52A2A"
}
]
}
}
},
"title": ""
},
"viz_Jt7up41Z": {
"type": "viz.singlevalue",
"options": {
"backgroundColor": "transparent"
},
"dataSources": {
"primary": "ds_CDFE3AMM"
},
"encoding": {
"majorColor": {
"field": "primary.word",
"format": {
"type": "matchvalue",
"matches": [
{
"match": "apple",
"value": "#FFA500"
},
{
"match": "grape",
"value": "#FFFF00"
},
{
"match": "pear",
"value": "#800080"
},
{
"match": "strawberry",
"value": "#0000FF"
},
{
"match": "cherry",
"value": "#A52A2A"
}
]
}
}
},
"title": ""
},
"viz_TKycCgXr": {
"type": "viz.singlevalue",
"options": {},
"dataSources": {
"primary": "ds_Y8lseSul_ds_CDFE3AMM"
},
"title": "No formatting"
},
"viz_5RxHuurm": {
"type": "viz.table",
"options": {},
"dataSources": {
"primary": "ds_CDFE3AMM"
}
}
},
"dataSources": {
"ds_CDFE3AMM": {
"type": "ds.search",
"options": {
"queryParameters": {
"earliest": "-24h@h",
"latest": "now"
},
"query": "| makeresults\n| eval word=\"cherry\"\n| fields word"
},
"name": "Search_1"
},
"ds_Y8lseSul_ds_CDFE3AMM": {
"type": "ds.search",
"options": {
"queryParameters": {
"earliest": "-24h@h",
"latest": "now"
},
"query": "| makeresults\n| eval word=\"cherry\""
},
"name": "Copy of Search_1"
}
},
"inputs": {},
"layout": {
"globalInputs": [],
"type": "absolute",
"options": {
"display": "auto-scale"
},
"structure": [
{
"item": "viz_Sl1H0oE5",
"type": "block",
"position": {
"x": 10,
"y": 250,
"w": 580,
"h": 210
}
},
{
"item": "viz_Jt7up41Z",
"type": "block",
"position": {
"x": 610,
"y": 250,
"w": 580,
"h": 210
}
},
{
"item": "viz_TKycCgXr",
"type": "block",
"position": {
"x": 10,
"y": 20,
"w": 580,
"h": 210
}
},
{
"item": "viz_5RxHuurm",
"type": "block",
"position": {
"x": 610,
"y": 20,
"w": 570,
"h": 210
}
}
]
},
"description": "",
"title": "Matchvalue"
}
You can change numerical values and their associated colors directly in the visual editor. Thresholding applied to the string value or background color must be done in the source editor.
Apply thresholding to the value instead of background
By default, the background of a visualization is the portion that changes color when the values change. If you'd rather have the value change color instead of the background, you must use the source editor. As shown in the following example, you would replace the "fill" field with the field "majorColor":
"viz_3md3CLNO": {
"type": "viz.singlevalue",
"options": {},
"encoding": {
"majorColor": {
"field": "primary[1]",
"format": {
"type": "rangevalue",
"ranges": [
{
"from": 100,
"value": "#cb3b43"
},
{
"to": 100,
"from": 70,
"value": "#ff7152"
},
{
"to": 70,
"from": 50,
"value": "#fc9850"
},
{
"to": 50,
"from": 30,
"value": "#f4df7a"
},
{
"to": 30,
"from": 10,
"value": "#4beba8"
},
{
"to": 10,
"value": "#5fbcff"
}
]
}
}
},
"dataSources": {
"primary": "ds_ZsK7mN0Y"
}
}
Source options for single value and single value radial
While some of these options can be set using the visual editor, there are additional options that can only be set in the source editor for viz.singlevalue and viz.singlevalueradial. These options are added to the options field of the visualization stanza. For example, the following example shows the addition of a background color using a hex code and the option not to show a sparkline.
"viz_25NNIqLF": {
"type": "viz.singlevalue",
"options": {
"backgroundColor": "#0000FF",
"showSparkline": false
},
"dataSources": {
"primary": "ds_gcEN4c7Q"
}
}
To read more on how visualization stanzas are structured see: Elements of a visualization. Below are all of the options available.
Single value options
The following options are available for the single value visualization:
| Property | Type | Default | Description |
|---|---|---|---|
| unit | string | N/A | Specify label text to show next to the single value. |
| unitPosition | (before | after) | after | Specify whether you want the unit label to appear before or after the single value. |
| underLabel | string | N/A | Specify the label text that appears below the value. |
| backgroundColor | string | light mode: "#FFFFFF". Dark mode: "#212527"
|
Specify a color to use for the single value background. For example, "#008000".
|
| showTrendIndicator | boolean | true | Specify whether to show or hide the single value trend indicator. |
| useTrendUnits | boolean | false | Specify whether to truncate the trend value to two significant digits. A magnitude unit is displayed. |
| showSparkline | boolean | true | Specify whether to show or hide the single value sparkline. |
| sparklinePosition | (before | after | below) | below | Specify the location to display a sparkline. |
| sparkline.AreaGraph | boolean | false | Specify whether to show the sparkline as an area graph rather than a line. |
| sparklineFillColor | string | "#6F7A87"
|
Specify a color in hex code to use for the sparkline fill. Note that this setting only works when sparkline.AreaGraph is set to true.
|
| sparklineStrokeColor | string | "#2f353C"
|
Specify a color in hex code to use for the sparkline stroke. |
| showSparklineTooltip | boolean | false | Show a tooltip to display values on the sparkline. |
| sparklineAcceptNullData | boolean | true | Specify whether to convert null and non-numeric values in the sparkline to 0. |
| sparklineHighlightSegments | number | 4 | Specify the number of segments to highlight at the top of a sparkline area graph. Note that this setting only works when sparkline.AreaGraph is set to true.
|
| sparklineHighlightDots | number | 5 | Specify the number of markers, or dots, to display at the top of a sparkline area chart. Note that this setting only works when sparkline.AreaGraph is set to true.
|
| trendDisplayMode | (percent | absolute) | absolute | Specify whether the trend value is displayed as a percentage or an absolute count. |
| numberPrecision | number | 0 | Specify the number of decimal places to display. For example, to display three decimal places, enter a value of 3. The maximum value is 20. |
| useThousandSeparators | boolean | true | Specify whether numeric values use commas as thousandths separators. |
| majorFontSize | number | calculated based on available space | Specify the font size (px) for the major value of Single Value. By default the major value font size is calculated dynamically based on the available space. |
| deltaFontSize | number | Font size depends on available space. | Specify the font size (px) for the delta value of Single Value. |
Single value radial options
The following options are available for the single value radial visualization:
| Property | Type | Default | Description |
|---|---|---|---|
| unit | string | N/A | Specify label text to show next to the single value. |
| unitPosition | (before | after) | after | Specify whether you want the unit label to appear before or after the single value. |
| underLabel | string | N/A | Specify the label text that appears below the value. |
| backgroundColor | string | light mode: "#FFFFFF". Dark mode: "#212527"
|
Specify a color to use for the single value background. For example, "#008000".
|
| showTrendIndicator | boolean | true | Specify whether to show or hide the single value trend indicator. |
| useTrendUnits | boolean | false | Specify whether to truncate the trend value to two significant digits. A magnitude unit is displayed. |
| trendDisplayMode | (percent | absolute) | absolute | Specify whether the trend value is displayed as a percentage or an absolute count. |
| numberPrecision | number | 0 | Specify the number of decimal places to display. For example, to display three decimal places, enter a value of 3. The maximum value is 20. |
| useThousandSeparators | boolean | true | Specify whether numeric values use commas as thousandths separators. |
| radialBackgroundColor | string | none | Specify a color in hex code to customize the radial background color. For example, "#FFFFFF".
|
| radialStrokeColor | string | none | Specify a color in hex code to customize the radial stroke color. For example, "#FFFFFF".
|
Default properties
In addition to the settings in the options field, there are two default fields that you can set. These are not options, but should be placed at the same level as the options field.
showProgressBar shows a progress bar as a visualization loads and is set to false by default.
showLastUpdated shows the last time the visualization was refreshed and is set to false by default.
You can enable these features by adding the properties to a visualization, and changing the settings to true.
In the following example, the visualization will override the default for showProgressBar and show a progress bar as it loads.
"viz_tpRnLS1I": {
"type": "viz.singlevalue",
"showProgressBar": true,
"options": {
"showSparkline": false,
"backgroundColor": "#ffffff"
},
"title": "Does have a progress bar",
"description": "Due to viz override",
"dataSources": {
"primary": "ds_o7IqGHcO"
}
|
PREVIOUS Scatter charts |
NEXT Single value icon |
This documentation applies to the following versions of Splunk® Dashboards App: 0.8.0, 0.9.0
Feedback submitted, thanks!