public class RrdDb extends Object implements RrdUpdater<RrdDb>, Closeable
RrdDef) or from XML file (dumped content of RRDTool's or
Rrd4j's RRD file).
Each RRD is backed with some kind of storage. For example, RRDTool supports only one kind of storage (disk file). On the contrary, Rrd4j gives you freedom to use other storage (backend) types even to create your own backend types for some special purposes. Rrd4j by default stores RRD data in files (as RRDTool), but you might choose to store RRD data in memory (this is supported in Rrd4j), to use java.nio.* instead of java.io.* package for file manipulation (also supported) or to store whole RRDs in the SQL database (you'll have to extend some classes to do this).
Note that Rrd4j uses binary format different from RRDTool's format. You cannot use this class to manipulate RRD files created with RRDTool. However, if you perform the same sequence of create, update and fetch operations, you will get exactly the same results from Rrd4j and RRDTool.
You will not be able to use Rrd4j API if you are not familiar with basic RRDTool concepts. Good place to start is the official RRD tutorial and relevant RRDTool man pages: rrdcreate, rrdupdate, rrdfetch and rrdgraph. For RRDTool's advanced graphing capabilities (RPN extensions), also supported in Rrd4j, there is an excellent CDEF tutorial.
RrdBackend,
RrdBackendFactory| Modifier and Type | Class and Description |
|---|---|
static class |
RrdDb.Builder
Builder for
RrdDb instances. |
| Modifier and Type | Field and Description |
|---|---|
static String |
PREFIX_RRDTool
Prefix to identify external RRDTool file source used in various RrdDb constructors.
|
static String |
PREFIX_XML
Prefix to identify external XML file source used in various RrdDb constructors.
|
(package private) static int |
XML_BUFFER_CAPACITY |
| Modifier and Type | Method and Description |
|---|---|
(package private) void |
archive(Datasource datasource,
double value,
double lastValue,
long numUpdates) |
void |
close()
Closes RRD.
|
boolean |
containsDs(String dsName)
Checks presence of a specific datasource.
|
void |
copyStateTo(RrdDb otherRrd)
copyStateTo.
|
FetchRequest |
createFetchRequest(ConsolFun consolFun,
long fetchStart,
long fetchEnd)
Prepares fetch request to be executed on this RRD.
|
FetchRequest |
createFetchRequest(ConsolFun consolFun,
long fetchStart,
long fetchEnd,
long resolution)
Prepares fetch request to be executed on this RRD.
|
Sample |
createSample()
Creates new sample with the current timestamp and all data source values set to 'unknown'.
|
Sample |
createSample(long time)
Creates new sample with the given timestamp and all datasource values set to 'unknown'.
|
String |
dump()
Returns string representing complete internal RRD state.
|
void |
dumpXml(OutputStream destination)
Writes the RRD content to
OutputStream using XML format. |
void |
dumpXml(String filename)
Dumps internal RRD state to XML file.
|
void |
dumpXml(XmlWriter writer)
Writes the RRD content to
XmlWriter using XML format. |
String |
exportXml()
This method is just an alias for
getXml method. |
void |
exportXml(OutputStream destination)
This method is just an alias for
dumpXml method. |
void |
exportXml(String filename)
This method is just an alias for
dumpXml(String) method. |
(package private) FetchData |
fetchData(FetchRequest request) |
Archive |
findMatchingArchive(FetchRequest request)
findMatchingArchive.
|
Archive |
findStartMatchArchive(String consolFun,
long startTime,
long resolution)
Finds the archive that best matches to the start time (time period being start-time until
now) and requested resolution.
|
int |
getArcCount()
Returns the number of RRA archives defined in the file
|
Archive |
getArchive(ConsolFun consolFun,
int steps)
Returns Archive object with the given consolidation function and the number of steps.
|
Archive |
getArchive(int arcIndex)
Returns Archive object for the given archive index.
|
(package private) Archive[] |
getArchives() |
int |
getArcIndex(ConsolFun consolFun,
int steps)
Returns index of Archive object with the given consolidation function and the number of
steps.
|
static RrdDb.Builder |
getBuilder() |
byte[] |
getBytes()
Returns an array of bytes representing the whole RRD.
|
String |
getCanonicalPath()
Returns canonical path to the underlying RRD file.
|
URI |
getCanonicalUri() |
Datasource |
getDatasource(int dsIndex)
Returns Datasource object for the given datasource index.
|
Datasource |
getDatasource(String dsName)
Returns Datasource object corresponding to the given datasource name.
|
(package private) Datasource[] |
getDatasources() |
int |
getDsCount()
Returns the number of datasources defined in the file
|
int |
getDsIndex(String dsName)
Returns internal index number for the given datasource name.
|
String[] |
getDsNames()
Returns an array of datasource names defined in RRD.
|
Header |
getHeader()
Returns RRD header.
|
String |
getInfo()
getInfo.
|
long |
getLastArchiveUpdateTime()
Returns the last time when some of the archives in this RRD was updated.
|
double |
getLastDatasourceValue(String dsName)
Returns the last stored value for the given datasource.
|
double[] |
getLastDatasourceValues()
Returns an array of last datasource values.
|
long |
getLastUpdateTime()
Returns time of last update operation as timestamp (in seconds).
|
String |
getPath()
Returns the path to this RRD.
|
RrdAllocator |
getRrdAllocator()
Required to implement RrdUpdater interface.
|
RrdBackend |
getRrdBackend()
Returns backend object for this RRD which performs actual I/O operations.
|
RrdDef |
getRrdDef()
Returns RRD definition object which can be used to create new RRD with the same creation
parameters but with no data in it.
|
URI |
getUri()
Returns the URI to this RRD, as seen by the backend.
|
String |
getXml()
Returns string representing internal RRD state in XML format.
|
(package private) void |
internalClose() |
boolean |
isClosed()
Returns true if the RRD is closed.
|
static void |
main(String[] args)
main.
|
static RrdDb |
of(RrdDef rrdDef)
Returns a new RRD object from the definition.
|
static RrdDb |
of(String path)
Opens an existing RRD with read/write access.
|
static RrdDb |
of(URI uri)
Opens an existing RRD with read/write access.
|
void |
setInfo(String info)
setInfo.
|
(package private) void |
store(Sample sample) |
public static final String PREFIX_RRDTool
public static final String PREFIX_XML
static final int XML_BUFFER_CAPACITY
final void archive(Datasource datasource, double value, double lastValue, long numUpdates) throws IOException
IOExceptionpublic void close()
throws IOException
close in interface Closeableclose in interface AutoCloseableIOException - Thrown in case of I/O related error.IllegalStateException - if the thread was interrupted in pool usage.public boolean containsDs(String dsName) throws IOException
dsName - Datasource name to checktrue if datasource is present in this RRD, false otherwiseIOException - Thrown in case of I/O error.public void copyStateTo(RrdDb otherRrd) throws IOException
Copies object's internal state to another RrdDb object.
copyStateTo in interface RrdUpdater<RrdDb>otherRrd - a RrdUpdater object.IOException - if any.public FetchRequest createFetchRequest(ConsolFun consolFun, long fetchStart, long fetchEnd)
FetchRequest
object and its fetchData() method to actually
fetch data from this RRD. Data will be fetched with the smallest possible resolution (see
RRDTool's rrdfetch
man page for the explanation of the resolution parameter).consolFun - Consolidation function to be used in fetch request.fetchStart - Starting timestamp for fetch request.fetchEnd - Ending timestamp for fetch request.public FetchRequest createFetchRequest(ConsolFun consolFun, long fetchStart, long fetchEnd, long resolution)
FetchRequest
object and its fetchData() method to actually
fetch data from the RRD file.consolFun - Consolidation function to be used in fetch request.fetchStart - Starting timestamp for fetch request.fetchEnd - Ending timestamp for fetch request.resolution - Fetch resolution (see RRDTool's rrdfetch man
page for an explanation of this parameter.public Sample createSample() throws IOException
Sample object to specify datasource values for the current
timestamp. See documentation for Sample for an explanation how to do this.
Once populated with data source values, call Sample's update() method to actually store sample in the RRD
associated with it.
IOException - Thrown in case of I/O error.public Sample createSample(long time) throws IOException
Sample object to specify datasource values for the given timestamp. See
documentation for Sample for an explanation how to do this.
Once populated with data source values, call Sample's update() method to actually store sample in the RRD
associated with it.
time - Sample timestamp rounded to the nearest second (without milliseconds).IOException - Thrown in case of I/O error.public String dump() throws IOException
stdout and/or used for debugging purposes.IOException - Thrown in case of I/O related error.public void dumpXml(OutputStream destination) throws IOException
OutputStream using XML format. This format is fully
compatible with RRDTool's XML dump format and can be used for conversion purposes or
debugging.destination - Output stream to receive XML dataIOException - Thrown in case of I/O related errorpublic void dumpXml(String filename) throws IOException
Suppose that you have a Rrd4j RRD file original.rrd and you want to convert
it to RRDTool format. First, execute the following java code:
RrdDb rrd = new RrdDb("original.rrd");
rrd.dumpXml("original.xml");
Use original.xml file to create the corresponding RRDTool file (from your
command line):
rrdtool restore copy.rrd original.xml
filename - Path to XML file which will be created.IOException - Thrown in case of I/O related error.public void dumpXml(XmlWriter writer) throws IOException
XmlWriter using XML format. This format is fully compatible
with RRDTool's XML dump format and can be used for conversion purposes or debugging.writer - XmlWriter to receive XML dataIOException - Thrown in case of I/O related errorpublic String exportXml() throws IOException
getXml method.IOException - Thrown in case of I/O related errorpublic void exportXml(OutputStream destination) throws IOException
dumpXml method.destination - a OutputStream object.IOException - Thrown in case of I/O related errorpublic void exportXml(String filename) throws IOException
dumpXml(String) method.filename - a String object.IOException - Thrown in case of I/O related errorFetchData fetchData(FetchRequest request) throws IOException
IOExceptionpublic Archive findMatchingArchive(FetchRequest request) throws IOException
request - a FetchRequest object.Archive object.IOException - if any.public Archive findStartMatchArchive(String consolFun, long startTime, long resolution) throws IOException
consolFun - Consolidation function of the datasource.startTime - Start time of the time period in seconds.resolution - Requested fetch resolution.IOException - Thrown in case of I/O related error.public int getArcCount()
public Archive getArchive(ConsolFun consolFun, int steps) throws IOException
consolFun - Consolidation functionsteps - Number of archive stepsIOException - Thrown in case of I/O errorpublic Archive getArchive(int arcIndex)
arcIndex - Archive index (zero based)Archive[] getArchives()
public int getArcIndex(ConsolFun consolFun, int steps) throws IOException
consolFun - Consolidation functionsteps - Number of archive stepsIOException - Thrown in case of I/O errorpublic static RrdDb.Builder getBuilder()
public byte[] getBytes()
throws IOException
IOException - Thrown in case of I/O related error.public String getCanonicalPath() throws IOException
IOException - Thrown in case of I/O error or if the underlying backend is not
derived from RrdFileBackend.public URI getCanonicalUri()
public Datasource getDatasource(int dsIndex)
dsIndex - Datasource index (zero based)public Datasource getDatasource(String dsName) throws IOException
dsName - Datasource nameIOException - Thrown in case of I/O errorDatasource[] getDatasources()
public int getDsCount()
public int getDsIndex(String dsName) throws IOException
dsName - Data source name.IOException - Thrown in case of I/O error.public String[] getDsNames() throws IOException
IOException - Thrown in case of I/O error.public Header getHeader()
public String getInfo() throws IOException
String object.IOException - if any.public long getLastArchiveUpdateTime()
throws IOException
getLastUpdateTime() since RRD file can be updated without updating any
of the archives.IOException - Thrown in case of I/O errorpublic double getLastDatasourceValue(String dsName) throws IOException
dsName - Datasource nameIOException - Thrown in case of I/O errorIllegalArgumentException - Thrown if no datasource in this RrdDb matches the
given datasource namepublic double[] getLastDatasourceValues()
throws IOException
IOException - Thrown in case of I/O errorpublic long getLastUpdateTime()
throws IOException
IOException - if any.public String getPath()
public RrdAllocator getRrdAllocator()
getRrdAllocator in interface RrdUpdater<RrdDb>public RrdBackend getRrdBackend()
getRrdBackend in interface RrdUpdater<RrdDb>public RrdDef getRrdDef() throws IOException
Example:
RrdDb rrd1 = new RrdDb("original.rrd");
RrdDef def = rrd1.getRrdDef();
// fix path
def.setPath("empty_copy.rrd");
// create new RRD file
RrdDb rrd2 = new RrdDb(def);
IOException - if any.public URI getUri()
public String getXml() throws IOException
IOException - Thrown in case of I/O related errorvoid internalClose()
throws IOException
IOExceptionpublic boolean isClosed()
public static RrdDb of(RrdDef rrdDef) throws IOException
URI, RrdBackendFactory.findFactory(URI) will be used to
resolve the needed factory. If not, or a relative URI was given, this RRD object will be
backed with a storage (backend) of the default type. Initially, storage type defaults to
"NIO" (RRD bytes will be put in a file on the disk). Default storage type can be changed with
a static RrdBackendFactory.setDefaultFactory(String) method call.
New RRD file structure is specified with an object of class RrdDef.
The underlying RRD storage is created as soon as the method returns.
Typical scenario:
// create new RRD definition
RrdDef def = new RrdDef("test.rrd", 300);
def.addDatasource("input", DsType.DT_COUNTER, 600, 0, Double.NaN);
def.addDatasource("output", DsType.DT_COUNTER, 600, 0, Double.NaN);
def.addArchive(ConsolFun.CF_AVERAGE, 0.5, 1, 600);
def.addArchive(ConsolFun.CF_AVERAGE, 0.5, 6, 700);
def.addArchive(ConsolFun.CF_AVERAGE, 0.5, 24, 797);
def.addArchive(ConsolFun.CF_AVERAGE, 0.5, 288, 775);
def.addArchive(ConsolFun.CF_MAX, 0.5, 1, 600);
def.addArchive(ConsolFun.CF_MAX, 0.5, 6, 700);
def.addArchive(ConsolFun.CF_MAX, 0.5, 24, 797);
def.addArchive(ConsolFun.CF_MAX, 0.5, 288, 775);
// RRD definition is now completed, create the database!
RrdDb rrd = RrdDb.of(def);
// new RRD file has been created on your disk
rrdDef - Object describing the structure of the new RRD file.IOException - Thrown in case of I/O error.public static RrdDb of(String path) throws IOException
path - Path to existing RRD.IOException - Thrown in case of I/O error.public static RrdDb of(URI uri) throws IOException
uri - URI to existing RRD.IOException - Thrown in case of I/O error.public void setInfo(String info) throws IOException
info - a String object.IOException - if any.final void store(Sample sample) throws IOException
IOException