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.
The easiest way to install the plugin is by using the grafana-cli
, which is described in the official Grafana plugin entry.
If you want to install the plugin without using the grafana-cli
, you will need to download the latest version of the plugin from our list of releases. After you download it, unzip the file, humio2grafana.zip
. This generates the humio2grafana
folder, which you must place into the data/plugins
directory in your Grafana install directory. If you’re using Linux, the default install directory is /var/lib/grafana/
. On MacOS it’s /usr/local/var/lib/grafana/
and on Windows it’s C:\Program Files\GrafanaLabs\grafana\
.
After unziping and putting the Humio plugin where it needs to go, restart Grafana.
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.
git clone git@github.com:humio/humio2grafana.git
cd humio2grafana
yarn install
to install dependenciesyarn run grafana-toolkit plugin:dev
to build the plugin and place it in the dist
folderFrom this point you can install the plugin for use with Grafana as explained above.
Before you can populate your dashboards with Humio data, you must register a Humio data source to your Grafana instance by following these steps:
Url
of your Humio instanceAuth
.Humio Token Authentication
.The type of authentication you choose for your data source depends on your use case. If you authenticate via token, which is tied to a specific Humio user, all Grafana users will authenticate against Humio as the same Humio user. Thus it is a good option, if you do not need to differentiate between users within Grafana with regards to Humio.
However if you do need to differentiate your users, it is advisable to use authentication without the use of a Humio token, such as OAuth forwarding. This will allow Grafana users to interact with the Humio data source as their own Humio user.
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.
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.
The graph widget is suited for showing time-series data. Use the timechart()
function to return data formatted for this widget.
The table widget is suited for showing tabular data. Use the table()
function to return data formatted for this widget.
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.
The Singlestat widget is suited for showing a single number. You can populate it with functions that return a single datapoint such as count()
.
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 worldmap()
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 |
The plugin supports populating Grafana variables using Humio queries. Both aggregate and filter queries can be used to populate a variable. In addition to the query, you must provide:
You must press the Execute Humio Query
button on the variables screen to query Humio for variable values and get a set of variable values to appear on the bottom of the screen.
We support both the All
and Multi-Value
feature for query variables. When a variable evaulates to more than one value in a query, it will interpolated to the format /^val1|val2...|valN$/
, so you need to keep account of that in your queries.
The plugin supports annotations based on Humio filter queries. Given the return of a filter query, each event will be turned into an annotation and its @timestamp
field will define where in time to place the annotation.
In addition to the query you also need to define:
Annotations are applied dashboard-wide, as Grafana doesn’t yet support the option of doing Annotations for individual panels.
Note that Grafana variables may be used in annotation queries.
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.
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()
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
.
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.
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.
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.
Please note that Humio filter queries can be used with variables and annotations. The standard result size of filter queries will always be 200 events. If you need more events from a query, append | tail(x)
to your query, where x
is the number of returned events. This default limit is in place because it is very easy for even simple queries on medium-sized Humio repos to have results that are several GB in size. Such a sizable result is usually not helpful and is likely to crash the Grafana frontend in your browser. Therefore, we leave the return size up to the user, and we urge you to try to be as specific with your queries as possible.
For more information, see Integrating Humio with Grafana For A Comprehensive Dashboarding Experience.