Annotations in Grafana

Im Zuge der diesjährigen Open Source Monitoring Conference durfte ich mit Timeseries & Analysis with Graphite and Grafana einen der Workshops am Vortag der eigentlichen Konferenz halten. Wie man dem Titel unschwer entnehmen kann spielte dabei auch Grafana eine besondere Rolle. Grafana ist vielen als schöneres Dashboard für Graphite bekannt und unterstützt mit Elasticsearch, CloudWatch, InfluxDB, OpenTSDB, Prometheus, MySQL als auch Postgres in der aktuellen Version 4.6.2 allerdings noch eine ganze Reihe weiterer Datensourcen nativ. Zusätzlich können diese herkömmlichen Datensourcen auch noch durch Community Plugins ergänzt werden.
Ganz besonders hilfreich ist es wenn man die Informationen aus verschiedenen Datensourcen miteinander vereint. So lassen sich beispielsweise Zusammenhänge besser erkennen und Rückschlüsse auf bestimmte Ereignisse ziehen, die ansonsten vielleicht unentdeckt blieben. Metriken, die z.B. aus Graphite stammen, können bei Grafana nun durch sogenannte Annotations um zusätzliche Informationen angereichert werden. Neben Annotations aus den unterstützten Datensourcen können solche Events seit v4.6 übrigens auch direkt in der eigenen Grafana-Datenbank gespeichert werden, ob man das wiederum möchte ist allerdings eine ganz andere Frage…
Als Praxisbeispiel habe ich für meinen Workshop im Rahmen der OSMC überraschenderweise Icinga gewählt. Hier ist es möglich über die Icinga 2 API verschiedene Daten wie Checkergebnisse, Statusänderungen, Benachrichtigungen, Bestätigungen, Kommentare oder auch Downtimes mit dem Icingabeat direkt an Elasticsearch oder wenn man möchte alternativ auch an Logstash zu senden. Über das Annotation-Feature von Grafana lassen sich so die Benachrichtigungen aus Icinga über die Elasticsearch Datasource passend zu den jeweiligen Statusänderungen der Host- oder Serivcechecks einblenden:

Wer dazu mehr erfahren möchte dem kann ich unsere Graphite + Grafana Schulung ans Herz legen, neben vielen anderen Themen werden dort auch Grafana und Annotations in aller Ausführlichkeit behandelt. Und wer’s nicht schafft, für den findet sich vielleicht der ein oder andere passende Workshop im Rahmen unserer Konferenzen.

Markus Waldmüller
Markus Waldmüller
Lead Senior Consultant

Markus war bereits mehrere Jahre als Sysadmin in Neumarkt i.d.OPf. und Regensburg tätig. Nach Technikerschule und Selbständigkeit ist er nun Anfang 2013 bei NETWAYS als Lead Senior Consultant gelandet. Wenn er nicht gerade die Welt bereist, ist der sportbegeisterte Neumarkter mit an Sicherheit grenzender Wahrscheinlichkeit auf dem Mountainbike oder am Baggersee zu finden.

Manage Elasticsearch, Kibana & icingabeat with Puppet

A while back I’ve already looked into the Elastic Stack 5 Beta release and the beats integration. Time flies and the stable release is here. Blerim announced the icingabeat 1.0.0 release last week, and so I was looking into a smooth integration into a Vagrant box here.
The provisioner uses Puppet, which Puppet modules could be used here? I’m always looking for actively maintained modules, best by upstream projects which share the joy of automated setups of their tools with their community.
 

Elastic and Kibana Puppet Module

The Elastic developers started writing their own Puppet module for Kibana 5.x. Previously I’ve used community modules such as puppet-kibana4 or puppet-kibana5. puppet-elasticsearch already supports 5.x for a while, that works like a charm.
Simple example for a low memory Elasticsearch setup:

class { 'elasticsearch':
  manage_repo  => true,
  repo_version => '5.x',
  java_install => false,
  jvm_options => [
    '-Xms256m',
    '-Xmx256m'
  ],
  require => Class['java']
} ->
elasticsearch::instance { 'elastic-es':
  config => {
    'cluster.name' => 'elastic',
    'network.host' => '127.0.0.1'
  }
}

Note: jvm_options was released in 5.0.0.
 

Default index pattern

If you do not define any default index pattern, Kibana greets you with a fancy message to do so (and I have to admit – i still need an Elastic Stack training to fully understand why). I wanted to automate that, so that Vagrant box users don’t need to care about it. There are several threads around which describe the deployment by sending a PUT request to the Elasticsearch backend.
I’m using a small script here which waits until Elasticsearch is started. If you don’t do that, the REST API calls will fail later on. This is also required for specifying index patterns and importing dashboards. A Puppet exec timeout won’t do the trick here, because we’ll have to loop and check again if the service is available.

$ cat/usr/local/bin/kibana-setup
#!/bin/bash
ES_URL="http://localhost:9200"
TIMEOUT=300
START=$(date +%s)
echo -e "Restart elasticsearch instance"
systemctl restart elasticsearch-elastic-es
echo -e "Checking whether Elasticsearch is listening at $ES_URL"
until $(curl --output /dev/null --silent $ES_URL); do
  NOW=$(date +%s)
  REAL_TIMEOUT=$(( START + TIMEOUT ))
  if [[ "$NOW" -gt "$REAL_TIMEOUT" ]]; then
    echo "Cannot reach Elasticsearch at $ES_URL. Timeout reached."
    exit 1
  fi
  printf '.'
  sleep 1
done

If you would want to specify the default index pattern i.e. for an installed filebeat service, you could something like this:

ES_INDEX_URL="$ES_URL/.kibana/index-pattern/filebeat"
ES_DEFAULT_INDEX_URL="$ES_URL/.kibana/config/5.2.2" #hardcoded program version
curl -XPUT $ES_INDEX_URL -d '{ "title":"filebeat", "timeFieldName":"@timestamp" }'
curl -XPUT $ES_DEFAULT_INDEX_URL -d '{ "defaultIndex":"filebeat" }'

One problem arises: The configuration is stored by Kibana program version. There is no symlink like ‘latest’, but you’ll need to specify ‘.kibana/config/5.2.2’ to make it work. There is a certain requirement for pinning the Kibana version, or finding a programatic way to automatically determine the version.
 

Kibana Version in Puppet

Fortunately the Puppet module allows for specifying a version. Turns out, the class validation doesn’t support package revision known from rpm (“5.2.2-1”). Open source is awesome – you manage to patch it, apply tests and after review your contributed patch gets merged upstream.
Example for Kibana with a pinned package version:

$kibanaVersion = '5.2.2'
class { 'kibana':
  ensure => "$kibanaVersion-1",
  config => {
    'server.port' => 5601,
    'server.host' => '0.0.0.0',
    'kibana.index' => '.kibana',
    'kibana.defaultAppId' => 'discover',
    'logging.silent'               => false,
    'logging.quiet'                => false,
    'logging.verbose'              => false,
    'logging.events'               => "{ log: ['info', 'warning', 'error', 'fatal'], response: '*', error: '*' }",
    'elasticsearch.requestTimeout' => 500000,
  },
  require => Class['java']
}
->
file { 'kibana-setup':
  name => '/usr/local/bin/kibana-setup',
  owner => root,
  group => root,
  mode => '0755',
  source => "puppet:////vagrant/files/usr/local/bin/kibana-setup",
}
->
exec { 'finish-kibana-setup':
  path => '/bin:/usr/bin:/sbin:/usr/sbin',
  command => "/usr/local/bin/kibana-setup",
  timeout => 3600
}

 

Icingabeat integration

That’s fairly easy, just install the rpm and put a slightly modified icingabeat.yml there.

$icingabeatVersion = '1.0.0'
yum::install { 'icingabeat':
  ensure => present,
  source => "https://github.com/Icinga/icingabeat/releases/download/v$icingabeatVersion/icingabeat-$icingabeatVersion-x86_64.rpm"
}->
file { '/etc/icingabeat/icingabeat.yml':
  source    => 'puppet:////vagrant/files/etc/icingabeat/icingabeat.yml',
}->
service { 'icingabeat':
  ensure => running
}

I’ve also found the puppet-archive module from Voxpupuli which allows to download and extract the required Kibana dashboards from icingabeat. The import then requires that Elasticsearch is up and running (referencing the kibana setup script again). You’ll notice the reference to the pinned Kibana version for setting the default index pattern via exec resource.

# https://github.com/icinga/icingabeat#dashboards
archive { '/tmp/icingabeat-dashboards.zip':
  ensure => present,
  extract => true,
  extract_path => '/tmp',
  source => "https://github.com/Icinga/icingabeat/releases/download/v$icingabeatVersion/icingabeat-dashboards-$icingabeatVersion.zip",
  checksum => 'b6de2adf2f10b77bd4e7f9a7fab36b44ed92fa03',
  checksum_type => 'sha1',
  creates => "/tmp/icingabeat-dashboards-$icingabeatVersion",
  cleanup => true,
  require => Package['unzip']
}->
exec { 'icingabeat-kibana-dashboards':
  path => '/bin:/usr/bin:/sbin:/usr/sbin',
  command => "/usr/share/icingabeat/scripts/import_dashboards -dir /tmp/icingabeat-dashboards-$icingabeatVersion -es http://127.0.0.1:9200",
  require => Exec['finish-kibana-setup']
}->
exec { 'icingabeat-kibana-default-index-pattern':
  path => '/bin:/usr/bin:/sbin:/usr/sbin',
  command => "curl -XPUT http://127.0.0.1:9200/.kibana/config/$kibanaVersion -d '{ \"defaultIndex\":\"icingabeat-*\" }'",
}

The Puppet code is the first working draft, I plan to refactor the upstream code. Look how fancy 🙂

Conclusion

Managing your Elastic Stack setup with Puppet really has become a breeze. I haven’t tackled the many plugins and dashboards available, there’s so much more to explore. Once you’ve integrated icingabeat into your devops stack, how would you build your own dashboards to correlate operations maintenance with Icinga alerts? 🙂
If you’re interested in learning more about Elastic and the awesome Beats integrations, make sure to join OSDC 2017. Monica Sarbu joins us with her talk on “Collecting the right data to monitor your infrastructure”.
PS: Test-drive the integration, finished today 🙂


 
 

Michael Friedrich
Michael Friedrich
Senior Developer

Michael ist seit vielen Jahren Icinga-Entwickler und hat sich Ende 2012 in das Abenteuer NETWAYS gewagt. Ein Umzug von Wien nach Nürnberg mit der Vorliebe, österreichische Köstlichkeiten zu importieren - so mancher Kollege verzweifelt an den süchtig machenden Dragee-Keksi und der Linzer Torte. Oder schlicht am österreichischen Dialekt der gerne mit Thomas im Büro intensiviert wird ("Jo eh."). Wenn sich Michael mal nicht in der Community helfend meldet, arbeitet er am nächsten LEGO-Projekt oder geniesst...

Timelion, eine Kibana Erweiterung

timelion logoIch habe mich in der Vergangenheit mit verschiedenen Tools beschäftigt die Performancedaten bzw. Metriken speichern und darstellen können. Aktuell beschäftige ich mich näher mit Timelion aus dem Hause Elastic und das hat zwei Gründe: Zum einen wurde mir die Kibana Erweiterung auf der ElasticON letzte Woche wieder schmackhaft gemacht, nachdem ich es eigentlich schon zur Seite gelegt hatte. Zum anderen erweist sich Timelion als sehr nützlich in Verbindung mit meinem Icingabeat. Ein Beat der Daten aus Icinga 2 zur weiteren Verarbeitung entweder an Logstash oder direkt an Elasticsearch schicken kann.
Timelion, übrigens Timeline ausgesprochen, ist eine Erweiterung für das bereits bekannte Kibana Webinterface. Es ist dazu gedacht Daten aus einem Elasticsearch Cluster visuell darzustellen. Anders als die bisherigen Visualisierugsmethoden von Kibana wird bei Timelion aber nichts zusammen geklickt und gefiltert. Stattdessen müssen die eingebauten Funktionen direkt aufgerufen und mit Parametern gefüllt werden. Klingt erst mal kompliziert, nach etwas Übung geht das aber schneller als alles mit der Maus zu bedienen.
Ein Beispiel: Um die Anzahl der Dokumente in Elasticsearch zu zählen, wird die Funktion es() verwendet. Sie erwartet als Parameter eine Query. Mit es(*) werden sämtliche Dokumente gezählt, die Query dabei ist *
timelion default query
Als Query kann alles eingegeben werden was das normale Kibana Interface auch versteht, also Apache Lucene Syntax. Zum Beispiel kann ich die Anzahl der Checkresults darstellen, die mein Icinga gerade ausführt: .es(type:icingabeat.event.checkresult)timelion icingabeat checkresults
Einfach Dokumente zu zählen reicht aber oft nicht aus, insbesondere im Hinblick auf Metriken. Wichtig an dieser Stelle ist der eigentliche Wert von einem Eintrag, nicht die Anzahl der Einträge. Die es() Funktion kann mit ihrem metric Parameter genau das tun. Man muss sich lediglich entscheiden mit welcher Methode man die Daten aggregieren möchte. Auch wenn die Daten nicht in einem definierten Zeitrahmen in Elasticsearch gespeichert werden, müssen sie spätestens bei der Darstellung irgendwie zusammengefasst werden um einen gleichmäßigen Graphen anzeigen zu können. Timelion versucht den Abstand in dem Daten aggregiert werden automatisch zu ermitteln, meistens ergibt das “Sekündlich”. Ob das der richtige Intervall ist, hängt davon ab wie schnell die Daten rein fließen. Wie viele MySQL Queries Icinga 2 innerhalb der letzten Minute ausgeführt hat, lässt sich zum Beispiel folgendermaßen ermitteln:
.es(metric=avg:perfdata.idomysqlconnection_ido-mysql_queries_1min.value).label("1 min").title("MySQL Queries").color(green)timelion icingabeat mysql
Hier sieht man auch das sich mehrere Funkionen aneinander ketten lassen. Zum Beispiel zum setzen von Titel oder Farbe. Timelion bringt eine ganze Fülle an Funktionen mit die die Darstellung der Daten beeinflussen. Ich will nicht alle aufzählen, weitere Beispiele aber sind:

  • bars(): Ein Barchart anstelle einer Linie
  • movingaverage(): Berechnet den gleitenden Durchschnitt
  • min(), max() und sum(): Erklärt sich von selbst

Es können auch mehrere Linien innerhalb eines Graphen angezeigt werden, dazu wird die Funktion einfach mehrfach aufgerufen. Hier ein vergleich der Ausführungszeiten von Icinga Plugins:
.es(metric=avg:status.avg_execution_time), .es(metric=avg:status.max_execution_time), .es(metric=avg:status.min_execution_time) timelion icingabeat execution time
Insgesamt ist das nur ein kleiner Teil dessen was Timelion kann. Auch wenn die Bedienung etwas gewöhnungsbedürftig ist, so kommt man nach etwas Übung schnell rein. Die Graphen die erstellt werden können entweder als eigenständige Dashboards abgespeichert werden oder als einzelne Visualisierungen. Werden die Graphen einzeln abgespeichert können Sie zu Kibana Dashboards hinzugefügt werden. Dadurch ergibt sich eine gute Ergänzung zu den normalen Visualisierungen.

Blerim Sheqa
Blerim Sheqa
Product Manager

Blerim ist seit 2013 bei NETWAYS und seitdem schon viel in der Firma rum gekommen. Neben dem Support und diversen internen Projekten hat er auch im Team Infrastruktur tatkräftig mitgewirkt. Hin und wieder lässt er sich auch den ein oder anderen Consulting Termin nicht entgehen. Mittlerweile kümmert sich Blerim hauptsächlich im Icinga Umfeld um die technischen Partner und deren Integrationen in Verbindung mit Icinga 2.