Jasper Report RRD Datasource Specification

From OpenNMS
Jump to navigation Jump to search

RRD Jasper Report Specification

Jasper reports can now be created from JRobin files. In this specification we'll cover how to create and run a jasper report using jrb files as the source for our dataset.

Overview

In order to provide access to data in JRobin RRD files, we have provided a QueryExecutor that allows you to create 'queries' into these RRD files using a syntax similar to the syntax used by the rrdtool xport command. Details of the rrdtool xport command can be found here or via the rrdxport man page for rrdtool. The --start, --end, --step, and --maxRows options and the DEF, CDEF and XPORT arguments will be supported.

These queries will be placed in a <queryString> block in the Jasper Report template (.jrxml file) with the language attribute set to 'jrobin' and will define a JRDatasource that has a Timestamp column, and a column for each XPORT argument whose name will match the name provided in the last portion of the XPORT argument. The type of the Timestamp column is 'java.util.Date' and the remaining columns are of type 'java.lang.Double'. These columns can be mapped to fields in the report using <field> tags. When doing the mapping the columns are mapped using first the fieldDescription and then the fieldName to determine the mapped column in a case insensitive manner.

Acceptance Criteria

The following steps will outline how to setup a jasper report, that uses a jrb as a datasource, in OpenNMS that will email you a daily report. The following steps are not a complete example but a rough outline of how to configure your own Jasper report to pull data from a jrb file as a datasource.

Step 1.

First we need data, and for this example we are using RRD data to build a report. We start off with two jrd files with a couple datasoures and a days worth of data.

One named mo_calls.jrb and mt_calls.jrb both of which have four RRD datasources. (These files are available at File:Mo calls.jrb and File:Mt calls.jrb

Once you have downloaded the two rrd files you will want to put the files in the $OPENNMS_HOME/share/rrd/samples/, if the samples directory doesn't exist you will need to create it.

The following are the datasources and archive setup for the jrobin rrd files.

Datasources for mo_calls.jrb

DS:mo_call_attempts:COUNTER:600:0:U
DS:mo_call_completes:COUNTER:600:0:U
DS:mo_mins_carried:COUNTER:600:0:U
DS:mo_calls_active:GAUGE:600:0:U
RRA:AVERAGE:0.5:1:288

Datasources for mt_calls.jrb

DS:mt_call_attempts:COUNTER:600:0:U
DS:mt_call_completes:COUNTER:600:0:U
DS:mt_mins_carried:COUNTER:600:0:U
DS:mt_calls_active:GAUGE:600:0:U
RRA:AVERAGE:0.5:1:288

Step 2.

Next we need a Jasper report template, for this example we have created a template that generates two graphs based on the RRD data over the course of 24 hours.

The first graph is a bar chart that graphs the MO_CALL_ATTEMPS_PER_HOUR and the MT_CALL_ATTEMPTS_PER_HOUR in a day. The second is a time series graph that charts the successRate of MT_CALLS and MO_CALLS in the 24 hours.

You can find the template here File:AllChartsReport.jrxml (Caution: I've just -2013/03/20- uploaded a new version of this file. If it doesn't work, you might also try the previous versions).

Once you have downloaded the jrxml report template file you will want to add this file to the $OPENNMS_HOME/etc/report-templates/ directory. This is the directory where all report templates are stored.

Step 3.

The next step is to configure reportd so that it knows about the report template you've created and setup the report schedule. The below configuration can be copied into your reportd-configuration.xml file. As you see it includes the parameters configuration for the rrd directory, start and end dates.


	<report report-name="sample-graph-report" report-template="AllChartsReport.jrxml" report-engine="jdbc">
		<cron-schedule>0 */5 * * * ? *</cron-schedule> <!-- every 5 minutes for testing -->
                <parameter name="rrdDir" value="PATH_TO_OPENNMS_HOME/share/rrd/samples"/>
                <parameter name="startDate" value="1287633600"/>
                <parameter name="endDate" value="1287720000"/>
                <recipient>me@host.com</recipient>
	</report>

You will want to change the email address to an actual email address.

Step 4.

Currently there isn't a nice webapp gui. The report will be run based on the cron schedule.


Step 5.

Your report should be email to you. Open the file and verify that you see two charts, a bar chart and a time series chart.

Like the ones below.

Bar Chart.jpeg Time Series Chart.jpg

Viewing and validating the report

Step 6.

Verify that the report sent to you and the above images are correct.


iReport

If you use iReport to build your Jasper report templates there is an easy way of adding this Jasper extension and fields provider to iReport to use within your template. You will need to add the 'jasper-extensions', 'jrobin-provider', 'jrobin', and 'org.opennms.core.lib' JARs to the classpath and set the query executer and fields provider.

Adding the JARs to the classpath

Under Preferences->Classpath (on Windows this is in Tools->Options->Classpath) click Add Jar and navigate to your ${OPENNMS_HOME}/lib directory and select the jasper-extensions-{version num}.jar, jrobin-provider-{version num}.jar, jrobin-{version num}.jar, and org.opennms.core.lib-{version num}.jar.

The fields provider (jrobin-provider-{version num}.jar) is distributed separately from the rest of OpenNMS and may be downloaded from SourceForge. In my case I added jrobin-provider-1.0.jar.

Adding the Query Executer and Fields Provider

Under Preferences->Query Executer click 'Add', for language type 'jrobin' and for Factory Class type 'org.opennms.netmgt.jasper.jrobin.JRobinQueryExecutorFactory'. For the Fields Provider class, type 'org.opennms.netmgt.jasper.jrobin.JRobinFieldsProvider'.


Using Store By Group

If you are using storeByGroup you will need to set the the following report property in iReport's preferences.

org.opennms.rrd.storeByGroup=<true | false>

Depending on if you are using storeByGroup or not.

1.9 RrdTool Usage

As of this update you have a choice of either using the JRobinDataSource or the RrdToolDataSource when dealing with rrd data based Jasper reports. Simple change the query language from "jrobin" to "rrdtool". And add the following report property to iReport in the preferences.

org.opennms.rrd.fileExtension=< .jrb | .rrd>

The default value is .jrb.