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 to follow the steps in the Grafana documentation.

Configure a LogScale Data Source in Grafana

For general information about Grafana data sources please visit this page . The very first step before you can populate your dashboards with LogScale data is to register a LogScale data source to your Grafana instance by following these steps:

  1. Log in to your Grafana instance.

  2. Go to Administration→ Data Sources.

  3. Click Add new data source and select the LogScale data source from the data source list.

  4. Name your data source.

  5. Set the URL of your LogScale instance, for example,

  6. Copy-paste your personal LogScale access token (PAT) into Token field under the LogScale Token Authentication section.


    To generate a personal access token, log into LogScale and navigate to User Menu & Manage Account & Personal API Token. Then, set or reset your token. Copy and paste the token into the token field.

  7. Optionally, set a default LogScale repository to use for your queries.

  8. Click Save & Test. You'll get a "Data Source is working" message if the plugin was able to connect to your LogScale instance.

Query the LogScale Data Source

You can write regular LogScale Query Language (LQL) queries using Query Language Syntax to populate Grafana dashboards with the data. 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.

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:

| 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.

Logs Panel

The logs panel shows the log lines coming from the LogScale which represents the @rawstring.


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.

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.


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

Explore View

The Explore view allows you to run LogScale queries and visualize the results as logs or charts.

  • For more information about Explore, refer to Explore.

  • For more information about Logs in Explore, refer to Explore logs.

Query Variables

The plugin supports populating Grafana variables using LogScale queries. Both aggregate and filter queries can be used to populate a variable.

You must click Run Query 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.

After creating a variable, you can use it in your LogScale queries using Variable syntax. For more information about variables, refer to Templates and variables.


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 and optionally:

  • Time range to specify whether the list should be limited

  • The event field in the returned events to extract the annotation title

  • The event field in the returned events to extract the annotation text

  • Tags to filter the annotations


    Grafana variables may be used in annotation queries.


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:


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.

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 if there is only a single one.

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

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.