RRD4j online integration

As opposite to RRD4j offline rendering it is possible to record and render RRD performance results near to real-time. Therefore JETM provides an RRD4j extension that stores executions times in given RRD4j databases at recording time and render graphs on demand.

Note that the current RRD4j online integration is experimental and should not be used in high traffic situations. While it should create exactly the same results seen at RRD4j offline support it is pretty much untested yet.

Step 1: Prerequisites

In order to use JETM RRD4j support you need to add all RRD4j libraries to your application runtime classpath. You can download the current RRD4j distribution here. Be aware that RRD4j requires Java™ 5.0 or higher.

Step 2: Create target RRD databases

The RRD4j online integration will record performance results into existing RRD databases. Therefore it is up to you to create those files before running an RRD4j enabled JETM runtime. The easiest way to create those files is using the command line tool described in RRD4j offline integration.

The following example creates two RRD DB files, one for Soap Actions and another one for HTTP requests using a high resolution database:

java etm.contrib.rrd.rrd4j.Rrd4jMain create-db -t highres -d /tmp/soap_actions.rrd
java etm.contrib.rrd.rrd4j.Rrd4jMain create-db -t highres -d /tmp/http_requests.rrd

Step 3: Enable RRD recording

To enable RRD4j online recording you need to add the Rrd4jPlugin and enable notifications for newly recorded performance results. The following JETM config excerpt uses static EtmManger configuration, nevertheless the same features can be actived in a Springframework based environment or manually via EtmMonitor API.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jetm-config PUBLIC "-// void.fm //DTD JETM Config 1.2//EN"
                             "http://jetm.void.fm/dtd/jetm_config_1_2.dtd">

<jetm-config>
  <features>
    ...
    <notifications />
  </features>
  
  <extension>
    <plugin class="etm.contrib.rrd.rrd4j.Rrd4jPlugin">
      <property name="destinations">soap_actions.rrd!^SoapAction.+</property>
      <property name="destinations">http_requests.rrd!^HTTP.+</property>
      <property name="rrdFilePath" ref="/tmp"/>
    </plugin>
  </extension>
</jetm-config>

The configuration above defines two target RRD databases located in /tmp. The first database called soap_actions.rrd will be used for all measurement points that match the regular expression ^SoapAction.+, while the second database http_requests.rrd is the destination for all performance results matching ^HTTP.+.

Step 4: Create performance graphs

Now there are two options to render grapical performance statistics: One option is the command line tool described in RRD4j offline integration. And the other option is a dedicated plugin that will create images online.

The plugin Rrd4jImageGeneratorPlugin pretty much works like command line tool.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jetm-config PUBLIC "-// void.fm //DTD JETM Config 1.2//EN"
                             "http://jetm.void.fm/dtd/jetm_config_1_2.dtd">

<jetm-config>
  ...

  <extension>
    <plugin class="etm.contrib.rrd.rrd4j.Rrd4jPlugin">
     ...
    </plugin>

    <plugin class="etm.contrib.rrd.rrd4j.Rrd4jImageGeneratorPlugin">
      <property name="generationInterval">60</property>
      <property name="templateName">max-average</property>
      <property name="renderInterval">3600</property>
      <property name="offset">121</property>
      <property name="templateProperties.imagefile">/tmp/performance_1h.png</property>
      <property name="templateProperties.rrdfile">/tmp/soap_actions.rrd</property>
      <property name="templateProperties.imagetitle">SOAP actions last hour</property>
    </plugin>   
  </extension>
</jetm-config>