Tokenhandling in SimpleXML-Dashboards
SimpleXML-Dashboards sind in Splunk eines der zentralen Werkzeuge, um Daten interaktiv und benutzerfreundlich zu visualisieren. Ein entscheidendes Element, das die Dynamik dieser Dashboards ermöglicht, ist das Tokenhandling – der Einsatz von Platzhaltern, die Werte zwischen Input-Elementen, Panels und Suchabfragen übergeben. Das gezielte Arbeiten mit Tokens ermöglicht es, dynamische, interaktive und kontextabhängige Dashboards zu erstellen, die sich intelligent an die Interaktion des Benutzers anpassen.
In diesem Artikel werfen wir einen detaillierten Blick darauf, wie Tokens effektiv eingesetzt werden können, um die Funktionalität von Dashboards zu erweitern. Wir zeigen verschiedene Möglichkeiten, Tokens zu erstellen und zu nutzen, und illustrieren diese mit konkreten Beispielen.
Reagieren auf Wertänderungen in Input-Elementen
Eine der wichtigsten Funktionen von Tokens ist die Möglichkeit, auf Wertänderungen in Input-Elementen zu reagieren. Dies erfolgt häufig unter Verwendung des <change>-Statements in SimpleXML. Innerhalb des <change>-Blocks können Tokens mit <set>, <unset> oder <eval> bearbeitet werden. Zusätzlich kann das <condition>-Statement genutzt werden, um logische Verzweigungen (ähnlich einem if-else-Konstrukt) zu erstellen.
Beispiel: Label eines Dropdown-Inputs dynamisch setzen
Ein praktisches Beispiel ist das Setzen des Labels eines Dropdown-Inputs basierend auf der Auswahl des Benutzers. So lässt sich beispielsweise die Überschrift eines Diagramms anpassen, wenn ein Wert aus einem Dropdown ausgewählt wird – besonders hilfreich, wenn sich der Anzeigetext und der Wert der Auswahl unterscheiden (z. B. bei Abkürzungen oder Übersetzungen).
<panel>
<input type="dropdown" token="tok_status">
<label>Auswahl Status</label>
<choice value="online">verfügbar</choice>
<choice value="occupied">belegt</choice>
<choice value="disconnect">offline</choice>
<choice value="unknown">unbekannt</choice>
<default>online</default>
<change>
<set token="tok_status_label">$label$</set>
</change>
</input>
<html>
<span>Es wurde Status "$tok_status_label$" ausgewählt</span>
</html>
</panel>
Mit dem Platzhalter $label$ lässt sich das Label der Auswahl zugreifen, wodurch eine flexiblere Benutzererfahrung ermöglicht wird.
Beispiel: Anzeigen und Verstecken von Elementen
Ein weiteres Beispiel für die Verwendung von Tokens ist das dynamische Steuern der Sichtbarkeit von Panels, basierend auf der Auswahl eines Radio-Buttons. Dafür verwenden wir <set>, <unset> und <condition> für die dynamische Änderungen.
<panel>
<input type="radio" token="tok_panel_selection">
<label>andere Panel anzeigen?</label>
<choice value="1">ja</choice>
<choice value="0">nein</choice>
<default>0</default>
<change>
<condition value="1">
<set token="tok_show">True</set>
</condition>
<condition value="0">
<unset token="tok_show"></unset>
</condition>
</change>
</input>
</panel>
<row depends="$tok_show$">
…
</row>
In diesem Beispiel wird das Token tok_show gesetzt, wenn der Benutzer „ja“ auswählt, wodurch das zugehörige Panel sichtbar gemacht wird. Wird „nein“ ausgewählt, wird das Token wieder entfernt und das Panel ausgeblendet. <condition value> überprüft dabei den Wert der Eingabe mit dem angegebenen Wert für value.
Das Ein- und Ausblenden erfolgt dabei über depends=“$tokenPlatzhalter$“. Ist das darin definierte Token nicht definiert, wir das Panel oder die Zeile nicht angezeigt. Besitz der Token einen Wert, wird die Zeile oder das Panel mit deren Inhalt anzeigt.
Komplexere Bedingungen mit <condition match>
Das <condition>-Statement ermöglicht auch komplexere Bedingungen, die über einfache Vergleiche hinausgehen. Dies erfolgt beispielsweise über den match-Operator, der reguläre Ausdrücke verwendet, um mehrere Bedingungen zu kombinieren.
Beispiel: Rückmeldung zur Richtigkeit einer Antwort
In diesem Beispiel wird ein einfaches Quiz erstellt, bei dem der Benutzer eine Antwort auswählen muss. Abhängig von der Auswahl wird das Token tok_answer auf „Richtig“ oder „Falsch“ gesetzt.
<panel>
<title>Match-Condition und Eval Nutzung</title>
<input type="radio" token="tok_math">
<label>Berechne: 011₂+001₂</label>
<choice value="100">100</choice>
<choice value="012">012</choice>
<choice value="4">4</choice>
<choice value="011001">011001</choice>
<change>
<condition match="$value$==012 OR $value$==011001">
<set token="tok_answer">Falsch</set>
</condition>
<condition>
<set token="tok_answer">Richtig</set>
</condition>
</change>
</input>
<html>
<span>Antwort ist $tok_answer$.</span>
</html>
</panel>
Hier wird die Auswahl mit einem regulären Ausdruck verglichen, um zu überprüfen, ob die Antwort korrekt oder falsch ist.
Initialisierung von Tokens
Wenn ein Token zu Beginn eines Dashboards gesetzt werden soll, ohne dass der Benutzer eine Auswahl trifft, kann das <init>-Statement verwendet werden. Dies ist besonders nützlich für Tokens, die beim Laden des Dashboards bereits initialisiert werden müssen.
Beispiel: Fehlerzähler
In folgendem Beispiel wird ein Fehlerzähler initialisiert, der nur dann erhöht wird, wenn der Benutzer eine falsche Antwort auswählt. Dafür erweitern wir das Code-Beispiel „Rückmeldung zur Richtigkeit einer Antwort“.
<init>
<set token="tok_show_error">0</set>
</init>
Der Zähler soll nur erhöht werden, wenn der Nutzer eine falsche Antwort auswählt.
Dafür nutzen wir ein <eval> Statement. <eval> Statements erlauben das Filtern und Formatieren von Werten innerhalb des Statements. Prinzipiell sind alle Eval-Befehle der Splunk SPL zugelassen.
Hinweis: Ausnahmen bilden folgende Kommandos und können damit nicht im <eval> verwendet werden:
Möchte man die Eval-Befehle relative_time, strftime und strptime benutzten, muss man beachten, dass die Zeitzone des Benutzers verwendet wird. |
Für unser Beispiel benötigen wir Addition des vorherigen Token-Wertes mit 1:
…
<condition match="$value$==012 OR $value$==011001">
<set token="tok_answer">Falsch</set>
<eval token="tok_show_error">$tok_show_error$+1</eval>
</condition>
…
Um die Benutzerinteraktion mit der Frage sichtbar machen zu können, kann das Token ergänzt werden.
<html>
<span>Antwort ist $tok_answer$ (Anzahl Fehler $tok_show_error$).</span>
</html>
Beispiel: Überprüfen initialer Werte
Wenn das Dashboard von einem anderen Benutzer aufgerufen oder nach einer Änderung neu geladen wird, können Anpassungen vorgenommen worden sein, die sich auf die Darstellung des Dashboards auswirken. Ein Beispiel dafür ist das dynamische Anzeigen oder Ausblenden von Panels, basierend auf der Auswahl des Benutzers.
Dafür erweitern wir das Beispiel „Beispiel: Anzeigen und Verstecken von Elementen“, indem zusätzlich das Eingabefeld selbst bei der Auswahl von „nein“ verschwindet. Bei einem Reload der Seite durch beispielweise das Pressen von F5, soll dieses unsichtbar bleiben.
Um das Verstecken das Eingabefeldes umzusetzen, fügen wir ein depends in das <panel> Statement hinzu. Zusätzlich können wir das <change> Statement vereinfachen, da ein Wechsel von „ja“ zu „nein“ durch das Verstecken des Eingabefeldes nicht mehr möglich ist.
Das Beispiel sieht nach den Anpassungen wie folgt aus:
<panel depends="$tok_question_shown$">>
<input type="radio" token="tok_panel_selection">
<label>andere Panel anzeigen?</label>
<choice value="1">ja</choice>
<choice value="0">nein</choice>
<default>0</default>
<change>
<condition value="1">
<set token="tok_show">True</set>
<unset token="tok_question_shown"></unset>
</condition>
</change>
</input>
</panel>
Damit auch beim Neuladen des Dashboards die Frage nur angezeigt wird, wenn „nein“ ausgewählt wurde, können wir das <init>-Statement verwenden. Innerhalb des <init>-Statements können auch <condition>-Statements genutzt werden, um zu überprüfen, ob ein Token beim Laden des Dashboards einen bestimmten Wert hat und darauf basierend Aktionen auszuführen.
<init>
<condition match="$tok_panel_selection$ == 0">
<set token="tok_question_shown">True</set>
</condition>
</init>
Lädt man nun das Dashboard neu, wird das Panel nur angezeigt, sofern der Benutzer nicht bereits „ja“ ausgewählt hat.
Tokens in Visualisierungen
Tokens können nicht nur zur Steuerung von Panels verwendet werden, sondern auch innerhalb von Visualisierungen, um benutzerdefinierte Daten anzuzeigen. Das <selection>-Statement ermöglicht den Zugriff auf ausgewählte Zeiträume und Spaltenwerte.
<chart>
…
<selection>
<set token="selection.earliest">$start$</set>
<set token="selection.latest">$end$</set>
<set token="start.[fieldname]">$start.[fieldname]$</set>
<set token="end.[fieldname]">$end.[fieldname]$</set>
</selection>
…
</chart>
Die Token $start$ und $end$ repräsentieren die Unix-Zeitstempel des vom Benutzer ausgewählten Start- bzw. Endzeitpunkts. Falls der Benutzer keinen Zeitraum auswählt, entsprechen diese Werte dem voreingestellten Suchzeitraum.
Bei Timecharts kann der Zeitraum geringfügig abweichen, da dieser automatisch an die vom Benutzer definierte Zeitspanne (span) angepasst wird.
Das Token $start.[fieldname]$ gibt den Wert der Spalte für den ausgewählten Zeitraum zurück. Entspricht der Zeitraum dem Standard-Suchzeitraum (d.h. der Benutzer hat keine Anpassung vorgenommen), wird hier der Werte der Spalte zum $start$ Zeitpunkt verwendet. Der Platzhalter [fieldname] muss dabei auf den tatsächlichen Spaltennamen abgestimmt werden.
Ähnlich verhält es sich mit $end.[fieldname]$. Dieses Token gibt den Wert der entsprechenden Spalte zum Endzeitpunkt des Zeitraums zurück und schreibt diesen in das angegebene Token.
In Abbildung 1 wird eine einfache Anwendung des <selection> Statements gezeigt. Die Werte der Tokens werden unter dem Graphen anzeiget.
Zugriff auf Suchergebnisse mit Tokens
Splunk bietet die Möglichkeit, Suchergebnisse und Informationen zum Suchjob in XML auf Tokens zu übertragen. Das <done>-Statement ermöglicht den Zugriff auf die Suchergebnisse und Job-Eigenschaften, sobald der Suchauftrag abgeschlossen ist. Es wird häufig verwendet, um nach der Fertigstellung einer Suche auf die entsprechenden Daten zuzugreifen.
Es gibt jedoch eine Einschränkung: Auf die Suchergebnisse kann nur in der ersten Zeile zugegriffen werden. Wenn alle Ergebnisse benötigt werden, muss ein JavaScript-Event-Listener für das Ende der Suche eingerichtet werden.
Beispiel: Zugriff auf den häufigsten Sourcetype
Mit $result.[fieldname]$ kann auf die entsprechende Spalte im Suchergebnis zugegriffen werden. Im folgenden Beispiel wird der Sourcetype mit den meisten Events der letzten 30 Minuten sowie die Anzahl der Events jeweils auf ein Token geschrieben.
<search>
<query>
index=_internal
| stats count by sourcetype
| sort - count
</query>
<earliest>-30m</earliest>
<latest>now</latest>
<done>
<set token="tok_sourcetype">$result.sourcetype$</set>
<set token="tok_sourcetype_count">$result.count$</set>
</done>
</search>
Im <done>-Statement kann auch auf verschiedene Job-Eigenschaften zugegriffen werden, indem man $job.[jobParameter]$ verwendet. Mögliche Job-Parameter sind:
- $job.earliestTime$: Gibt den Startzeitpunkt des Suchzeitraums zurück.
- $job.latestTime$: Gibt den Endzeitpunkt des Suchzeitraums zurück.
- $job.resultCount$: Gibt die Anzahl der Zeilen zurück, die das Suchergebnis enthält.
- $job.runDuration$: Gibt die Laufzeit der Suche in Sekunden zurück.
- $job.message$: Liefert eine Liste von Debug-Nachrichten, die während der Suche generiert wurden.
Wird die Suche aufgrund eines Fehlers nicht erfolgreich abgeschlossen, werden die Statements im <done>-Block nicht ausgeführt. Stattdessen wird der Block nur bei erfolgreicher Ausführung der Suche ausgefüllt.
Wenn die Suche aufgrund eines Fehlers fehlschlägt und dieses Verhalten abgefangen werden soll, kann das <error>-Statement verwendet werden. In diesem Fall sind keine Suchergebnisse oder Job-Informationen verfügbar, aber Statements wie <set>, <unset> und <eval> können weiterhin genutzt werden.
Soll während der Suche bereits Feedback gegeben werden – beispielsweise um den Nutzer mitzuteilen, dass die Daten im Hintergrund verarbeitet werden –, kann das <progress>-Statement verwendet werden. Wie im <done>-Statement ist hier auch der Zugriff auf die erste Zeile der Suchergebnisse sowie die Job-Informationen möglich.
Fazit
Das Tokenhandling in SimpleXML-Dashboards von Splunk bietet eine leistungsstarke Möglichkeit, interaktive und dynamische Dashboards zu gestalten. Durch die gezielte Verwendung von entsprechender XML-Statements lässt sich das Verhalten von Dashboards präzise steuern, um benutzerfreundliche und kontextabhängige Visualisierungen zu erstellen. Mit dieser Flexibilität können Dashboards nicht nur an die Bedürfnisse der Benutzer angepasst werden, sondern auch die Benutzererfahrung erheblich verbessern.
Für eine vertiefende Schulung zu Splunk oder für Unterstützung bei der Implementierung komplexer Dashboards stehen wir Ihnen gerne zur Verfügung.
Kommentare
Keine Kommentare