Introduction to advanced views

Introduction to advanced views

This section introduces you to important concepts you need to build a view using Splunk's advanced XML syntax. Before you try to build an advanced view, you may want to build views with Splunk's UI view builder or the simple XML. You can always convert your simple views to advanced XML if you find the simpler syntax doesn't meet your needs.

By far, the most useful toolset you'll use while building views for Splunk is the info endpoint available at:

http://localhost:8000/info

(Replace with your Splunk host and port.)

This page offers a list of all available modules, RelaxNG schemas for view building and many other utilities.

Views

Every page in Splunk Web is custom built. These pages, or views, are XML files stored in an App's view directory. Views are made out of a library of modules. Every module is actually a directory of CSS, JavaScript, HTML and, in some cases, Python and Flash.

Views can be modified to fit your specifications. Or, you can create your own views from scratch. If you're just starting out, check out the simplified view XML described earlier in this manual. You should only use the advanced XML if you've tried the simple XML and it doesn't support your use case. For example, if you want to build a search view, or you want to use modules that aren't available to the simple XML.

Example views

There are many example views in this section of the documentation. Many of these views are available in the UI examples app. Download this app from Splunkbase here. Install the app to add all the views to your Splunk install.

Modules

Every element you see on a page in Splunk Web is a module, from the search bar to the results. Even some elements you don't see -- like searches running in the background to populate results -- are modules as well. Configure views by choosing which modules you want to display, and linking them together.

http://localhost:8000/modules

Params

Use params to configure modules. Params control module-specific configurations, such as the size of a graph or chart, or the number of events to display per page. Params are noted on the module reference page, or in the module's conf file. For example:

<module name="Message">
  <param name="filter">*</param>
</module>

Some params are required, while some are optional. Some params have default settings. All param settings are noted in the module reference. If a param is required, then you must include the param in the module. If a param is optional, you may include it with the module, but do not need to. If there is a default noted, that is the default value for that param, unless you set it. Params are also noted in a module's conf file, in the module's directory in $SPLUNK_HOME/share/splunk/search_mrsparkle/modules.

Module hierarchy

Modules in a view fit together in a tree structure. So if you're building a search view, search information gets passed from a module to its children. Each child module modifies the search in some way, until the search returns events, or is transformed into results. If you're building a dashboard view, each panel will likely be built from a separate search. You'll have more, but shorter, trees of modules in a dashboard view than a search view.

Modules at the top level of the hierarchy must specify a location within the view. Locations are known as layoutPanel. All other modules in the tree that don't have layoutPanel set inherit it from their parent. As you move through the page, into different layout panels, you must set the layout panel for the first module in that panel. Specify where your module should appear on the page by setting the layoutPanel attribute on the module tag. For example:

<module name="SearchBar" layoutPanel="mainSearchControls">

http://localhost:8000/en-US/app/search/charting?showsource=true

Intentions

Whenever you add a search to a view, you are using intentions. Specifically, modules pass searches passed between each other, modifying the searches by adding intentions as they pass the search down the tree. Once a series of intentions reaches a special type of module -- a dispatching module -- the intentions are composed into a search and that search is run in Splunk. Most results modules are dispatching modules -- if a results module doesn't have any results from a search by the time they are invoked in a view, the results module will compile the intentions and run the resulting search.

Layout templates

There are two main types of views: dashboards and search views. Each type of view is defined by a Mako template, located in $SPLUNK_HOME/share/splunk/search_mrsparkle/templates/view/. Mako templates are HTML files with support for Python. Splunk's layout templates define page layout; basically, how each element fits into a page.

Search views and dashboards use different layouts. Dashboards are laid out in a series of rows and columns while search views contain a search bar at the top and events view area, with a few other areas for customization. Search views are made from sets of search modules (see below). Your search is passed through any number of specified modules and results are displayed via one or more of the results modules. Dashboards display results from a variety of different searches, mostly via the results modules. You can add other modules to search and dashboard views, as you see fit.

If you find you're unhappy with the way a given template is laid out, your best bet is to modify the view's CSS. For example, you may want to float a module next to another module, or move one module underneath another module. For more information about how to change CSS for a view, see customize CSS in this manual.

Start your view

Here's a general outline of the basic concepts for configuring views:

1. Decide which modules you want to include in your view.
2. Configure each module in <view_name>.xml.
3. Put <view_name>.xml in the views directory, inside your app directory: $SPLUNK_HOME/etc/apps/<app_name>/data/ui/views/
4. If you have more than one view for your app, arrange them in the UI by following the instructions in Build navigation.
5. To change the CSS for a view, Customize CSS.

Useful URIs for view building

There are a few endpoints you should be aware of while you're working on building views, especially if you're working with the XML directly in the filesystem, and not through Splunk Manager.

Get a brand new view to show up:

https://localhost:8089/services/apps/local?refresh=true 

(replace with your host and Splunkd management port)

Reload a specific view:

https://localhost:8089/services/apps/local/<appname>?refresh=true 

(replace with your host and Splunkd management port)

Reload all views:

http://localhost:8000/app/<appname>/

(replace with your host and port)

Reload nav:

https://localhost:8089/servicesNS/admin/<appname>/data/ui/nav?refresh=1

Important notes about XML

There are a few things you should note about XML, especially if you've never worked with it before. Please read through this section -- it will make your whole view building experience more pleasant.

XML escaped characters

There are five characters that are not supported in XML. These are ", ', <, > and &. You must escape them much like URL encoding:

"

'

<

>

&

Schemas and editors

Many XML editors will let you load a schema -- DTD, XSD, Relax, RelaxNG are just a few different types of schemas. Schemas are useful for validating your XML and also for providing you with guidelines while building an XML file. Splunk contains RelaxNG formatted schemas for views, from dashboards to form searches to advanced XML views. Read more about how to use Splunk's schemas in the Use schemas topic in this manual.

• Was this topic useful?
• Post a comment