Grafana

LogScale 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 LogScale'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.
Install the Plugin
The easiest way to install the plugin is by using the
grafana-cli
, which is
described in the official
Grafana
plugin entry.
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 thedata/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/
.On Windows it's
C:\Program Files\GrafanaLabs\grafana\
.
Restart Grafana.
Building the Plugin
If you need to build a plugin:
#Clone the humio2grafana repository
git clone git@github.com:humio/humio2grafana.git
cd humio2grafana
#Then run the following to install dependencies and build the plugin in the dist file
yarn install
yarn run grafana-toolkit plugin:dev
You can now Install the Plugin for use with Grafana.
Setting up a LogScale Data Source
Before you can populate your dashboards with LogScale data, you must register a LogScale data source to your Grafana instance by following these steps:
Log in to your Grafana instance through the browser.
Go to
Configuration --> Data Sources
.Click
.Choose the LogScale data source from the list.
Name your data source.
Input the URL of your LogScale instance.
Copy-paste your personal LogScale access token into the
LogScale Token Authentication
field.Click
Save & Test
. You'll get a "Success" message if the plugin was able to connect to your LogScale instance.
Add a New LogScale Panel to a Dashboard
To add a LogScale panel to a dashboard, simply add a new panel widget and select your new LogScale data source as the panel's data source. You can then write regular LogScale queries for the panel to populate it with data.
Widget Types
Grafana offers many different types of widgets to display data queried from LogScale. The type of widget you choose defines the data format your query is expected to return to populate it, more specifically the data format returned by a query is specified by 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 provide 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 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 |
Query Variables
The plugin supports populating Grafana variables using LogScale queries. Both aggregate and filter queries can be used to populate a variable. In addition to the query, you must provide:
The LogScale repo to query
The name of the event field in the returned events to extract the variable contents from
You must press the Execute LogScale Query button on the variables screen to query LogScale 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.
Annotations
The plugin supports annotations based on LogScale filter queries. Given the return of a filter query, each event will be turned into an annotation and its :field: @timestamp field will define where in time to place the annotation.
In addition to the query you also need to define:
The LogScale repository to query
The name of the event field in the returned events to extract the annotation text from
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.
Tips
Use a Saved Query
It is a good idea to create and maintain the queries you use in your Grafana dashboards in LogScale'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 LogScale'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 LogScale 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.
Using Filter Queries
Please note that LogScale 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 LogScale 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 LogScale with Grafana For A Comprehensive Dashboarding Experience.