Splunk® Enterprise

Dashboards and Visualizations

Download manual as PDF

Splunk Enterprise version 5.0 reached its End of Life on December 1, 2017. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Data structure requirements for visualizations

In this topic we cover the data structure requirements of the different types of visualizations offered for our reports and dashboards. If you're trying to generate a visualization, and are wondering why certain visualizations are unavailable, this is the topic for you.

Inappropriate viz.png

If you're getting the above error when you change the underlying search for an existing dashboard panel, or if you're creating a new panel and are finding that the visualization you want is unavailable, it's likely because the underlying search doesn't return data that will work for that visualization. In most cases, it's easy to tweak the search to get the visualization you want.

For example, most charting visualizations (column charts, line charts, area charts, bar charts, and so on) require search results that are structured as tables with at least two columns, where the first column provides x-axis values, and the subsequent columns provide y-axis values for each series represented in the chart (pie charts only provide information for single-series reports, while the other chart types can represent multiple series). To get these tables you need to set up the underlying search with reporting search commands like stats, chart, or timechart.

For a high-level overview of Splunk's visualization options, see the "Visualization reference," in this manual.

Column, line, and area charts

It's important to understand that column, line, and area charts are two-dimensional charts supporting one or more series. They plot data on a Cartesian coordinate system, working off of tables that have at least two columns, where the first column contains x-axis values and the subsequent columns contain y-axis values (each column represents a series). This is why "Values over time" searches and searches that include splitbys are among those that are available as column, line, and area charts.

If you want to generate a column, line, or area chart from a search, that search must produce a table matching the description provided in the preceding paragraph. For example, any search using the timechart reporting command will generate a table where _time is the first column (and therefore the x-axis of any column, line, or area chart generated from those results). You'll get the same result with most basic searches involving reporting commands.

For example, a search like this, where the over operator indicates that source is the x-axis:

...| chart avg(bytes) over source

produces a two-column, single-series table like this:

Two column chart.png

In this table, the x-axis is source, and the y-axis is avg(bytes). With it you can produce a column chart that compares the average number of bytes passed through each source.

Say you change up the search a bit by adding clientip as a splitby field:

...| chart avg(bytes) over source by clientip

This produces a table that features multiple series:

Multi-column chart.png

In this table, the x-axis is still source, and the y-axis is still avg(bytes), but it now separates the avg(bytes) by clientip, creating a table with multiple series. You might generate a stacked column chart to represent this data.

You run into trouble when you design a complex search that returns a result table that lacks a valid x-axis or y-axis value. This can happen when you use the eval and fields commands to force a particular arrangement of columns in the finished table, for example.

Bar charts

Bar charts have the same data structure requirements as column, line, and area charts, except that the x- and y-axes are reversed. So they are working off of tables that have at least two columns, where the first column contains y-axis values and the subsequent columns contain x-axis values.

Pie charts

Pie charts are one dimensional and only support a single series. They work off of tables with just two columns, where the first column contains the labels for each slice of the pie, and the second column contains numerical values that correspond to each label, determining the relative size of each slice. If the table generated by the search contains additional columns, those extra columns have no meaning in the terms of the pie chart and are ignored.

Of the two "column, line, and area charts" search examples noted above, the first is the only one that could be used to make a pie chart. The source column would provide the wedge labels, and the avg(bytes) column would provide the relative sizes of the wedges (as percentages of the sum of avg(bytes) returned by the search).

Scatter charts

Scatter charts are cartesian charts that render data as scattered markers. They help you visualize situations where you may have multiple y-axis values for each x-axis value, even when you're not charting multiple series. Their data set can be in one of two forms:

  • A single series setup, where the chart is structured on a 2-column data table, where the first column (column 0) contains the values to be plotted on the x-axis, and the second column (column 1) contains the values to be plotted on the y-axis.
  • A multiple series setup, where the chart is structured on a data table that contains 3 columns. The first column (column 0) contains the series names, and the next two columns contain the values to be plotted on the x- and y-axes, respectively.

To generate a scatter chart you need to graph events directly with a search like:

* | fields - _* | fields clientip bytes

This search finds all of the packets received from various client IP addresses and then orders them according to the number of bytes in each packet.

  • Note that the search removes all fields with a leading underscore, such as the _time field.
  • The second fields command isolates the two fields that you want for the x- and y-axis of the chart, respectively. The y-axis value should be numerical for best results. (So in this case, the x-axis is clientip while the y-axis is bytes.)

Note: To create a scatter plot chart with a search like this, you need to enter the reporting commands directly into the Report Builder by clicking Define report data using search language in the Report Builder. You can run this report from the search bar, but when you open up Report Builder, it adds a timechart command that you should remove before formatting the report.

More complex scatter charts can be set up in dashboards using Splunk's view XML. For more information see the Custom charting configuration reference chapter in the Developer manual.

Gauges and single value visualizations

Gauges and single value visualizations are designed to represent searches that return a single numerical field value. Gauges show where this value exists within a defined range, while single value visualizations just display the number.

A simple example is a search that returns a count of the number of events matching a set of search criteria that come in within a specific time period, or a real-time window, if you are using a real-time search. If you base a gauge on a real-time search, the chart's range marker will appear to fluctuate as the value displayed within the real-time search window changes over time.

If you base a single value visualization on this same search, you'll see the value increase and decrease as the value returned by the real-time search changes over time. If you've used the rangemap command in conjunction with the search, the single value visualization will change color depending on the value returned.

Visualization reference
Understand basic table and chart drilldown actions

This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters