Reporting on information from the OpenNMS HORIZON monitoring system is important for strategical or operational decisions. Database Reports give access to the embedded JasperReports engine and allows to create and customize report templates. These reports can be executed on demand or on a pre-defined schedule within OpenNMS HORIZON.

Originally Database Reports were introduced to create reports working on data stored in the OpenNMS HORIZON database only. This is no longer mandatory, also performance data can be used. Theoretically the reports do not necessarily need to be OpenNMS HORIZON related.
The OpenNMS HORIZON Report Engine allows the creation of various kinds of reports and also supports distributed report repositories. At the moment these features are not covered by this documentation. Only reports using JasperReports are described here.

Overview

The OpenNMS HORIZON Report Engine uses the JasperReport library to create reports in various output formats. Each report template must be a *.jrxml file. The OpenNMS HORIZON Report Engine passes a JDBC Connection to the OpenNMS HORIZON Database to each report on execution.

Table 1. feature overview

Supported Output Formats

PDF, CSV

JasperReport Version

{jasperReportsVersion}

For more details on how JasperReports works, please have a look at the official documentation of Jaspersoft Studio.

Add a custom report

To add a new JasperReport report to the Local OpenNMS HORIZON Report Repository, the following steps are required.

At first a new entry in the file $OPENNMS_HOME/etc/database-reports.xml must be created.

<report
  id="MyReport" (1)
  display-name="My Report" (2)
  online="true" (3)
  report-service="jasperReportService" (4)
  description="This is an example description. It shows up in the web ui when creating an online report"  (5)
/>
1 A unique identifier.
2 The name of the report. Is shown when using the web ui.
3 Defines if this report can be executed on demand, otherwise only scheduling is possible.
4 The report service implementation to use. In most cases this is jasperReportService.
5 A description of the report. Is shown when using the web ui.

In addition a new entry in the file $OPENNMS_HOME/etc/jasper-reports.xml must be created.

<report
  id="MyReport" (1)
  template="My-Report.jrxml" (2)
  engine="jdbc" (3)
/>
1 The identifier defined in the previous step. This identifier must exist in $OPENNMS_HOME/etc/database-reports.xml.
2 The name of the template. The template must be located in $OPENNMS_HOME/etc/report-templates.
3 The engine to use. It is either jdbc or null.

Use of Jaspersoft Studio

When developing new reports it is recommended to use the Jaspersoft Studio application. It can be downloaded here.

We recommend always to use the same Jaspersoft Studio version as the JasperReport library OpenNMS HORIZON uses. Currently OpenNMS HORIZON uses version {jasperReportsVersion}.

Connect to the OpenNMS HORIZON Database

In order to actually create SQL statements against the OpenNMS HORIZON database a database Data Adapter must be created. The official Jaspersoft Studio documentation and wiki covers this aspect.

Use Measurements Datasource and Helpers

To use the Measurements API it is required to add the Measurements Datasource library to the build path of JasperStudio. This is achieved with right click in the Project Explorer and select Configure Buildpath.

1 configure build path 1
  1. Switch to the Libraries tab.

  2. Click Add External JARs and select the opennms-jasperstudio-extension-{opennms-version}-jar-with-dependencies.jar file located in $OPENNMS_HOME/contrib/jasperstudio-extension.

  3. Close the file selection dialog.

2 configure build path 2
  1. Close the dialog.

  2. The Measurements Datasource and Helpers should now be available.

  3. Go to the Dataset and Query Dialog in Jaspersoft Studio and select a language called measurement.

3 dataset query dialog
Even if there is no Read Fields functionality available, the Data preview can be used. It is required the the access to the Measurements API is possible using the connection parameters MEASUREMENT_URL, MEASUREMENT_USERNAME and MEASUREMENT_PASSWORD. The Supported Fields section gives more details. In addition you have

Accessing Performance Data

Before OpenNMS Horizon 17 and OpenNMS Meridian 2016 it was possible to access the performance data stored in .rrd or .jrobin files directly by using the jrobin language extension provided by the RrdDataSource. This is no longer possible and the Measurements Datasource has to be used.

To access performance data within reports we created a custom Measurement Datasource which allows to query the Measurements API and process the returned data in your reports. Please refer to the official Measurements API documentation on how to use the _Measurements API_.

When using the Measurements Datasource within a report a HTTP connection to the Measurements API is only established if the report is NOT running within OpenNMS HORIZON, e.g. when used with Jaspersoft Studio.

To receive data from the Measurements API simply create a query as follows:

Sample queryString to receive data from the Measurements API
<query-request step="300000" start="$P{startDateTime}" end="$P{endDateTime}" maxrows="2000"> (1)
  <source aggregation="AVERAGE" label="IfInOctets" attribute="ifHCInOctets" transient="false" resourceId="node[$P{nodeId}].interfaceSnmp[$P{interface}]"/>
  <source aggregation="AVERAGE" label="IfOutOctets" attribute="ifHCOutOctets" transient="false" resourceId="node[$P{nodeid}].interfaceSnmp[$P{interface}]"/>
</query-request>
1 The query language. In our case measurement, but JasperReports supports a lot out of the box, such as sql, xpath, etc.

Fields

Each datasource should return a number of fields, which then can be used in the report. The Measurement Datasource supports the following fields:

Field name Field type Field description

<label>

java.lang.Double

Each Source defined as transient=false can be used as a field. The name of the field is the label, e.g. IfInOctets

timestamp

 java.util.Date

The timestamp of the sample.

step

java.lang.Long

The Step size of the Response. Returns the same value for all rows.

start

java.lang.Long

The Start timestamp in milliseconds of the Resopnse. Returns the same value for all rows.

end

java.lang.Long

The End timestamp in milliseconds of the Response. Returns the same value for all rows.

For more details about the Response, please refer to the official Measurement API documentation.

Parameters

In addition to the queryString the following JasperReports parameters are supported.

Parameter name Required Description

MEASUREMENT_URL

yes

The URL of the Measurements API, e.g. http://localhost:8980/opennms/rest/measurements

MEASUREMENT_USERNAME

no

If authentication is required, specify the username, e.g. admin

MEASUREMENT_PASSWORD

no

If authentication is required, specify the password, e.g. admin

Helper methods

There are a couple of helper methods to help creating reports in OpenNMS HORIZON.

These helpers come along with the Measurement Datasource.

Table 2. supported helper methods
Helper class Helper Method Description

org.opennms.netmgt.jasper.helper.MeasurementsHelper

getNodeOrNodeSourceDescriptor(nodeId, foreignSource, foreignId)

Generates a node source descriptor according to the input paramters. Either node[nodeId] or nodeSource[foreignSource:foreignId] is returned. nodeSource[foreignSource:foreignId] is only returned if foreignSource and foreignId is not empty and not null. Otherwise always node[nodeId] is returned.

nodeId : String, the id of the node
foreignSource: String, the foreign source of the node, may be null
foreignId: String, the foreign id of the node, may be null.

For more details checkout Usage of the node source descriptor.

org.opennms.netmgt.jasper.helper.MeasurementsHelper

getInterfaceDescriptor(snmpifname, snmpifdescr, snmphysaddr)

Returns the interface descriptor of a given interface, e.g. en0-005e607e9e00. The input paramaters are prioritized. If a snmpifdescr is specified, it is used instead of the snmpifname. It a snmpifdescr is defined, it will be appended to snmpifname/snmpifdescr.

snmpifname: String, the interface name of the interface, e.g. en0. May be null.
snmpifdescr: String, the description of the interface, e.g. en0. May be null.
snmphyaddr: String, the mac address of the interface, e.g. 005e607e9e00. May be null.
As each input parameter may be null, not all of them can be null at the same time. At least one input parameter has to be defined.

For more details checkout Usage of the interface descriptor.

Usage of the interface descriptor

An interfaceSnmp is addressed with the exact interface descriptor. To allow easy access to the interface descriptor a helper tool is provided. The following example shows the usage of that helper.

jrxml report snippet to visualize the use of the interface descriptor
<parameter name="interface" class="java.lang.String" isForPrompting="false">
  <parameterDescription><![CDATA[]]></parameterDescription>
  <defaultValueExpression><![CDATA[org.opennms.netmgt.jasper.helper.MeasurementsHelper.getInterfaceDescriptor($P{snmpifname}, $P{snmpifdescr}, $P{snmpphysaddr})]]></defaultValueExpression>
</parameter>
<queryString language="Measurement">
  <![CDATA[<query-request step="300000" start="$P{startDateTime}" end="$P{endDateTime}" maxrows="2000">
<source aggregation="AVERAGE" label="IfInOctets" attribute="ifHCInOctets" transient="false" resourceId="node[$P{nodeId}].interfaceSnmp[$P{interface}]"/>
<source aggregation="AVERAGE" label="IfOutOctets" attribute="ifHCOutOctets" transient="false" resourceId="node[$P{nodeId}].interfaceSnmp[$P{interface}]"/>
</query-request>]]>

Usage of the node source descriptor

A node is addressed by a node source descriptor. The node source descriptor references the node either via the foreign source and foreign id or by the node id.

If store by foreign source is enabled only addressing the node via foreign source and foreign id is possible.

In order to make report creation easier, there is a helper method to create the node source descriptor.

For more information about store by foreign source, please have a look at our Wiki.

The following example shows the usage of that helper.

jrxml report snippet to visualize the use of the node source descriptor.
<parameter name="nodeResourceDescriptor" class="java.lang.String" isForPrompting="false">
  <defaultValueExpression><![CDATA[org.opennms.netmgt.jasper.helper.MeasurementsHelper.getNodeOrNodeSourceDescriptor(String.valueOf($P{nodeid}), $P{foreignsource}, $P{foreignid})]]></defaultValueExpression>
</parameter>
<queryString language="Measurement">
  <![CDATA[<query-request step="300000" start="$P{startDateTime}" end="$P{endDateTime}" maxrows="2000">
<source aggregation="AVERAGE" label="IfInOctets" attribute="ifHCInOctets" transient="false" resourceId="$P{nodeResourceDescriptor}.interfaceSnmp[en0-005e607e9e00]"/>
<source aggregation="AVERAGE" label="IfOutOctets" attribute="ifHCOutOctets" transient="false" resourceId="$P{nodeResourceDescriptor}.interfaceSnmp[en0-005e607e9e00]"/>
</query-request>]]>

Depending on the input parameters you either get a node resource descriptor or a foreign source/foreign id resource descriptor.

Usage of the interface descriptor

An interfaceSnmp is addressed with the exact interface descriptor. To allow easy access to the interface descriptor a helper tool is provided. The following example shows the usage of that helper.

jrxml report snippet to visualize the use of the interface descriptor
<parameter name="interface" class="java.lang.String" isForPrompting="false">
  <parameterDescription><![CDATA[]]></parameterDescription>
  <defaultValueExpression><![CDATA[org.opennms.netmgt.jasper.helper.MeasurementsHelper.getInterfaceDescriptor($P{snmpifname}, $P{snmpifdescr}, $P{snmpphysaddr})]]></defaultValueExpression>
</parameter>
<queryString language="Measurement">
  <![CDATA[<query-request step="300000" start="$P{startDateTime}" end="$P{endDateTime}" maxrows="2000">
<source aggregation="AVERAGE" label="IfInOctets" attribute="ifHCInOctets" transient="false" resourceId="node[$P{nodeId}].interfaceSnmp[$P{interface}]"/>
<source aggregation="AVERAGE" label="IfOutOctets" attribute="ifHCOutOctets" transient="false" resourceId="node[$P{nodeId}].interfaceSnmp[$P{interface}]"/>
</query-request>]]>

To get the appropriate interface descriptor depends on the input parameter.

Use HTTPS

To establish a secure connection to the Measurements API the public certificate of the running OpenNMS HORIZON must be imported to the Java Trust Store. In Addition OpenNMS HORIZON must be configured to use that Java Trust Store. Please follow the instructions in this chapter to setup the Java Trust Store correctly.

In addition please also set the property org.opennms.netmgt.jasper.measurement.ssl.enable in $OPENNMS_HOME\etc\opennms.properties to true to ensure that only secure connections are established.

If org.opennms.netmgt.jasper.measurement.ssl.enable is set to false an accidentally insecure connection can be established to the Measurements API location. A SSL secured connection can be established even if org.opennms.netmgt.jasper.measurement.ssl.enable is set to false.

Limitations

  • Only a JDBC Datasource to the OpenNMS HORIZON Database connection can be passed to a report, or no datasource at all. One does not have to use the datasource, though.