How to visualize device parameters, account statistics and logs in Grafana?

A dedicated plugin enables the visualization of your flespi items parameters in Grafana.

Essentials

Grafana is an open-source application for interactive data visualization, offering various charts, graphs, and visualization tools for data regardless of the location it's stored.

Data is channeled into Grafana through supported data sources. To enable visualization of your flespi data in Grafana, we've developed the ‘flespi-parameters-datasource’ open-source plugin. You can download and install it on your Grafana server, configure access to your flespi account as a data source, and create diverse dashboards to visualize your flespi data.

How to install plugin and configure data source

To install the plugin on your Grafana server, follow the instructions provided in the plugin's README file.

Once the plugin is installed, it will appear in the list of available plugins within the Plugins catalog at Administration > Plugins. To find the plugin easily, type 'flespi':

grafana flespi parameters datasource

Select the Flespi Parameters Datasource plugin and click the 'Add new data source' button to create the flespi data source:

grafana add new data source

The Settings window of the data source will open. Here, you need to configure the Flespi Token that the data source will use to access your flespi data.

Paste the token into the corresponding field and click the 'Save & Test' button to verify access:

grafana flespi token

If the data source is configured correctly, a "Success!.." banner will display, showing what flespi instances are available for the given token:

grafana flespi devices

How to build a simple dashboard

Once the data source is configured, you can build a dashboard. Let's start with a simple one displaying a graph of a specific parameter from a flespi device.

Click the 'Build a dashboard' button (located in the top right corner), then 'Add visualization,' and select Flespi Parameters Datasource as the data source for the new dashboard:

grafana flespi datasource

The Query Editor window of the dashboard will open.

Choose the device and parameter to build a graph and save the dashboard:

grafana flespi device connected

In my example, I selected a flespi device representing my personal Teltonika tracker, used during my bike rides to work and back. I chose the 'position.speed' parameter to display on the graph. As a result, the dashboard displays the speed during my bike rides (revealing three traffic lights on my route from the office to home):

grafana flespi graph

How to build an interactive dashboard

As soon as the ‘flespi-parameters-datasource’ plugin supports dashboard variables, you can build more complex and flexible dashboards that will allow you to display graphs of different parameters for different devices.

To illustrate this we will build a dashboard with template variables, that allows you to select a device and/or parameter in corresponding drop-downs, and dynamically rebuild the graph once the selected options have changed.

First, create dashboard variables. Go to dashboard settings (gear icon at the top of the page) > Variables and click the 'Add variable' button.

Specify variable type as Query, variable name as device, and query as devices.*. Click 'Run query'. In the 'Preview of values' section, you'll see the devices returned for this query (all devices available for the configured flespi token):

grafana flespi query

Click 'Apply' to save the device variable. Then, click 'New variable' to create another query variable for parameters.

For the second variable, specify the variable type as Query, name as param, and the query as devices.${device}.parameters.*. Click 'Apply,' and you'll see the list of newly created variables resembling this:

grafana flespi variables

Double-check that the names (those in the Variable column) and queries (in the Definition column) of your variables correspond to the screenshot above. If everything is configured correctly, the first variable allows the selection of the device for visualization, while the second variable allows the selection of a parameter of the chosen device to be displayed on the graph.

Click 'Save dashboard' in the top right corner to save the dashboard with the newly added variables. Return to the dashboard, and notice the Device and Parameter drop-down menus in the top left corner:

grafana flespi drop-down

The next step is to create a visualization panel displaying a graph for the selected device and parameter. This graph will dynamically update when the user selects another device and/or parameter.

Click the 'Add' button, then select Visualization. In the query editor enable switch 'Use dashboard variable' for both Devices and Parameters sections, and type '$device' into the Devices input field and '$param' into the Parameters field:

grafana flespi chart

Note that the queries specified ('$device' and '$param') must match the names of the variables created initially. The panel will display the graph based on the device and parameter chosen from the drop-down menus (or, in the other words, come from data source template variables).

Save the dashboard and go to the dashboard itself. Now, the dashboard contains two panels. The lower panel displays my bike speed (built in the previous step), while the upper panel exhibits the graph for the device and parameter selected in the drop-down menus. Implement it yourself and observe how the graph dynamically rebuilds each time you choose another device and/or parameter:

grafana flespi dynamic chart

For convenience, I've exported a dashboard containing a dynamic timeseries panel as described above. You can download, import it into your Grafana, and further customize it according to your requirements.

How to display multiple devices' charts on one panel

To track my bike tours to office and back, I use either personal tracker, or my smartphone with installed tracker app. To see the graph of my speed sourced from different flespi devices on one panel, I've just selected the two devices in the query editor's Devices field:

grafana flespi multiple devices chart

As a result, panel displays speed charts for both my trackers together. Panel's legend shows the device which this or that graph corresponds to.

How to visualize flespi account's statistics

In version 1.1.0 of  ‘flespi-parameters-datasource’  plugin we added a possibility to visualize statistics of flespi account and subaccounts. 

To demonstrate the idea, I've configured a panel with a graph of api_traffic and tokens_rest_traffic parameters for my account and subaccount:

grafana flespi multiple devices chart

To build a panel for displaying flespi statistics, you should first switch to the Query Type 'Statistics' in query editor, and then select account and/or subaccounts and parameters to be visualized.

Interactive statistics dashboards are also supported. To build one you need to create dashboard variables. This is pretty much the same, as we did for the flespi devices in the one of the previous sections, just use the following queries instead:

NameQueryDescription
accountaccounts.*fetch account and subaccounts available for given token
parameteraccounts.${account}.statistics.*fetch statistics parameters for the selected account and/or subaccounts

How to visualize logs of flespi devices and streams

The plugin is also capable to visualize numeric data from logs of flespi devices and streams.

The first example demonstrates configuration of the panel, that draws device's messages heatmap. The panel displayed 'msgs' field from the logs of the selected device - the quantity of messages received through the connection. The log entry is generated at the moment when the TCP connection is closed, therefore bars on the heatmap indicate the moments of connection closure, and the color of the bars indicate how many messages was received through the connection (the lighter - the more), thus showing the intensity of data flow.

grafana flespi multiple devices chart

The seconds example demonstrates visualization of 'ack_latency' field from the logs of a stream. Large values of the 'ack_latency' indicate that the target server is unable to process the messages from the stream in time. Such a kind of visualization may help you to detect issues with your server:

grafana flespi multiple devices chart

Interactive dashboards are supported for both devices' and streams' logs visualization. To be able to use dashboard variables for devices, streams or logs parameters, enable corresponding 'Use dashboard variable' switch and specify the name of the variable to be used in query (as on the screenshot above). 

To create dashboard variables for device and stream, use the following queries:

NameQueryDescription
devicedevices.*fetch all flespi devices available for given token
streamstreams.*fetch all flespi streams available for given token

To create a dashboard variable for logs parameters, select variable type 'Custom' and specify a comma-separated list of possible options:

grafana flespi multiple devices chart

Change log

Subscribe to the flespi-parameters-datasource plugin change log to stay in sync with any updates.


  ⚠️  Backward compatibility note

The section below is applicable for those who have dashboards configured for the plugin's version 1.0.0. If not, you may simply stop reading here.

Version 1.1.0 of the plugin uses a new query model, that differ from that was used in the previous version. 

A special backward compatibility mechanism is included in the new plugin's version, so that the dashboards that are configured for the previous version of the plugin, continue working in the version 1.1.0 as well. 

However, it's recommended to re-save the panels under the new version of the plugin. This will ensure that the panels will keep working when the mechanism will be removed. To do this just open the panel for editing and then his 'Save' button to save the panel with updated query model:

 Step 1

grafana flespi multiple devices chart

Step 2

grafana flespi multiple devices chart


See also
Using Tachograph functionality
A comprehensive guide on the key concepts and principles of the flespi analytics engine.