rrd4j with RRDBulkWriter

Note: This repository is deprecated, please move to rrdbulkwrier

This is a clone of the rrd4j code with an additional method for openHAB users.

The method "RRDBulkWriter" will fetch the persisted data from a single item and put it into an rrd4j file (.rrd). The method is part of the "demo" package ( located under "src/main/java/org/rrd4j/demo").

The method can be called from a compiled .jar file with "java -cp rrd4j-{version}.jar org.rrd4j.demo.RRDBulkWriter" and it reads the configuration settings in the file "RRDBulkWriter.config" (example located next to the readme). This config file is expected in the folder of the .jar. Some output is printed on the terminal to show the process is working, the complete log and all other output is stored under "/user/rrd4j-demo".

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.

RRD4J supports all standard operations on Round Robin Database (RRD) files: CREATE, UPDATE, FETCH, LAST, DUMP, EXPORT and GRAPH. RRD4J's API is made for those who are familiar with RRDTool's concepts and logic, but prefer to work with pure Java (no native functions or libraries, no Runtime.exec(), RRDTool does not have to be present). We help out our users here.

Latest Version (requires Java 8+)

RRD4J 3.8 (released 2020-12-08) - Download - Changelog

Building (optional)

RRD4J is built using Maven. The generated site is available here. Automated builds are uploaded to Sonatype's repository.

The build settings allows to use any jvm, even latest one. But to produce compatible jar, it's recommended to define the path to a compatible runtime. The cross compilation settings are activated when the property is defined.

mvn clean compile -Djdk.8.home=.../jdk1.8.0_241.jdk

Or in settings.xml

<settings>
    <activeProfiles>
        <activeProfile>jdkpaths</activeProfile>
    </activeProfiles>
    <profiles>
        <profile>
            <id>jdkpaths</id>
            <properties>
                <jdk.8.home>.../jdk1.8.0_241.jdk</jdk.8.home>
            </properties>
        </profile>
    </profiles>
</settings>

Tests needs a running mongo instance to succeds. It could be started with:

docker run --rm  -p 27017:27017 mongo:latest

Using with Maven

Add this dependency to your project's POM file:

<dependency>
    <groupId>org.rrd4j</groupId>
    <artifactId>rrd4j</artifactId>
    <version>3.8</version>
</dependency>

Why RRD4J?

• Portable files, RRDTool files are not
• Simple API
• Supports the same data source types as RRDTool (COUNTER, ABSOLUTE, DERIVE, GAUGE)
• Supports the same consolidation functions as RRDTool (AVERAGE, MIN, MAX, LAST) and adds TOTAL, FIRST
• Supports almost all RRDTool RPN functions (wiki/see RPNFuncs)
• Multiple backends, e.g. use MongoDB as data store

Usage Example

import java.awt.Color;

import org.rrd4j.core.*;
import org.rrd4j.graph.*;
import static org.rrd4j.ConsolFun.*;

String rrdPath = "my.rrd";

// first, define the RRD
RrdDef rrdDef = new RrdDef(rrdPath, 300);
rrdDef.addArchive(AVERAGE, 0.5, 1, 600); // 1 step, 600 rows
rrdDef.addArchive(AVERAGE, 0.5, 6, 700); // 6 steps, 700 rows
rrdDef.addArchive(MAX, 0.5, 1, 600);

// then, create a RrdDb from the definition and start adding data
try (RrdDb rrdDb = RrdDb.getBuilder().setRrdDef(rrdDef).build()) {
    Sample sample = rrdDb.createSample();
    while (...) {
        double inbytes = ...
        double outbytes = ...
        sample.setValue("inbytes", inbytes);
        sample.setValue("outbytes", outbytes);
        sample.update();
    }
}

// then create a graph definition
RrdGraphDef gDef = new RrdGraphDef();
gDef.setWidth(500);
gDef.setHeight(300);
gDef.setFilename("inbytes.png");
gDef.setTitle("My Title");
gDef.setVerticalLabel("bytes");
gDef.datasource("inbytes-average", rrdPath, "inbytes", AVERAGE);
gDef.line("inbytes-average", Color.BLUE, "Bytes In");
gDef.hrule(2568, Color.GREEN, "hrule");
gDef.setImageFormat("png");

// then actually draw the graph
RrdGraph graph = new RrdGraph(gDef); // will create the graph in the path specified

Go through the source of Demo for more examples. The package org.rrd4j.demo contains other demo code.

Supported Backends

Next to memory and file storage, RRD4J supports the following backends (using byte array storage):

• MongoDB - a scalable, high-performance, open source, document-oriented database.
• Oracle Berkeley DB Java Edition - an open source, embeddable database providing developers with fast, reliable, local persistence with zero administration.

Clojure

Thanks to the rrd4clj project Clojure now has a RRD API (using RRD4J). Check out their examples.

Contributing

If you are interested in contributing to RRD4J, start by posting pull requests to issues that are important to you. Subscribe to the discussion group and introduce yourself.

If you can't contribute, please let us know about your RRD4J use case. Always good to hear your stories!

Graph Examples (from the JRDS project)

License

Licensed under the Apache License, Version 2.0.