Grafana

Humio has built-in support for dashboards, but if you are using Grafana for visualizing your data from different sources and would prefer to keep everything in Grafana you can use Humio’s Grafana plugin.

If you’re interested in contributing to the further development of the plugin, please look at the documentation found on the plugin’s GitHub repository.

Installing the plugin

  1. Download the latest version of the plugin from the our list of releases.
  2. Copy the downloaded dist folder to data/plugins in your Grafana install directory. Feel free to rename the folder. Also note that the default install directory varies by OS
    • Linux: /var/lib/grafana/
    • MacOS: /usr/local/var/lib/grafana/
    • Windows: C:\Program Files\GrafanaLabs\grafana\
  3. Restart your Grafana service.

Building the plugin

You may need to build the plugin yourself if a release hasn’t already been made available with the newest updates, or if you’re testing out an experimental branch of the repository.

  1. Run git clone git@github.com:humio/humio2grafana.git
  2. Run cd humio2grafana
  3. Run npm install to install dependencies
  4. Run npm run build to build the plugin and place it in the dist folder

From this point you can install the plugin for use with Grafana as explained above.

Setting up a Humio data source

Before you can populate your dashboards with Humio data, you must register a Humio data source to your Grafana instance by following these steps

  1. Log in to your Grafana instance through the browser.
  2. Go to Configuration > Data Sources.
  3. Click Add data source.
  4. Choose the Humio data source from the list.
  5. Configure the data source
    1. Set data source name, for example “MyHumioCloud”.
    2. Set Humio server address, for example https://cloud.humio.com.
    3. Set Humio access token. Please make sure not to use an ingest token, as it cannot be used to query data from your Humio instance.
  6. Click Save & Test. You’ll get a “Success” message if the plugin was able to connect to your Humio instance.

Adding a new Humio panel to a dashboard

To add a Humio panel to a dashboard, simply add a new panel widget and select your new Humio data source as the panel’s data source. You can then write regular Humio queries for the panel to populate it with data.

Widget types

Grafana offers many different types of widgets to display data queried from Humio. Depending on the type of widget you choose, your query is expected to return a certain data format to populate it. The data format returned by a query depends on the last function in its pipeline. For instance, given the query: groupby(...) | count(), the data format returned is decided by count(). In this example, count() returns a single data point.

In the following, we give some examples that work well with the different widget types. This is not an exhaustive list, but is meant as a starting point.

Graph

The graph widget is suited for showing time-series data. Use the timechart() function to return data formatted for this widget.

Table

The table widget is suited for showing tabular data. Use the table() function to return data formatted for this widget.

Stat/Gauge/Bar Gauge

These widgets are suited for showing a single metric across different groups of data. Use the groupby() function to return data formatted for this widget.

Singlestat

The Singlestat widget is suited for showing a single number. You can populate it with functions that return a single datapoint such as count().

Worldmap

The Worldmap widget is very useful for showing locational data, but it is not included in the standard Grafana installation. You can install it as a plugin from its plugin page.

To populate your widget use the worlmap() function. As an example, if you want to decide location by ip use worldmap(ip={your ip field here}). Given this query, the widget must be configured in the following manner to be shown correctly

Field Value
Location Data Table
Aggregation Total
Table Query Format geohash
Location Name Field geohash
Metric Field magnitude
Geohash Field geohash

Tips

Use a saved query

It is a good idea to create and maintain the queries you use in your Grafana dashboards in Humio’s own UI Then create Saved Queries for them and call them by name in Grafana instead of writing the entire query in Grafana. This way you have all your queries collected in one place.

Example

Create a query in Humio’s UI and give it the name “MyQuery”

#source=console.log loglevel=ERROR | timechart()

Then from Grafana call it by name

$MyQuery()

Use live queries

A live Humio query can be used to continuously update a Grafana dashboard over time. To activate live queries on your dashboard, make sure that its time range is set relative to the present point in time and that automatic refresh of the dashboard has been activated.

As an example, set the time range to be last 10 minutes and the refresh rate to be 1m.

Configuring the bar gauge

Grafana’s bar gauge widget is still in beta, so it may not always behave as you expect. Here are a few tips to help configure the widget.

Ensuring Visibility of Gauge Names

The default behavior of the widget is to only show the names of gauges when there is more than one gauge on the chart. You may however find that you want to have your gauges named, even there is only a single one.

To do this go to the Visualization tab of the widget and enter ${__series.name} into the Title field.

Ensuring proportionality between gauges

Grafana may “zoom in” on gauges in the widget, meaning that the smallest gauge becomes a lot shorter than the rest of the gauges. If you want to “zoom out” this view, and have some more accurate proportions, try and set the min field to 0 under the Visualization tab.

For more information