We use cookies to ensure that we give you the best experience on our website.  Visit our Privacy Policy to learn more. If you continue to use this site, we will assume that you are okay with it.

Your choices regarding cookies on this site.
Your preferences have been updated.
In order for the changes to take effect completely please clear your browser cookies and cache. Then reload the page.

Integrating Checkmk in Grafana

This article is just a draft and not yet finished!

1. Introduction

Checkmk has an integrating graphing system with a lot features for visualize and store metrics. However, it might still be helpful to use Grafana as an external graphing system. For example, if you are already using Grafana and have other data sources connected to it and want to have one unified dashboard.

Beginning with version 1.5.0p16, in the  Checkmk Enterprise Editions it is possible to directly address Checkmk as a data source in Grafana, and to display individual metrics – or even entire graphs as predefined by Checkmk – in Grafana. In addition you can create your own graphs dynamically using regular expressions to specify a set of hosts and services that should take specific metrics in the graph into account.

How to get and to display your Checkmk metrics in Grafana is explained fundamentally in this article. For detailed instructions on how to use and configure Grafana, see the Documentation at Grafana Labs.

Since the plug-in for Grafana is developed in parallel to Checkmk, it is not included with Checkmk. You can however keep up-to-date with the latest development status through the Archive on GitHub. The Announcements mailing list will also inform you if there is a new version of the plug-in.

Listing the data source directly in the official Grafana Data Sources is still in progress. Once the plug-in has been officially incorporated you will be able to install it directly from Grafana's interface.

2. Setting-up the plug-in in Grafana

2.1. Installing the plug-ins

To use the plug-in, there are two ways to insert it into Grafana:

  • You download the zip file from the GitHub project, and manually paste the content into the Grafana plug-in directory.
  • You clone the GitHub project directly into the plug-in directory.

Installation from the Zip-file

To install the plug-in, simply download the zip file with the latest version, and copy it – for example, with scp – to the Grafana server:

Bild der GitHub-Releases

Alternatively, you can also load the file directly from the command line. Note that you need to know the correct version for this. With the option -O in the following comannd, the name of the file to be saved locally is set manually. Otherwise it would be 1.1.0.zip:

root@linux# wget -O grafana-checkmk-datasource-1.1.0.zip https://github.com/tribe29/grafana-checkmk-datasource/archive/1.1.0.zip

The content is then extracted into the Grafana plug-in directory. This is usually the file path /var/lib/grafana/plugins/:

root@linux# unzip grafana-checkmk-datasource-1.1.0.zip && mv grafana-checkmk-datasource-1.1.0 /var/lib/grafana/plugins/

Finally you can activate and set up the plug-in in the Grafana interface.

Installation as a Git archive

The variant described above has the fewest requirements, and is easy to implement even for less-experienced users. But if you get the plug-in directly from the Git archive, the are several advantages:

  • Upgrading to a new version can be quickly performed with two commands
  • You have the ability to directly access the latest version from the archive, without having to wait for an official release.

To use the plug-in with the help of a copy of the archive, you absolutely need the git program. The procedure is then quite simple – simply clone the archive into the Grafana plug-in directory:

RP(/var/lib/grafana/plugins/):git clone https://github.com/tribe29/grafana-checkmk-datasource.git
Cloning into 'grafana-checkmk-datasource'...
remote: Enumerating objects: 541, done.
remote: Total 541 (delta 0), reused 0 (delta 0), pack-reused 541
Receiving objects: 100% (541/541), 291.55 KiB | 0 bytes/s, done.
Resolving deltas: 100% (374/374), done.
Checking connectivity... done.

Afterwards the plug-in is available in the Grafana GUI, and from there can be activated and set up.

2.2. Activating and setting-up the plug-in

After the necessary files have been installed you can activate the plug-in in Grafana. Go to the configuration and select the Data Sources tabs. Here you can add a new data source using the Add data sources button:

Bild der Übersicht

The entry for Checkmk can be found under the category Others:

Bild der verfügbaren Plugins

The configuration mask for the data source is quite simple. Enter the URL for your instance and an automation user here. Important – In a distributed setup with multiple instances, here you specify the URL for the master instance:

Bild von Plugin-Config

If you want to connect more than one Checkmk instance, from CheckMK you can optionally add a unique name to each connection.

After you have saved the connection with the Save & Test button, it will be available as a data source in Grafana and you can configure your first graphs.

3. Creating the first graph

3.1. Creating a blank dashboard

Dashboards are generated in Grafana using the ‘plus’ icon on the right side. With a click on Dashboard you can create something like this:

Bild von + ➳ Create ➳ Dashboard

3.2. Displaying a predefined graph from Checkmk

Checkmk automatically merges metrics into a graph to quickly compare content-related metrics. You can display the metrics from such a ready-made graph directly in Grafana. In an existing – or just created – dashboard, create a new Panel. Here you first select Add Query:

Bild vom neuen Panel

The Query should be Check_MK. You can then prefilter the query to a Checkmk instance (Site). Then select the desired Host, Service and Graph:

Bild von der predefined-Mode-Konfig

The result is displayed immediately. As soon as you click on the Save icon, you will be prompted to specify a title for the Panel. Then you will be redirected directly to the dashboard:

Bild vom Dashboard

3.3. Displaying a single metric from a host

Of course it is also possible to display individual metrics for a host. The procedure is very similar to that with predefined graphs – you just change the Mode to single metric, and instead of choosing a predefined graph, select the Metric for a service:

Bild von der single-metric-Mode-Konfig

Again, save the Panel and see the result in the dashboard:

Bild vom Dashboard

4. Creating complex graphs

Especially in a dynamic cluster, you often want to be able to track the entire history of a metric across all participating hosts without having to adjust a graph each time a new node is added or dropped. As of version 1.6.0p2 you also have the option to create graphs dynamically using regular expressions. The prerequisite for this is that the plug-in is in version 1.1.0.

For this purpose change Mode to combined graph in a new Panel. The general setting options remain unchanged, but you can now merge metrics from one or more hosts and services. You have access to all of the regular expressions which you are already familiar with in Checkmk.

Bild von der combined-metric-Mode-Konfig

In addition to the advanced filter options, with Aggregation you can specify the representation of the metrics in the graph, and with Graph, which graph should be used as a reference. Note that metrics for a host/service will only be displayed if the host/service also has this selected graph. The example graph looks like this:

Bild vom Dashboard

5. Files and directories

File path Description
/var/lib/grafana/plugins/ Grafana checks here for (new) plug-ins. Each plug-in gets its own subdirectory. Save the Checkmk plug-in here.