Graphs with RRD4J

Pierre Kil edited this page Oct 4, 2016 · 8 revisions
Clone this wiki locally

RRD4J is a high performance data logging and graphing system for time series data, implementing RRDTool's functionality in Java. It follows much of the same logic and uses the same data sources, archive types and definitions as RRDTool does.

OpenRemote is now integrating this logging and graphing system and your sensors information can now be stored and graphically displayed on your panels.

A RRD4J Tutorial can be found here

Only Sensor data can be stored in the RRD4J Database.

OpenRemote is using the WebElements to display the graphics. Make sure your device can display the WebElement

This tutorial is splitted in 3 steps:

  1. Creating and configuring the RRD4J Database
  2. Displaying graphics
  3. Advanced feature: dynamically changing the graphic timeframe

Creating and configuring the RRD4J Database

In order to display graph, you need to have some data to be displayed. RRD4J is storing the data on Round Robin Database (RRD) files. This RRD file is automatically created by OpenRemote following your RRD4J configuration.

The configuration file is located within your controller in the folder "rrd/rrd4j-config.xml".

This configuration file is composed of two main section:

  • The data definition
  • The graph definition

Here is a example of such a config file with 2 sensors:

<?xml version="1.0" encoding="UTF-8"?>
<rrd4j xmlns="http://www.openremote.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.openremote.org http://www.openremote.org/schemas/rrd4j.xsd">

  <rrdDB fileName="test.rrd" step="60">
    <datasource name="Temp SDB" type="GAUGE" heartbeat="120" />
    <datasource name="Temp CH7" type="GAUGE" heartbeat="120" />
    <archive function="AVERAGE" xff="0.5" steps="1" rows="300" />
    <archive function="AVERAGE" xff="0.5" steps="10" rows="144" />
    <archive function="AVERAGE" xff="0.5" steps="15" rows="672" />
    <archive function="AVERAGE" xff="0.5" steps="60" rows="744" />
    <archive function="AVERAGE" xff="0.5" steps="120" rows="4380" />
  </rrdDB>

  <rrd_graph_def name="graph2">
     <options>
         <vertical_label>Temp (°c)</vertical_label>
         <title>YPH RRD4J Example</title>
     </options>
     <datasources>
         <def>
             <name>Temp_SDB</name>
             <rrd>test.rrd</rrd>
             <source>Temp SDB</source>
             <cf>AVERAGE</cf>
         </def>
         <def>
             <name>Temp_CH7</name>
             <rrd>test.rrd</rrd>
             <source>Temp CH7</source>
             <cf>AVERAGE</cf>
         </def>
     </datasources>
     <graph>
         <line>
             <datasource>Temp_SDB</datasource>
             <color>#FF0000</color>
             <legend>Temp Salle de Bain\r</legend>
             <width>2</width>
         </line>
         <line>
             <datasource>Temp_CH7</datasource>
             <color>#0000FF</color>
             <legend>Chambre Astrid\r</legend>
             <width>2</width>
         </line>
         <comment>This chart displays OR sensor values.</comment>
     </graph>
 </rrd_graph_def> 

</rrd4j>

Here is the resulting graph that RRD4J will generate :

RRD4J Graph

The data Definition

This section of the RRD4J configuration file describes which data to store in the RRD file and how to store them.

The RRD file creation parameters:

  • 'filename': the name of the RRD file that will be created by OpenRemote within your controller in the folder "rrd"
  • 'step' : The RRD Time step in seconds

The Data source parameters:

  • 'name' : This value must be the exact name of the OpenRemote sensor you'd like to log. The name is limited to 20 characters!
  • 'type': This is the type of the datasource values. ABSOLUTE Is for counters which get reset upon reading. COUNTER Is for continuous incrementing counters like the ifInOctets counter in a router. DERIVE Will store the derivative of the line going from the last to the current value of the data source. GAUGE Is for things like temperatures or number of people in a room or the value of a RedHat share.
  • 'heartbeat' : This is usually twice the value of the RRDDB step.

The archive parameters :

ToDO ....(see RRDTool original author Tobias Oetiker's documentation)

NOTE: If you change/add data sources, you must stop the controller and remove the RRD files (test.rrd)

The graph definition

This section of the RRD4J configuration file describes what data will be part of the graph and this graph will look like.

    <rrd_graph_def name="graph2">
     <options>
         <vertical_label>Temp (°c)</vertical_label>
         <title>YPH RRD4J Example</title>
     </options>
     <datasources>
         <def>
             <name>Temp_SDB</name>
             <rrd>test.rrd</rrd>
             <source>Temp SDB</source>
             <cf>AVERAGE</cf>
         </def>
         ...
     </datasources>
     <graph>
         <line>
             <datasource>Temp_SDB</datasource>
             <color>#FF0000</color>
             <legend>Temp Salle de Bain\r</legend>
             <width>2</width>
         </line>
         ...
         <comment>This chart displays OR sensor values.</comment>
     </graph>

The RRD graph definitions parameters are:

  • 'name': The name of the graph. This is the graph name that you're going to call from your OpenRemote panel

The graph definition is compound of 3 main parts:

  • datasources
  • graph
  • options

graph definition - options

The "options" section lets you defined some optional information on your graph like axis labels, title, units, color, grid, log scale, fonts, ...

graph definition - datasources

This section create the link between the datesource you've stored in your RRD4J database and the ones to display in the graph. There are several ways to create a graph datasource definition. You could create a datasource by evaluating a mathematical expression, ...

In our tutorial, for each datasource you'd like to display, its definition parameters are:

  • 'name': the id of your graph datasource definition within this graph definition. It can be different from the name of that datasource stored into your RRD DB or from your OpenRemote Sensor
  • 'rrd': from which RRD Database the data source come from?
  • 'source': one of the datasource you've created in your RRD Database
  • 'cf': one of the available consolidation function:
  • AVERAGE The average of the data points is stored.
  • FIRST The fist data point is used.
  • LAST The last data point is used.
  • MAX The largest of the data points is stored.
  • MIN The smallest of the data points is stored.
  • TOTAL The total of the data points is stored.

graph definition - graph

What needs to be part of main graph area like lines, areas, stack, hrule, vrule, ... a sample definition of those is provided here In this tutorial, we're displaying the datasource using a line representation. In that case, the parameters are:

  • 'datasource': the graph datasource definition to be used
  • 'width' of the line
  • 'color' of the line (see here for color map)
  • 'legend' of the line

Displaying graphics

The graph could be seen at the URL generated by OpenRemote:

http://IP:Port/controller/graph?name=graph2&start=20140131-00-01&end=21040131-00-23&width=600&height=400

IP= is the IP address or DNS name of your controller followed by the port number. For testing you can quickly see your results by entering the following shorter URL in your browser

http://IP:Port/controller/graph?name=graph2&start=20140131-13-01

This shows your collected data since 2014-01-31 13:01h.

In order to view it in the OpenRemote panel, we're going to use the Web View element of OpenRemote. There are two ways to use the Web View element:

  • either you enter directly the URL as parameter or
  • you link the Web View element to a sensor and the sensor will provide to URL to the Web View element. We're going to create such a sensor for the RRD4J Graph. The benefit of this approach is that web view will be refreshed if your sensor changes.

Creating the RRD4J Commands

Optional: Create a new device to group all RRD4j commands

Create a new command to call the controller in order to get the URL of RRD4J graph. Named it i.e.'GetRRDGraphURL' and select the 'RRD4J Graph URL' protocol. Fill-in the following parameters:

  • graph name as defined in your RRD4J configuration file
  • start / end date with format yyyymmdd-hh-mm
  • width / height of the graph to display
  • command: 'getURL'

RRD4J Edit Command

Now that the command exists, defined a sensor linked to that command

RRD4J Edit Sensor

That's it for the building modeler side, now go the panel design part of the online designer.

Designing the panel

To display the graph, we're going to use Web View element from the widget list. Note however if you are using the Android Console and this does not work, please try using an Image connected to the RRD4J sensor instead.

Select it and drop it into your panel. You can set some properties like width, height, ... the URL can be empty but don't forget to link the Web View element to the RRD4J sensor.

RRD4J Webview Properties

That's it! you can now display your graph within your prefered panel.

Advanced feature: dynamically changing the graphic timeframe

One nice feature of the RRD4J implementation within Openremote is that you can dynamically change the time period of the graph your displaying. you can increase/decrease the start/end date of the graph and it will be refreshed in your web view element.

To do so, the RRD4J protocol supports several commands:

  • startPlus1Year: this command will increase the start date by 1 year
  • startPlus1Month: this command will increase the start date by 1 month
  • startPlus1Day: this command will increase the start date by 1 day
  • startPlus1Hour: this command will increase the start date by 1 hour

  • startMinus1Year: this command will decrease the start date by 1 year

  • startMinus1Month: this command will decrease the start date by 1 month
  • startMinus1Day: this command will decrease the start date by 1 day
  • startMinus1Hour: this command will decrease the start date by 1 hour

You've got also the same 8 command for the end date, so:

  • endPlus1Year: this command will increase the end date by 1 year
  • endPlus1Month: this command will increase the end date by 1 month
  • endPlus1Day: this command will increase the end date by 1 day
  • endPlus1Hour: this command will increase the end date by 1 hour

  • endMinus1Year: this command will decrease the end date by 1 year

  • endMinus1Month: this command will decrease the end date by 1 month
  • endMinus1Day: this command will decrease the end date by 1 day
  • endMinus1Hour: this command will decrease the end date by 1 hour

The following commands can be used to reset the time axis:

Commands below are only available in version Pro 1.2.0 and above
  • resetStart: Reset start time
  • resetEnd: Reset end time
  • resetStartEnd: - Reset both start and end times

Usage Example

Create a new Command and setup the properties

  • Name: the name of the OpenRemote command within the Online Designed protocol
  • graph name: need to be the one defined in your RRD4J configuration file
  • command: one of the RRD4J command to change the start-end date

In example for the "StartPlus1Month" command:

Edit Command

You can of course create a command for each of those 16 RRD4J commands

Now, let's have a look at one basic way to use them on the design side. The target of this tutorial is to achieve the following design result:

Panel Example

First of all, if you'd like to control that the command are working, you could add a new label on your panel and link it to RRD4J sensor. Like this your RRD4J URL will be displayed and refreshed each time it's changing.

Label properties

Now you can create a button to trigger one RRD4J command. Drop a button on your panel, setup some properties, width, heigth, give it a label and link the button command property to one of the created RRD4J command by selecting it from the selection tree.

Command Selection tree

You can repeat that command button creation for each of the RRD4J command.

Here is a screenshot of the achieve results on iPAD:

Example Panel

A public template has been created with that panel

name: RRD4J Graph
keywords: RRD4J Graph

Useful Links