Splunk® Enterprise

Splunk Dashboard Studio

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

What is a dashboard definition?

A dashboard definition is a JSON schema containing five core sections, a description, and a title. Each of the five core sections contributes to creating a dashboard.

Section Description
visualizations Customize visualization options, such as visualization colors and labels.
dataSources Specify your data sources, searches, and options for each created search.
defaults Set global defaults that apply to all specified visualizations, such as the same color scheme for all pie charts.
inputs Define input types and options, such as a multiselect dropdown.
layout List inputs, change the canvas size, and modify dashboards.

The following is a code example of the five core sections as empty objects and the description and title as empty strings.

{
  "visualizations": {},
  "dataSources": {},
  "defaults": {},
  "inputs": {},
  "layout": {},
  "description": "",
  "title": ""
}

The source editor provides limited validation, and you can't select the editor's Back button to save your changes if you have formatting errors. You might want to use a JSON validator to ensure that your formatting is correct.

How to format JSON stanzas

Each of the five core sections is defined as a JSON-formatted stanza. Data sources, visualizations, inputs, defaults, and layout have similar hierarchies but crucial differences.

For example, naming a data source is different from naming a visualization. You can give your data source stanza a name, separate from the unique ID, using the name property. For visualizations, you can use the title property to provide a visualization with a title.

Using stanza punctuation

The following are a few standard JSON formatting rules with accompanying code examples.


When setting options in the options property, Boolean values and numbers do not require quotes.

"options": {
  "majorFontSize": 36,
  "deltaFontSize": 16,
  "deltaColor": "> deltaValue | rangeValue(deltaColorEditorConfig)",
  "showSparklineAreaGraph": true,
  "backgroundColor": "transparent"
}

Strings, such as plain text and hexadecimal color codes, must be wrapped in quotes.

"options": {
  "markdown": "# Overall Equipment Effectiveness (OEE) Metrics",
  "fontColor": "#999A9C"
}

Arrays must be enclosed in brackets.

"options": {
  "orientation": "horizontal",
  "backgroundColor": "transparent",
  "gaugeRanges": [
    {
      "from": 75,
      "value": "#EC4B43",
      "to": 100
    },
    {
      "from": 50,
      "value": "#FAE75F",
      "to": 75
    },
    {
      "from": 0,
      "value": "#61CAFA",
      "to": 50
    }
  ]
},

The list of options you use must be enclosed in curly braces, and commas must come at the end of the line after each option entry except the last.

"options": {
  "fillColor": "#080D12",
  "strokeColor": "transparent",
  "fillOpacity": 0.9
}

Commas must separate each stanza in a section except for the last. For example, suppose there are three visualization stanzas in the visualization section of a dashboard definition. In that case, each stanza is separated by a comma after the final closing curly brace, with the exception of the last visualization.

"visualizations": {
  "viz_qoHJXrYE": {
    "type": "splunk.markdown",
    "options": {
      "markdown": "# Business Operations Metrics",
      "fontColor": "#999A9C"
    }
  },
  "viz_9evXJmvv": {
    "type": "splunk.rectangle",
    "options": {
      "fillColor": "#080D12",
      "strokeColor": "transparent",
      "fillOpacity": 0.9
    }
  },
  "viz_RIFCcAe3": {
    "type": "splunk.markdown",
    "options": {
      "markdown": "# Body Assembly",
      "fontColor": "#7AD3F0"
    }
  }
}

Commas must separate each property setting except the last.

{
  "visualizations": {},
  "dataSources": {},
  "defaults": {},
  "inputs": {},
  "layout": {},
  "description": "",
  "title": ""
}

If you get formatting error messages, you can use one of the many JSON formatting websites to check your code to identify the error.

Example of a dashboard definition

View and edit your dashboard definition in the source editor. The dashboard definition is the JSON source code that renders the dashboard in the visual editor. The following dashboard definition is a complete example. An overview of each section follows the example.

Source code

Expand the box to view the complete definition. You can copy and paste the code into your own instance to see the data at work.


{
  "visualizations": {
    "viz_BHTFSi0R": {
      "type": "splunk.pie",
      "options": {
        "labelDisplay": "valuesAndPercentage"
      },
      "dataSources": {
        "primary": "ds_sKOnz7iP"
      }
    }
  },
  "dataSources": {
    "ds_sKOnz7iP": {
      "type": "ds.search",
      "options": {
        "query": "| inputlookup firewall_example.csv\n| stats count by host"
      },
      "name": "Search_1"
    }
  },
  "defaults": {
    "dataSources": {
      "ds.search": {
        "options": {
          "queryParameters": {
            "latest": "$global_time.latest$",
            "earliest": "$global_time.earliest$"
          }
        }
      }
    }
  },
  "inputs": {
    "input_global_trp": {
      "type": "input.timerange",
      "options": {
        "token": "global_time",
        "defaultValue": "-24h@h,now"
      },
      "title": "Global Time Range"
    }
  },
  "layout": {
    "type": "absolute",
    "options": {
      "display": "auto-scale"
    },
    "structure": [
      {
        "item": "viz_BHTFSi0R",
        "type": "block",
        "position": {
          "x": 140,
          "y": 60,
          "w": 800,
          "h": 470
        }
      }
    ],
    "globalInputs": [
      "input_global_trp"
    ]
  },
  "description": "Firewall hosts by percentage",
  "title": "Firewall Pie Chart"
}

The visualizations section

At the root of the JSON visualization section is "visualizations": { after which, all of your visualization stanzas are listed. Each visualization has a type. For example, a pie chart is of type splunk.pie.

Visualization options

Each visualization has an options field. All options available for that particular visualization are listed with each visualization topic and in the Object options reference. For more information on options available for each visualization, see the Object options reference.

All visualizations are called in the layout section.

The following is a code example of the visualizations section with a visualization stanza for a pie chart.

"visualizations": {
  "viz_BHTFSi0R": {
    "type": "splunk.pie",
    "options": {
      "labelDisplay": "valuesAndPercentage"
    },
    "dataSources": {
      "primary": "ds_sKOnz7iP"
    }
  }
},

Visualization fields and settings

Each visualization can have the following fields:

Field Description Required?
The unique ID The unique ID is automatically generated, but can be changed. If you change it, however, you must also change the visualization's ID in the layout section. Yes
type The type is the kind of visualization you are using. For example, the table visualization type is splunk.table. You can change the type in the source code, much like using the Visualization Picker in the visual editor. Ensure your search results contain the fields needed for your visualization type. For example, visualization maps need latitude and longitude fields. Without them, the map will not render. Yes
title This is the title name that will display on your visualization. It is not the same as the unique ID and will not change the unique ID. No
description You can use this field to add more context to your visualization within the visualization panel. No
options In this field, apply options to your visualizations, such as series colors, axis visibility, and background color. No
context This is the field where dynamic variable elements are defined. For example, if you've formatted a table column to change colors according to a range of values, the numeric ranges and values are specified in the context section. Yes, if dynamic elements are used, and only with visualizations of type, splunk.<visualization>.
dataSources.primary This is where the unique ID of your primary data source is listed. A visualization can have only one primary data source. No
dataSources.annotation This is where the unique ID of your annotation data source is listed. annotation is the only secondary data source that has its own designated name. No

The dataSources section

The dataSources section of the dashboard definition is where you can modify the data source stanzas created in the source editor. You can add searches to your visualizations in the data source section of the Configuration panel or directly in the dataSources section of the dashboard definition. At the root of the section is "dataSources": {. This is where you place each data source stanza.

Unique IDs

When you create a new data source in the form of an ad hoc search or chain search through the visual editor Configuration panel, a unique ID is automatically created for each data source. Each data source must have a unique ID. You can change this unique ID as long as it remains unique in your dashboard definition.

Data source types

Each data source has a type field. There are four data source types:

  • ds.search
  • ds.chain
  • ds.savedSearch
  • ds.test

Data source options

Each data source has an options field. For more information on data sources and their types, see Data source options and properties.

The following code example uses "type": "ds.search" because the data source is using a search to gather data.

"dataSources": {
  "ds_sKOnz7iP": {
    "type": "ds.search",
    "options": {
      "query": "| inputlookup firewall_example.csv\n| stats count by host"
    },
    "name": "Search_1"
  }
},

The defaults section

Use the defaults section to define global settings for any or all data source or visualization types. All settings applied at the component or stanza level override those in the defaults section. For more details about the defaults section, examples, and the options available, see Set global and local defaults.

The following is an example of what a defaults section looks like:

"defaults": {
  "dataSources": {
    "ds.search": {
      "options": {
        "queryParameters": {
          "latest": "$global_time.latest$",
          "earliest": "$global_time.earliest$"
        }
      }
    }
  }
},

The inputs section

Inputs have fields for their unique ID, type, title, and options. Like visualizations, inputs must be called in the layout section.

The following example is an input of the time range type:

"inputs": {
  "input_global_trp": {
    "type": "input.timerange",
    "options": {
      "token": "global_time",
      "defaultValue": "-24h@h,now"
    },
    "title": "Global Time Range"
  }
},

To view the available input types, their associated options, and more examples, see Use inputs to make dashboards dynamic.

The layout section

The layout stanza has four main settings fields:

Settings field Description
options The options field is where you set your dashboard settings.
globalInputs The globalInputs field is where you must list any inputs in your dashboard by their ID. If an input's ID is not in the globalInputs field, it doesn't appear on the dashboard canvas.
structure The structure field is where you define the width and height of visualizations and where visualizations are placed on the x-axis and y-axis of the dashboard canvas. If a visualization's ID is not in the structure field, it doesn't appear on the dashboard canvas.
type The type field is where you set the dashboard to either an absolute or grid layout. Don't change this setting for populated dashboards, especially from absolute to grid, because it will likely result in losing your visualizations and an error message.

The following is an example of a layout stanza:

"layout": {
  "type": "absolute",
  "options": {
    "display": "auto-scale"
  },
  "structure": [
    {
      "item": "viz_BHTFSi0R",
      "type": "block",
      "position": {
        "x": 140,
        "y": 60,
        "w": 800,
        "h": 470
      }
    }
  ],
  "globalInputs": [
    "input_global_trp"
  ]
},

The layout is also where you modify the canvas of your dashboard. For more information, see Compare absolute and grid layouts.

Use layout options to modify your dashboard canvas with the source editor

When you select the canvas of your dashboard, you can change many of the dashboard layout settings in the visual editor Configuration panel. There are some options, however, that you can only set in the source editor. For example, the source editor is the only place where you can add a submit button for inputs.

The dashboard definition's layout section is where the positions and sizes of visualizations, in pixels, are listed as they exist on the dashboard. You must also list any inputs in the globalInputs area of the layout section. For more information on inputs, see Use inputs to make dashboards dynamic.

In the source editor, the layout section is where you can change the canvas size, background color, and background image settings to modify your dashboards.

Layout options

Some of the following options are available through the visual editor and others are available only using the options level of the layout section of the dashboard definition.

Option Type Default Description
backgroundColor string lightmode: #FFFFFF darkmode: #FF0000 Splunk Cloud Platform: #171D21 This option is not available if you are using the grid layout. Specify the color of the layout background color using a hexadecimal code, such as #FF0000.
display actual-size or auto-scale actual-size This option is not available if you are using the grid layout. Grid layout is always auto-sized.

Specify the display behavior. If this property is set to actual-size, changing the size of your browser doesn't change the size of your dashboard or visualizations. If this property is set to auto-scale, your dashboard and visualizations automatically also change size.

submitButton Boolean n/a You can specify the layout option submitButton. When set to true, a user must select a Submit button for the input selection to take effect. If set to false or not specified at all, the dashboard immediately refreshes when a user makes a selection.
submitOnDashboardLoad Boolean n/a To have the dashboard load using the default input values, add the option submitOnDashboardLoad, which will automatically run searches on the first dashboard load. After the initial load, the user must select the submit button to refresh the dashboard's searches and visualizations. If you don't add submitButton then submitOnDashboardLoad doesn't work.
backgroundImage object n/a This option is not available if you are using the grid layout. A background image must be one of the following types: JPG, JPEG, PNG, SVG or GIF. You can also use a web-based image using the backgroundImage.src option.
backgroundImage.src SRC n/a This option is not available if you are using the grid layout. Specify the location of a background image using the option src. For example: "src": "https://www.myImageLocation.com/galleryX/image1.png".
backgroundImage.w number n/a This option is not available if you are using the grid layout. Specify the image width in pixels for w. Don't specify this option if you set the sizeType option. If you do, it will overrule that setting.
backgroundImage.h number n/a This option is not available if you are using the grid layout. Specify the image height in pixels for h. Don't specify this option if you set the sizeType option. If you do, it will overrule that setting.
backgroundImage.x number (0,y) This option is not available if you are using the grid layout. Specify the position in pixels of the background image on the x-axis. Don't specify this option if you set the sizeType option. If you do, it will overrule that setting.
backgroundImage.y number (x,0) This option is not available if you are using the grid layout. Specify the position in pixels of the background image on the y-axis. Don't specify this option if you set the sizeType option. If you do, it will overrule that setting.
backgroundImage.sizeType auto, contain, or cover contain This option is not available if you are using the grid layout. auto scales the image while maintaining the image proportion. contain increases the size of the image as much as possible without cropping or stretching it. cover increases the size of the image without stretching it. The image might be cropped vertically and horizontally to minimize empty space.
width number 1200 Specify the canvas width in pixels. The width option only applies to the absolute layout.
height number 900 Specify the canvas height in pixels. The height option only applies to the absolute layout.

Default options for the visualizations and layout sections

When some defaults are not changed in the visual editor, the corresponding source options and properties might not appear in the source editor. For example, if you don't change the default width and height of the dashboard, the width and height options and their settings don't appear in the editor. Similarly, if you don't change the display default, this option and setting also don't appear in the source code. To have them appear, you can either change the defaults or add and edit them manually in the source editor. The following is a layout example of these settings after the defaults have been changed in the visual editor.

"layout": {
  "globalInputs": [],
  "type": "absolute",
  "options": {
      "backgroundColor": "#C093F9",
      "backgroundImage":
        { "x": 0,                        
          "y": 0,                       
          "src": "splunk-enterprise-kvstore://5f6cc9810b19516995423ad1",                        
          "sizeType": "contain"            
        },
      "submitButton": true,
      "width": 1198,
      "height": 898,
      "display": "auto-scale"
  },
  "structure": []
},
Last modified on 28 September, 2022
PREVIOUS
Source code editor
  NEXT
Advanced dynamic options syntax

This documentation applies to the following versions of Splunk® Enterprise: 9.0.0, 9.0.1, 9.0.2


Was this documentation topic helpful?


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