Developing Dashboards, Views, and Apps for Splunk Web

 


Advanced charting options

NOTE - Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.

Advanced charting options

Splunk charts in dashboards and other views are highly customizable. You can make a wide variety of customizations through the Splunk Web UI with the Panel Editor, which enables you to change chart axis labels, define color ranges for gauges, configure stacking modes for column and bar charts, and much more.

When the basic customization options offered by the Panel Editor aren't enough, you can go "under the hood" and edit the panel XML directly to customize the appearance and behavior of your charts in additional ways. You can change axis label text styles, reverse chart axes, define specific color palettes for chart results, and much more.

You can customize the appearance of charts using either Simplified XML or Advanced XML. The syntax for charts differs slightly between Simplified and Advanced XML. For example, in Simplified XML syntax, charting controls are specified with option attributes. In Advanced XML, you specify the same thing using params to a HiddenChartFormatter module. For code examples, see the "Chart colors" section, below, as well as the sections that follow.

This topic provides a few common customizations using both Simplified and Advanced XML. For more information on building charts in simplified XML, refer to adding a chart to your dashboard. Refer to the Custom Chart Configuration Reference in this manual for a complete list of chart customizations available.

Chart customization and non-Flash chart displays

Dashboards built from Simplified XML use the JSChart module to render graphics. JSChart uses JavaScript to build the graphics for a chart. This provides charting support on platforms such as iOS mobile devices that cannot display Flash-based graphics. The JSChart module also provides better printing quality.

Any chart that you create and edit through Splunk Web (for example, using the Report Builder, the Add to Dashboard dialog, and the Dashboard and Panel Editors) use Simplified XML. Thus the JSChart module renders the graphics for a chart using JavaScript – Flash is not required.

Unsupported JSChart properties

Caution: Splunk offers a wide array of dashboard chart customization properties that are not currently supported by the JSChart module. Using any of these properties with JSChart affects how dashboards are displayed:

  • Dashboard using Simplified XML To render a chart using unsupported properties for JSChart, Splunk uses FlashChart, the Flash-based charting module. This means that the chart won't displays in platforms that do not support Flash. The exception is iOS, in which case Splunk will still use JSChart but will ignore any unsupported properties.
  • Dashboard using Advanced XML In Advanced XML you need to specify the charting module (JSChart or FlashChart) for each chart in the dashboard. For a chart that uses the JSChart module Splunk simply ignores unsupported properties.

For example, consider a dashboard created using Simplified XML that contain a panel with a line chart. If you edit the seriesColors chart customization property, which is unsupported by the JSChart module, Splunk will render the line chart with FlashChart. The line chart displays correctly in browsers that support Flash, incorrectly on an iOS device such as an iPad, and not at all on other platforms that don't support Flash.

Splunk applies charting modules in dashboards on a panel by panel basis. It is possible to have a dashboard where some charts use the JSChart module while others use FlashChart.

Note: All of the charting customizations described in the following topics (series colors, brushes, palettes, and so on) are not supported by the JavaScript-based charting module. If you implement them using Simplified XML, the resulting charts display only on platforms supporting Flash.

For more information about what charting parameters are supported by the Java-script charting module and what charting parameters are not, see the Custom Charting Configuration Reference in this manual.

JSChart display issues

The JSChart charting module has some display issues that may be resolved in upcoming releases.

Non-transforming searches

The JSChart module cannot render charts based on searches that do not include (or properly use) transforming search commands such as chart, timechart, stats, or eval.

The FlashChart module will attempt to chart the results of non-transforming searches, but charts won't revert to FlashChart automatically when non-transforming searches are used. You will need to explicitly specify that Splunk use the FlashChart module in the charting XML.

Time Charting

JSChart can only plot time-based data using the timechart command. If you try to plot a time-based series using any other transforming search command, JSChart treats the timestamp data as a series of strings.

FlashChart can plot time-based data with other transforming search commands.

Search result truncation

For performance reasons, the JSChart module truncates search result data sets that are too large. The exact limits that trigger this truncation depend on the browser being used as well as the charting configuration. When the JSChart module is caused to truncate data sets, it displays an error message below the chart. To remove the error message you can:

  • Switch to a chart type that involves drawing only one shape per series (in other words, move from a column chart to a line chart).
  • Control the number of results generated. An example with the timechart command can be consulted here on Splunk Answers.
  • Reduce the number of fields that are being plotted.
  • For time charts, use a longer time-span between data points.

There are additional conditions that can cause truncation:

  • Searches that return too many results per series can cause JSChart to hang the browser. Splunk employs a throttling strategy that restricts the number of results returned per series to 500 by default. You can configure this value by going to JSChart.conf and changing the maxResultsCount parameter to something other than 500.
  • JSChart can only plot the first 50 series that are returned. Additional series will not be plotted.
  • Object rendering limits by charting module. Both charting modules have rendering limits if the total number of objects plotted in the chart exceeds a certain number. If you run into this limit you'll want to change either the search string or search time range so that the results returned fall under the limit.
    • For the FlashChart module, the rendering limit in all cases is 2000 objects. If you hit this limit, the chart stops rendering.
    • The JSChart module has a 2000 object limit for line charts, a 1200 object limit for other chart types, and a 1000 object limit for charts built in Internet Explorer. If you hit the limit with a chart that uses JSChart, Splunk provides an error message.

Category limit

In JSChart, when you are plotting data on a categorical axis, no more than 80 categories can be displayed. When there are more than 80 categories Splunk doesn't truncate the data but instead hides the labels and tick marks. This is not configurable; Splunk runs into performance issues if you go higher than this. If you need to display a large number of axis categories, use FlashChart. It has a much higher limit.

Chart rendering limits

Both charting modules have limits as to the full number of objects/pixels that they can render.

Chart colors

You may want to set a specific set of colors for a series in a chart. To change chart colors, use the seriesColors property charting.seriesColors. The seriesColors property is the simplest way to adjust the colors of series in a Splunk chart. It is represented as a list of hexadecimal color values (0xRRGGBB values separated by commas and surrounded by brackets).

For example, in a Simplified XML dashboard:

<dashboard>
 <label>My dashboard</label>
 <row>
  <chart>
   <searchName>My saved report</searchName>
     <option name="charting.seriesColors">
       [0xFF0000,0xFFFF00,0x00FF00]
     </option>
   </chart>
  </row>
</dashboard>

In an Advanced XML dashboard, use the charting options with HiddenChartFormatter:

...
<module name="HiddenChartFormatter">
  <param name="charting.seriesColors">
    [0xFF0000,0xFFFF00,0x00FF00]
  </param>
...

Series colors for Splunk charts are index-based, which means that a color is assigned to a particular series based on its index among all other series assigned to legend labels in a specific order. (This usage of "index" does not refer to Splunk event indexes or indexers). Given the seriesColors list defined above, the first series of a chart is assigned color 0xFF0000 (red), the second series 0xFFFF00 (yellow), and so on.

For example, in a Simplified XML dashboard:

<dashboard>
 <label>My dashboard</label>
 <row>
  <chart>
   <searchName>My saved report</searchName>
    <option name="charting.legend.labels">[error,warn,info]</option>
    <option name="charting.seriesColors">[0xFF0000,0xFFFF00,0x00FF00]</option>
   </chart>
  </row>
</dashboard>

In an Advanced XML dashboard, use the charting options with HiddenChartFormatter:

...
<module name="HiddenChartFormatter">
  <param name="charting.legend.labels">[error,warn,info]</param>
  <param name="charting.seriesColors">[0xFF0000,0xFFFF00,0x00FF00]</param>
...

This assigns the series named error to the color 0xFF0000 (red) and the series named warn to the color 0xFFFF00 (yellow) (and so on) from the seriesColors list above.

However, if there are other charts in a view, this mapping is not necessarily be guaranteed. That's because all legends for all charts in a view are connected to a common "master legend" by default to synchronize their colors. The master legend determines the final label/series index mapping from the merged mappings of its "slave" legends. The first slave legend to be processed by the master legend (typically the first one in a view) has its labels placed before the labels of the next legend to be processed (minus duplicates). Therefore, error at series index 0 in the labels list above is not necessarily at series index 0 in the master list. To alleviate this problem, you can exclude a legend from synchronization by assigning its masterLegend property to null or an empty string.

For example, in a Simplified XML dashboard:

<dashboard>
 <label>My dashboard</label>
 <row>
  <chart>
   <searchName>My saved report</searchName>
    <option name="charting.legend.labels">[error,warn,ok]</option>
    <option name="charting.seriesColors">[0xFF0000,0xFFFF00,0x00FF00]</option>
    <option name="charting.legend.masterLegend"></option>
   </chart>
  </row>
</dashboard>

This guarantees a one-to-one mapping between the labels and seriesColors lists above.

But what if you want to assign a color to a particular series based on its name instead of its series index? In that case use the fieldColors property to map specific colors to particular fields. The fieldColors property is represented as a map of field/color pairs surrounded by curly braces:

<option name="charting.fieldColors">
  {"error":0xFF0000,"warn":0xFFFF00,"info":0x00FF00}
</option>

This example assigns the series named error to the color 0xFF0000 (red), the series named warn to the color 0xFFFF00 (yellow), and the series named info to the color 0x00FF00 (green). Although not required in this case, double quotes must surround field names containing any of these characters []{}(),:". Existing double quotes or backslashes in the field name must be escaped with a preceding backslash.

Brushes and palettes

The entire concept of a series "color" is a drastic simplification of how a series, or any other visual element in Splunk charts, is actually styled. For example, the default style of all series in Splunk charts is not a solid color at all--it's a gradient of two colors. The seriesColors property described earlier is actually a convenience property to simplify the complexity of how chart styles are really defined. If you're only interested in changing the default series color mappings of a chart, while keeping the rest of the default styling, then the seriesColors property will suffice. If, however, you want more elaborate styling beyond the default gradients or even beyond colors, you need to become familiar with the underlying brush and palette architecture.

All visual elements in Splunk charts, with the exception of text, are "painted" using brushes. A brush can paint fills, strokes, gradients, images, and even video. Some brushes can combine and layer these methods. For example, a Solid Fill Brush paints solid color fills, while a Solid Stroke Brush paints solid color strokes. There is also a Group Brush that paints with a group of brushes simultaneously. You might use the Group Brush to paint a solid color fill surrounded by a solid color stroke, for example.

Here's an example of how a custom brush with a solid red fill and 50% transparency might be defined:

<dashboard>
 <label>My dashboard</label>
 <row>
  <chart>
   <searchName>My saved report</searchName>
    <option name="charting.myBrush">solidFill</option>
    <option name="charting.myBrush.color">0xFF0000</option>
    <option name="charting.myBrush.alpha">0.5</option>
  </chart>
 </row>
</dashboard>

Charts often have several series to plot, which means they usually need several brushes, one for each series. But spending your time designing unique brushes for individual series for all the different chart visualization options doesn't scale, especially if you have views that include dozens of series. Instead, charts use brush palettes. A brush palette maps a series index to a brush. There are a variety of brush palettes for Splunk charts. The simplest brush palette is the Solid Fill Brush Palette, which generates a solid fill brush for each series in a chart.

To determine the color of each brush it generates, the Solid Fill Brush Palette uses another type of palette - a color palette. Similar to a brush palette, a color palette maps a series index to a color. For example, a List Color Palette maps a series index directly to a color from a specified list of colors. By default, if an index is out of range of the list of colors, it wraps around to the beginning of the list, essentially repeating the colors. The List Color Palette can optionally interpolate between the list of colors, instead of wrapping, to produce a range of colors that spans over the total number of series. The following example specifies a color palette that interpolates between red, green, and blue:

<dashboard>
 <label>My dashboard</label>
 <row>
  <chart>
   <searchName>My saved report</searchName>
    <option name="charting.myColorPalette">list</option>
    <option name="charting.myColorPalette.colors">[0xFF0000,0x00FF00,0x0000FF]</option>
    <option name="charting.myColorPalette.interpolate">true</option>
   </chart>
  </row>
</dashboard>

Property references

In order to use the color palette defined above to generate Solid Fill Brushes for a chart, reference it from the appropriate property of a Solid Fill Brush Palette. To reference a property to use as the value of another property, use the "@" symbol followed by the property name to reference (minus the "charting" prefix). The Solid Fill Brush Palette has a colorPalette property that expects a color palette as its value:

<option name="charting.myBrushPalette">solidFill</option>
<option name="charting.myBrushPalette.colorPalette">@myColorPalette</option>

Again use a property reference to create a Column Chart whose columns are painted using the brushes generated from myBrushPalette. The Column Chart has a columnBrushPalette property designed specifically for this purpose:

<option name="charting.chart">column</option>
<option name="charting.chart.columnBrushPalette">@myBrushPalette</option>

You can also use a property reference in the original definition of myColorPalette to reference another property defining the list of colors. This is exactly how the simple seriesColors property described earlier is wired up to the underlying default set of brushes and palettes in Splunk charts:

<option name="charting.myColorPalette.colors">@seriesColors</option>

Create chart options on the fly

You can define your own properties on the fly by simply declaring them. For example, the following declares a custom brush with a red solid fill:

   <option name="charting.myBrush">solidFill</option>
   <option name="charting.myBrush.color">0xFF0000</option>

You can assign a property to another property either by reference or copy. The "@" symbol denotes a property reference and the "#" symbol denotes a property copy (or clone). For example, to use the custom brush defined above as the background of the tooltip, you can use a property reference:

   <option name="charting.tooltip.backgroundBrush">@myBrush</option>

However, if you would like to use a brush that's the same as the custom brush defined above except it has an alpha transparency of 50%, you can clone it then modify the alpha property of the clone.

 
   <option name="charting.tooltip.backgroundBrush">#myBrush</option>
   <option name="charting.tooltip.backgroundBrush.alpha">0.5</option>

If you need to use either the "@" or "#" symbols as the first character of a string (for example, an axis title), you can escape it with a second symbol:

 
   <option name="charting.axisTitleY.text">## Of Downloads</option>
   <option name="charting.axisTitleX.text">@@Foo</option>

This documentation applies to the following versions of Splunk: 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 , 4.3.7 View the Article History for its revisions.


Comments

Dmcguerty, I suggest you consult the docs for Splunk Enterprise 6.1 (http://docs.splunk.com/Documentation/Splunk/latest/AdvancedDev/CustomChartingConfig-FontColorBrushPalette).

The docs here for Splunk 4.3 have been updated several times for subsequent releases.

Starting with Splunk Enterprise 6.0, simple XML has been enhanced to provide functionality previously only available with advanced XML.

Vgenovese
June 6, 2014

Need to be clear about colors for a field value vs for a field. In many charts, there is one field with multiple values. IE the *values* are 'error','warn' or 'info'. The writing implies these are three different fields rather than three different values of *a* field. Which is it?

[error,warn,info]
[0xFF0000,0xFFFF00,0x00FF00]

Dmcguerty
June 5, 2014

There is a workaround to this limitation:

"JSChart can only plot time-based data using the timechart command. If you try to plot a time-based series using any other transforming search command it will treat the timestamp data as a series of strings"

"makecontinuous " will let JSCharts display the time series fine (tested in flashtimeline and in a SimpleXML dashboard). E.g.:

index=_internal sourcetype=splunkd | bucket _time span=1d | stats count by _time component | xyseries _time component count | makecontinuous _time

Paolo

Stige
January 24, 2012

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

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!