public class RrdDb extends Object implements Closeable
Main class used to create and manipulate round robin databases (RRDs). Use this class to perform
update and fetch operations on existing RRDs, to create new RRD from
the definition (object of class 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 | 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.
|
Constructor and Description |
---|
RrdDb(RrdDef rrdDef)
Constructor used to create new RRD object from the definition.
|
RrdDb(RrdDef rrdDef,
RrdBackendFactory factory)
Constructor used to create new RRD object from the definition object but with a storage
(backend) different from default.
|
RrdDb(String path)
Constructor used to open already existing RRD.
|
RrdDb(String path,
boolean readOnly)
Constructor used to open already existing RRD.
|
RrdDb(String path,
boolean readOnly,
RrdBackendFactory factory)
Constructor used to open already existing RRD backed
with a storage (backend) different from default.
|
RrdDb(String path,
RrdBackendFactory factory)
Constructor used to open already existing RRD in R/W mode with a storage (backend) type
different from default.
|
RrdDb(String rrdPath,
String externalPath)
Constructor used to create RRD files from external file sources.
|
RrdDb(String rrdPath,
String externalPath,
RrdBackendFactory factory)
Constructor used to create RRD files from external file sources with a backend type
different from default.
|
RrdDb(URI path)
Constructor used to open already existing RRD.
|
RrdDb(URI path,
boolean readOnly)
Constructor used to open already existing RRD.
|
RrdDb(URI rrdPath,
String externalPath)
Constructor used to create RRD files from external file sources.
|
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes RRD.
|
boolean |
containsDs(String dsName)
Checks presence of a specific datasource.
|
void |
copyStateTo(org.rrd4j.core.RrdUpdater other)
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.
|
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. |
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.
|
int |
getArcIndex(ConsolFun consolFun,
int steps)
Returns index of Archive object with the given consolidation function and the number
of steps.
|
byte[] |
getBytes()
Returns an array of bytes representing the whole RRD.
|
String |
getCanonicalPath()
Returns canonical path to the underlying RRD file.
|
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.
|
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.
|
boolean |
isClosed()
Returns true if the RRD is closed.
|
static void |
main(String[] args)
main.
|
static void |
setDefaultFactory(String factoryName)
Deprecated.
|
void |
setInfo(String info)
setInfo.
|
public static final String PREFIX_XML
public static final String PREFIX_RRDTool
public RrdDb(RrdDef rrdDef) throws IOException
Constructor used to create new RRD object from the definition. If the rrdDef was constructed
giving an 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 constructor 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 = new RrdDb(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 RrdDb(RrdDef rrdDef, RrdBackendFactory factory) throws IOException
Constructor used to create new RRD object from the definition object but with a storage (backend) different from default.
Rrd4j uses factories to create RRD backend objects. There are three different backend factories supplied with Rrd4j, and each factory has its unique name:
For example, to create RRD in memory, use the following code:
RrdBackendFactory factory = RrdBackendFactory.getFactory("MEMORY"); RrdDb rrdDb = new RrdDb(rrdDef, factory); rrdDb.close();
New RRD file structure is specified with an object of class
RrdDef
. The underlying RRD storage is created as soon
as the constructor returns.
rrdDef
- RRD definition objectfactory
- The factory which will be used to create storage for this RRDIOException
- Thrown in case of I/O errorRrdBackendFactory
public RrdDb(String path, boolean readOnly) throws IOException
Constructor used to open already existing RRD. The path will be parsed as an URI and checked against the active factories. If it's a relative URI (no scheme given, or just a plain path), the default factory will be used.
Constructor obtains read or read/write access to this RRD.
path
- Path to existing RRD.readOnly
- Should be set to false
if you want to update
the underlying RRD. If you want just to fetch data from the RRD file
(read-only access), specify true
. If you try to update RRD file
open in read-only mode (readOnly
set to true
),
IOException
will be thrown.IOException
- Thrown in case of I/O error.public RrdDb(String path, boolean readOnly, RrdBackendFactory factory) throws IOException
path
- Path to existing RRD.readOnly
- Should be set to false
if you want to update
the underlying RRD. If you want just to fetch data from the RRD file
(read-only access), specify true
. If you try to update RRD file
open in read-only mode (readOnly
set to true
),
IOException
will be thrown.factory
- Backend factory which will be used for this RRD.FileNotFoundException
- Thrown if the requested file does not exist.IOException
- Thrown in case of general I/O error (bad RRD file, for example).RrdBackendFactory
public RrdDb(URI path, boolean readOnly) throws IOException
Constructor used to open already existing RRD. The URI will checked against the active factories. If it's a relative URI (no scheme given, or just a plain path), the default factory will be used.
Constructor obtains read or read/write access to this RRD.
path
- Path to existing RRD.readOnly
- Should be set to false
if you want to update
the underlying RRD. If you want just to fetch data from the RRD file
(read-only access), specify true
. If you try to update RRD file
open in read-only mode (readOnly
set to true
),
IOException
will be thrown.IOException
- Thrown in case of I/O error.public RrdDb(String path) throws IOException
Constructor used to open already existing RRD. The path will be parsed as an URI and checked against the active factories. If it's a relative URI (no scheme given, or just a plain path), the default factory will be used.
Constructor obtains read/write access to this RRD.
path
- Path to existing RRD.IOException
- Thrown in case of I/O error.public RrdDb(URI path) throws IOException
Constructor used to open already existing RRD. The URI will checked against the active factories. If it's a relative URI (no scheme given, or just a plain path), the default factory will be used.
Constructor obtains read/write access to this RRD.
path
- Path to existing RRD.IOException
- Thrown in case of I/O error.public RrdDb(String path, RrdBackendFactory factory) throws IOException
path
- Path to existing RRD.factory
- Backend factory used to create this RRD.IOException
- Thrown in case of I/O error.RrdBackendFactory
public RrdDb(String rrdPath, String externalPath) throws IOException
Constructor used to create RRD files from external file sources. Supported external file sources are:
rrdtool dump
command).
The path for the new rrd will be parsed as an URI and checked against the active factories. If it's a relative URI (no scheme given, or just a plain path), the default factory will be used.
Rrd4j and RRDTool use the same format for XML dump and this constructor should be used to (re)create Rrd4j RRD files from XML dumps. First, dump the content of a RRDTool RRD file (use command line):
rrdtool dump original.rrd > original.xml
Than, use the file original.xml
to create Rrd4j RRD file named
copy.rrd
:
RrdDb rrd = new RrdDb("copy.rrd", "original.xml");
or:
RrdDb rrd = new RrdDb("copy.rrd", "xml:/original.xml");
See documentation for dumpXml()
method
to see how to convert Rrd4j files to RRDTool's format.
To read RRDTool files directly, specify rrdtool:/
prefix in the
externalPath
argument. For example, to create Rrd4j compatible file named
copy.rrd
from the file original.rrd
created with RRDTool, use
the following code:
RrdDb rrd = new RrdDb("copy.rrd", "rrdtool:/original.rrd");
Note that the prefix xml:/
or rrdtool:/
is necessary to distinguish
between XML and RRDTool's binary sources. If no prefix is supplied, XML format is assumed.
rrdPath
- Path to a RRD file which will be createdexternalPath
- Path to an external file which should be imported, with an optional
xml:/
or rrdtool:/
prefix.IOException
- Thrown in case of I/O errorpublic RrdDb(URI rrdPath, String externalPath) throws IOException
Constructor used to create RRD files from external file sources. Supported external file sources are:
rrdtool dump
command).
The path for the new rrd will be parsed as an URI and checked against the active factories. If it's a relative URI (no scheme given, or just a plain path), the default factory will be used.
Rrd4j and RRDTool use the same format for XML dump and this constructor should be used to (re)create Rrd4j RRD files from XML dumps. First, dump the content of a RRDTool RRD file (use command line):
rrdtool dump original.rrd > original.xml
Than, use the file original.xml
to create Rrd4j RRD file named
copy.rrd
:
RrdDb rrd = new RrdDb("copy.rrd", "original.xml");
or:
RrdDb rrd = new RrdDb("copy.rrd", "xml:/original.xml");
See documentation for dumpXml()
method
to see how to convert Rrd4j files to RRDTool's format.
To read RRDTool files directly, specify rrdtool:/
prefix in the
externalPath
argument. For example, to create Rrd4j compatible file named
copy.rrd
from the file original.rrd
created with RRDTool, use
the following code:
RrdDb rrd = new RrdDb("copy.rrd", "rrdtool:/original.rrd");
Note that the prefix xml:/
or rrdtool:/
is necessary to distinguish
between XML and RRDTool's binary sources. If no prefix is supplied, XML format is assumed.
rrdPath
- Path to a RRD file which will be createdexternalPath
- Path to an external file which should be imported, with an optional
xml:/
or rrdtool:/
prefix.IOException
- Thrown in case of I/O errorpublic RrdDb(String rrdPath, String externalPath, RrdBackendFactory factory) throws IOException
Constructor used to create RRD files from external file sources with a backend type different from default. Supported external file sources are:
rrdtool dump
command).
Rrd4j and RRDTool use the same format for XML dump and this constructor should be used to (re)create Rrd4j RRD files from XML dumps. First, dump the content of a RRDTool RRD file (use command line):
rrdtool dump original.rrd > original.xml
Than, use the file original.xml
to create Rrd4j RRD file named
copy.rrd
:
RrdDb rrd = new RrdDb("copy.rrd", "original.xml");
or:
RrdDb rrd = new RrdDb("copy.rrd", "xml:/original.xml");
See documentation for dumpXml()
method
to see how to convert Rrd4j files to RRDTool's format.
To read RRDTool files directly, specify rrdtool:/
prefix in the
externalPath
argument. For example, to create Rrd4j compatible file named
copy.rrd
from the file original.rrd
created with RRDTool, use
the following code:
RrdDb rrd = new RrdDb("copy.rrd", "rrdtool:/original.rrd");
Note that the prefix xml:/
or rrdtool:/
is necessary to distinguish
between XML and RRDTool's binary sources. If no prefix is supplied, XML format is assumed.
rrdPath
- Path to RRD which will be createdexternalPath
- Path to an external file which should be imported, with an optional
xml:/
or rrdtool:/
prefix.factory
- Backend factory which will be used to create storage (backend) for this RRD.IOException
- Thrown in case of I/O errorRrdBackendFactory
public void close() throws IOException
close
in interface Closeable
close
in interface AutoCloseable
IOException
- Thrown in case of I/O related error.public boolean isClosed()
public Header getHeader()
public Datasource getDatasource(int dsIndex)
dsIndex
- Datasource index (zero based)public Archive getArchive(int arcIndex)
arcIndex
- Archive index (zero based)public String[] getDsNames() throws IOException
IOException
- Thrown in case of I/O error.public Sample createSample(long time) throws IOException
Creates new sample with the given timestamp and all datasource values set to
'unknown'. Use returned 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 Sample createSample() throws IOException
Creates new sample with the current timestamp and all data source values set to
'unknown'. Use returned 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 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 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 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 String dump() throws IOException
stdout
and/or used for debugging purposes.IOException
- Thrown in case of I/O related error.public int getDsIndex(String dsName) throws IOException
dsName
- Data source name.IOException
- Thrown in case of I/O error.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 dumpXml(OutputStream destination) throws IOException
destination
- Output stream to receive XML dataIOException
- 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 String getXml() throws IOException
IOException
- Thrown in case of I/O related errorpublic String exportXml() throws IOException
getXml
method.IOException
- 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 exportXml(String filename) throws IOException
dumpXml(String)
method.filename
- a String
object.IOException
- Thrown in case of I/O related errorpublic long getLastUpdateTime() throws IOException
IOException
- if any.public RrdDef getRrdDef() throws IOException
Returns RRD definition object which can be used to create new RRD with the same creation parameters but with no data in it.
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 void copyStateTo(org.rrd4j.core.RrdUpdater other) throws IOException
copyStateTo.
Copies object's internal state to another RrdDb object.other
- a RrdUpdater
object.IOException
- if any.public Datasource getDatasource(String dsName) throws IOException
dsName
- Datasource nameIOException
- Thrown in case of I/O errorpublic int getArcIndex(ConsolFun consolFun, int steps) throws IOException
consolFun
- Consolidation functionsteps
- Number of archive stepsIOException
- Thrown in case of I/O errorpublic Archive getArchive(ConsolFun consolFun, int steps) throws IOException
consolFun
- Consolidation functionsteps
- Number of archive stepsIOException
- Thrown in case of I/O errorpublic String getCanonicalPath() throws IOException
IOException
- Thrown in case of I/O error or if the underlying backend is
not derived from RrdFileBackend.public String getPath()
public URI getUri()
public RrdBackend getRrdBackend()
public RrdAllocator getRrdAllocator()
public byte[] getBytes() throws IOException
IOException
- Thrown in case of I/O related error.@Deprecated public static void setDefaultFactory(String factoryName)
RrdBackendFactory.setActiveFactories(RrdBackendFactory...)
instead.RrdBackendFactory.setDefaultFactory(String)
.factoryName
- Name of the backend factory to be set as default.IllegalArgumentException
- Thrown if invalid factory name is supplied, or not called
before the first backend object (before the first RrdDb object) is created.public double[] getLastDatasourceValues() throws IOException
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 int getDsCount()
public int getArcCount()
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 String getInfo() throws IOException
String
object.IOException
- if any.public void setInfo(String info) throws IOException
info
- a String
object.IOException
- if any.© 2018 The RRD4J Authors. © 2001-2005 Sasa Markovic and Ciaran Treanor. © 2018 The OpenNMS Group, Inc.