Splunk: Suchen, Token und Eventhandling in JavaScript

In einigen Splunk-Dashboards reicht es manchmal nicht aus, nur Simple XML zu verwenden. Wer beispielweise komplexere Berechnung und flexiblere Interaktionen realisieren möchte, kommt um die Verwendung von JavaScript nicht herum. In diesem Beitrag schauen wir uns an, wie man in einem Splunk Dashboard über JavaScript einfache Suchen ausführt, mit Tokens arbeitet und Eventhandling umsetzt, um so ein Grundstein für ihre eigene Lösung zu bieten.

 

Grundvoraussetzungen

Benötigte Dateien

Um JavaScript in einem Splunk-Dashboard zu nutzen, muss das Dashboard als Classic Dashboard (Simple XML) vorliegen und das script-Attribut in der XML-Datei eingebunden sein. Im scripts- Attribute können mehrere Scripts mit einem Komma getrennt eingebunden werden.

<dashboard version="1.1"script="JSdemo.js">
 ...
</dashboard>

Die JSdemo.js-Datei wird in einer Splunk App unter appserver/static/ abgelegt und beim Laden des Dashboards eingebunden.

Im Grundkonstrukt sieht die JSdemo.js-Datei wie folgt aus:

require([
    "splunkjs/ready!",
    "splunkjs/mvc/simplexml/ready!",
], function() {
    // JS Corpus
});

In required können verschiedene benötigte Module geladen werden. Um Zugriff auf diese zu erhalten, muss der Modul-Instanz in function() ein Namen gegeben werden. Die Reihenfolge ist dabei wichtig.
Splunk bietet mit seinem Webframework bereits verschiedene Funktionalitäten an, die man als Modul importieren kann.  
 

Änderungen laden

Wurden Änderungen am XML-Dashboard vorgenommen, kann man das Dashboard mithilfe des Aufrufens folgender URL neu laden:

<SplunkURL>/de-DE/debug/refresh 

Für Änderungen im XML muss folgende URL aufgerufen werden und auf „Bump version“ geklickt werden:

<SplunkURL>/de-DE/_bump 

Token abfragen und setzen

Im Javascript kann man auf die im Dashboard erstellten Token zugreifen und selbst auch diese Modifizierung oder löschen.
Dafür muss man das Modul splunkjs/mvc importieren. In diesem Beispiel importieren wir es unter den Namen mvc.
Mithilfe von get() kann der aktuelle Wert vom Token geholt werden. Existiert das Token nicht, erhält man den Wert undefined.
Mit set() kann ein beliebiger Wert auf ein Token gesetzten werden. Existiert das Token noch nicht, wird dieses erstellt.
Mit unset() kann man den Wert vom Token löschen bzw. das Token selbst löschen. 

require([
    "splunkjs/mvc",
    "splunkjs/ready!",
    "splunkjs/mvc/simplexml/ready!"
], function (
    mvc
) {
    TokenModel = mvc.Components.get("default");
    // Token abfragen
    let value = TokenModel.get("tok_get_example");  
    // Token setzen
    TokenModel.set("tok_set_example", "Text");
    // Tokenwert löschen
    TokenModel.unset("tok_unset_example");
})

Suchabfragen erstellen, ausführen, löschen und Ergebnisse erhalten

Suchabfragen und Post Process Searches erstellen 

Auch im JavaScript kann man Suchanfragen und Post Process Searches erstellen. Dafür benötigt man das Modul splunkjs/mvc/searchmanager. Im folgenden Beispiel haben wir es unter den Namen SearchManager importiert.

    let myBaseSearch = new SearchManager({
        id: "example-search",
        search: "index=_internal | timechart span=30s count by sourcetype",
        earliest_time: "-30m",
        latest_time: "now"
    });

Die in JavaScript erstelle Suche hat ähnlich zu einer Suche in XML eine ID, die eineindeutig sein muss, einen Such-Zeitraum (earliest_time und latest_time) und eine SPL.

Auch hier können in der SPL und in den Zeitraum Tokens verwendet werden. Diese müssen nicht vorher selbst aus dem Tokenmodel mit get() geholt werden, sondern können wie gewohnt mit den $-Symbol referenziert werden.
Eine Base Search erstellt man auf ähnliche Weise:
Hierfür benötigt man das Modul splunkjs/mvc/postprocessmanager. 

    let mySearch = new PostProcessManager({
       managerid: "example-search",
       search: "| table _time splunkd",
       id: "example-ppsearch"
   });

Wie bei einer Post Process Search in XML muss die ID der Base Search angegeben werden. Die Angabe einer ID ist keine Pflicht, sofern man diese nicht weiter referenzieren muss.

Zugriff auf Suchen 

Suchen die in XML erstellt wurden, sind auch in JS erreichbar.
Dafür benötigt man, wie bereits bei der Benutzung von Tokens, die mvc Modul-Instanz. In der Funktion mvc.Components.get() muss die Such-ID der XML Suchen angegeben werden. Mit diesem Such-Objekt kann man beispielweise die Suche neu starten oder auf die Ergebnisse zugreifen.

let xmlSearch = mvc.Components.get("xml_search_id");

Erstellt man eine Suche in JS, kann man direkt bei der Erstellung der Suchen, diese auf eine Variable speichern. Im Abschnitt „Suchabfragen und Post Process Searches erstellen“ sind myBaseSearch und mySearch die jeweiligen Such-Objekte der Suchen. Alternativ kann, wie bei in XML erstellten Suchen, die Such-Objekte über die mvc Modul-Instanz geholt werden.

Suche starten und stoppen

Möchte man eine Suche manuell neu starten, benötigt man das entsprechende Such-Objekt.
Mithilfe der Funktion startSearch() des Such-Objekt kann die Suche dann manuell gestartet werden.

searchObject.startSearch();

Möchte man eine Suche löschen, benötigt man nur die ID der Suche und die mvc Modul-Instanz. Mit der Funktion mvc.Components.revokeInstance() kann man die ID als Parameter übergeben und so die Suche löschen.

mvc.Components.revokeInstance("xml_search_id");

Suchergebnisse erhalten

In XML greift man Suchergebnisse einer Suche über das <done> Statement ab. Nachteil dabei ist es, dass man nur auf die erste Zeile der Spalten Zugriff hat.
In JS erhält man stattdessen Zugriff auf die kompletten Ergebnisse.
Dafür benötigt man wieder das Such-Objekt. Wie man dieses erhält, kann in den vorhergehenden Abschnitt „Zugriff auf Suchen“ nachgelesen werden. Im folgenden Beispiel greifen wir auf die Daten eines Such-Objekt mit den Namen SearchObject zu und erstellen einen Event Listener mit .on(), der überwacht, wann die Suche fertig ist. Mithilfe von data().fields erhält man Zugriff auf die Spaltennamen und mir data().rows auf die Ergebnisse der Suche.

    var searchDataInstance = SearchObject.data("results", { count: 0 });
   searchDataInstance.on("data", function() { 
       if (searchDataInstance.data() !== undefined){
               var data = searchDataInstance.data().rows;
               var fields = searchDataInstance.data().fields;
               // eventuelle weitere Datenverarbeitung
           }
       });

Eventhandling 

Neben dem Abfangen von Suchen ist es möglich auf weitere Events zu hören, sei es Änderung eines Tokens oder Inputs oder das Drücken eines Knopfes.

Token Änderung überwachen

Möchte man auf die Änderung eines Tokens reagieren, benötigt man wieder das Token Model. Für dieses erstellt man einen Eventhandler, und gibt den entsprechenden Tokens, die man überwachen möchte, mit den Prefix change: und Leerzeichen separiert an. Bei Änderungen eines dieser Tokens wird der Funktion das aktuelle Token Model und der neue Wert zurückgegeben. 

TokenModel.on('change:tokenA change:tokenB change:tokenC', function(model, value){         
           // ...
   })

XML Änderungen überwachen

Die Überwachung von XML Inputs erfolgt über die Instanz des Objektes. Wie bei den Suchen benötigt man die Instanz von dem Input. Diese erhält man wie bei Suchen über mvc.Components.getInstance() und der Angabe der ID in der Funktion oder durch das Schreiben auf einer Variable, wenn das Objekt in JS erstellt wurde. Auf dieses Objekt wird ein Event Listener mit .on() erstellt. Wird von Nutzer die Eingabe geändert, wird in der Funktion der neue Wert auf die Variable new_value geschrieben. Dadurch benötigt man keine Abfrage das Tokens des Input, um den aktuellen Wert zu erhalten.

inputObject.on('change', function(new_value){
               // ...
   })

Andere Objekte überwachen

Mithilfe von JQuery und JavaScript HTML DOM Document ist es auch in Splunk möglich, im JS andere Objekte vom Dashboard zu überwachen und auf verschiedene Änderungen wie beispielweise einen „Klick“ zu reagieren.
Im folgenden Beispiel überwachen wir einen Button, der in XML wie folgt erstellt wurde:

…          
<html>
    <button class="btn btn-primary" id="btn_click_me">Drück mich!</button>
</html>
…

Dieser Button kann nun z.B. über seine ID mithilfe von JQuery im Dashboard gefunden werden. Zudem kann man ein Event Listener darauf erstellen, der auf eine „Klick“ Aktion reagiert. Innerhalb des Aufrufs können weitere Funktionalitäten hinzugefügt werden, die auf diese Aktion reagieren.

   $('#btn_click_me').on('click', function () {
       // ...
   });

Fazit

Mit der Einbindung von JavaScript in Splunk-Dashboards eröffnen sich weitreichende Möglichkeiten, die über die Grenzen von Simple XML hinausgehen. Durch den gezielten Einsatz lassen sich noch interaktivere, dynamischere und leistungsfähigere Dashboards erstellen.

Dieser Beitrag hat einen grundlegenden Einstieg in die wichtigsten Konzepte und deren Umsetzung gegeben – von der Initialisierung benötigter Dateien über die Steuerung von Tokens bis hin zur Erstellung und Auswertung von Suchen.

Möchten Sie erfahren, wie man eigene Visualisierungen in Splunk baut oder Ihr Wissen noch weiter vertiefen, dann besuchen Sie eine unserer Schulungen! Weitere Informationen zum Schulungsangebot finden Sie unter: https://www.robotron.de/schulungszentrum/nach-autor/splunk
Gerne unterstützen wir Sie auch bei ihren Projekten und entwickeln eigene Lösungen für Sie.