% -*- Mode: noweb; noweb-code-mode: javascript-mode ; noweb-doc-mode: latex-mode -*-
\documentclass{article}
\usepackage{noweb}
\usepackage{hyperref}
\begin{document}

% Generate code and documentation with:
%
% noweave -filter l2h -delay -x -html simplesplunkjs.nw | htmltoc > simplesplunkjs.html
% notangle -Rtitle.js simplesplunkjs.nw > title.js
% notangle -Rindex.xml simplesplunkjs.nw > index.xml
% notangle -Rcputime.xml simplesplunkjs.nw > cputime.xml

\section{Introduction}

Splunk's SimpleXML is an XML file format to describe a custom dashboard
with searches, inputs and panels.  There are a number of
\nwanchorto{href="http://dev.splunk.com/getstarted}{fantastic resources}
for building them, but I recently encountered an interesting problem.
That link also discusses SplunkJS, a Javascript library that allows
users to customize searches and visualizations far beyond what SimpleXML
allows.

SplunkJS is usually used with raw HTML and CSS, but can be pulled into a
SimpleXML file by uing the [[script]] attribute in the SimpleXML opening
[[<dashboard>]] or [[<form>]] tag.  It's easy to make a SplunkJS search
and attach it to a SimpleXML visualization; it's not so easy to make a
SimpleXML search and attach it to a SplunkJS visualization.  This
document shows you how, and shows you how to fix a peculiarity that
arises from creating a well-organized ecosystem of panels and
dashboards.

In later versions of Splunk, SimpleXML has a new attribute for
[[<panel>]], [[ref]], which allows you to define a panel in a single
file and drop it into a number of different dashboards without having to
cut-and-paste the panel code.  In the process, SimpleXML mangles the
names of searches and visualizations, and so finding and manipulating
those searches has become difficult.

This example uses the Splunk Unix TA (Technology Add-on), so you should
download and install that.  What data you use isn't really important.
For our example, though, we're going to do is create a single dashboard
with a single independent panel that shows the list of processes running
on a host, find that panel, find it's search, find it's title, and
modify the title with the name of the longest-running process.

After installing Splunk (here's the
\nwanchorto{http://www.splunk.com/en_us/download/splunk-enterprise.html}{free
  version of the Enterprise Edition}, limited to a half-GB of data per
day) and getting it up and running, click on the App icon (the gear
symbol) on the left sidebar.  On the Applications list, click on "Create
a New App", and provide it with a name, a directory slug, and a version
number.

Now it's time to fire up your editor.  We need to create three things.
A dashboard, a panel, and a javascript file to perform the magic.

\subsection{Literate Program}

A note: this article was written with the
\nwanchorto{http://en.wikipedia.org/wiki/Literate_programming}{Literate
  Programming} toolkit
\nwanchorto{http://www.cs.tufts.edu/~nr/noweb/}{Noweb}. Where you see
something that looks like [[<<this>>]], it's a placeholder for code
described elsewhere in the document.  Placeholders with an equal sign
at the end of them indicate the place where that code is defined.  The
link (U->) indicates that the code you're seeing is used later in the
document, and (<-U) indicates it was used earlier but is being defined
here.

\section{The Dashboard Files}

The Dashboard file is simple.  We just want to pull in a panel.  This
goes into [[APP\_HOME/default/data/ui/views/index.xml]].  Here,
APP\_HOME is the path to the directory slug where your app is stored.  I
install Splunk in [[/opt]] and I named my example "searchhandle,"
thus the path is
[[/opt/splunk/etc/apps/searchhandle/default/data/ui/views/]].

<<index.xml>>=
<dashboard script="title.js">
  <label>A Dashboard with a portable Panel and a Managed Title</label>
  <description>A simple demonstration integrating SimpleXML and SplunkJS</description>
  <row>
    <panel ref="cputime" />
  </row>
</dashboard>
@ 

The panel file is also simple. It's going to define a search and a
table.  It goes in
[[APP\_HOME/default/data/ui/panels/cputime.xml]].  Note that the
filename must match the [[ref]] attribute.  I've limited the
search to the last hour, just to keep from beating my poor little laptop
to death.
<<cputime.xml>>=
<panel>
  <table>
    <title>Long-running processes</title>
    <search id="cputimesearch">
      <query>index=os source=ps | stats latest(cpu_time) by process | sort -latest(cpu_time)</query>
      <earliest>-1h@h</earliest>
      <latest>now</latest>
    </search>
  </table>
</panel>
@ 

The [[<dashboard>]] tag in our dashboard file has a
[[script]] attribute.  This is where we'll put our logic for
manipulating the title of our panel.  It's annoying that we have to put
our script reference in the dashboard and not the panel.  It's possible
to have a file named "dashboard.js" which will be loaded for \textit{every} XML
file in your app, and then have it selectively act on panels when they
appear.

\section{The Javascript}

Javascript files go in the [[APP\_HOME/appserver/static/]]
directory.  I've named ours [[title.js]].

Splunk uses the [[require]] facility to import files.  In the
prelude to any SplunkJS interface, you must start with the
[[ready!]] import, which doesn't allow the contents of this file
to run until the Splunk MVC (Model View Controller) base library is
loaded.  We're also loading the [[searchmanager]] and two utility
libraries: \nwanchorto{http://underscorejs.org/}{underscore} and
\nwanchorto{https://jquery.com/}{jquery}, both of which come with the
SplunkJS UI.

The one thing we're most concerned with is the [[registry]],
which is a central repository where all components of the current Splunk
job's client-side operations are indexed and managed.

The file's outline looks like this:

<<title.js>>=
require([
    "splunkjs/ready!",
    "splunkjs/mvc/searchmanager",
    "underscore",
    "jquery"
], function(mvc, searchManager, _, $) {

    var registry = mvc.Components;

    <<update the title with the data>>

    <<listen to the search for the data>>

    <<find the search>>

    <<wait for the search to be available>>
});
@ 

In the outline, we took one of the items passed in,
[[mvc.Components]], and gave it a name, the \textit{registry}.  Waiting
for the search to be available is as simple as listening to the
registry:

<<wait for the search to be available>>=

var handle = registry.on('change', findPanel);
@ 

Finding the search and attaching a listener to it is actually one of the
two hardest parts of this code.  First, because we have to \textit{find} it,
and the new panels layout makes that difficult, and secondly, because
the change event mentioned above can happen multiple times, but we want
to make sure we only set up our listener only once.

Below, the function [[findPanel]] lists through all the Splunk
managed objects on the page, and finds our search.  It does this by
looking for a registry name that matches the ID of our search.  The
panel layout mangles the name, attaching the prefix ``panelXX\_'' where
XX is some arbitrary index number.  (In practice, the index number is
probably deterministic, but that's not useful or important if you're
going to be using this panel on multiple dashboards.)  Underscore's
[[filter]] is perfect for finding out if our search is
available.  If it is, we disable the registry listener and proceed to
the next step, sending it the search name.

<<find the search>>=

var findPanel = function() {
    var panel = _.filter(registry.getInstanceNames(),
                         function(name) { return name.match(/panel\d+_cputimesearch/); });
    if (panel.length === 1) {
        registry.off('change', findPanel);
        setUpSearchListener(panel[0]);
    }
};
@ 

This is the most straightforward part of the code.  Having found the
search name, we then get the search manager, get its results manager,
and then set up a listener to it that will update the title with the
data.  

Splunk searches manage the \textit{task} of searching, but not the actual
data.  That happens in a Result, which updates regularly with the
growing cache of data from the server to the browser.  

This code skips a ton of details, mostly about listening to the search
for failure messages.  That's okay.  This is just an example, and it
works 99\% of the time anyway.  Since we're going to change the title to
include the longest-running process, and our search is pre-sorted, we
just need a count of one.  This Result uses the same dataset as the
actual visualization and puts no additional strain on the Splunk server
or bandwidth between the server and the browser.

<<listen to the search for the data>>=

var setUpSearchListener = function(searchname) {
    var searchmanager = registry.getInstance(searchname);
    var resultmanager = searchmanager.data("preview", {
        output_mode: "json",
        count: 1,
        offset: 0
    });
    resultmanager.on("data", updateTitle);
};
@ 

The last thing we do is update the title.  (Remember, that's our goal).
The panel's title is found in the [[.panel-head h3]] child
DOM object.  Finding the panel is trickier, but Splunk gives us an
attribute with the name of the panel's filename, so jQuery can find it
for us.  There's a guard condition to ensure that we actually have some
data to work with.

The names of the fields correspond to the final names in the search.
I've always found Splunk's naming conventions to be a little fragile,
but it works most of the time.

<<update the title with the data>>=

    var updateTitle = function(manager, data) {
        if ( !data || !data.results || !data.results.length) {
            return;
        }

        var topprocess = data.results[0];
        $("[data-panel-ref=cputime] .panel-head h3")
            .text("Longest Running Process: " + topprocess["Process"] +
                  " (" + topprocess["CPU Time"] + ")");
    };
@ 

\section{Navigation}

One last detail: You want to be able to get to this page.

To do that, open the file at:
[[APP\_HOME/default/data/ui/nav/default.xml]] and change the line for
search to look like this:

<<update navigation>>=
<view name="index" default='true' />
<view name="search" />
@ 

Now restart Splunk

And that's it.  Put it all together, and you've got yourself a working
application in which SplunkJS can tap into SimpleXML searches and
exploit their data, even if that search is defined in an independent
panel.

This code is available at my github at
\nwanchorto{https://github.com/elfsternberg/Splunk-SimpleXML-SplunkJS}{Splunk
  with SimpleXML and Javascript}.

\end{document}