NAME
orb2rrdc - populate a round-robin database from an orbserver
SYNOPSIS
orb2rrdc [-vV] [-d cachedaemon] [-s statefile] [-p pffile] [-m match]
[-f from] orb dbcache
SUPPORT
Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.
FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.
DESCRIPTION
orb2rrdc enters state-of-health information from an Antelope orbserver
into a round-robin database using rrdtool(1). Every round-robin-database (rrd)
file constructed is entered into the
rrdcache table of a caching
database (this table is an extension of the css3.0 schema). The orb2rrdc.pf
parameter file governs the variables which are extracted from the status
packets, as well as the pathnames for the generated RRD files, the types
of RRD variables used (see rrdtool(1)), and the types of round-robin
archives that are stored (see rrdtool(1)).
The parameter file allows the user to specify a default network for the incoming
status packets, should they be from an application
that does not use the
sta_chan form for
dls array entries.
OPTIONS
-
-d cachedaemon
If this option is given, the update commands issued to rrdtool(1)
include an argument --daemon=cachedaemon, intended to direct actual file
updates through the rrdcached(1) program. See the man-page for rrdcached(1) for
further information. The rrdcached daemon is assumed to be already running.
-
-s statefile
Specify a state-file to use for tracking and synchronizing the current
read position in the orb.
-
-f from
Specify a starting position for reading the orb stream. This may be
a string time interpretable by str2epoch(3), or the string newest or
oldest. To avoid confusion, the -f argument is ignored if the -s
option is also given (i.e. if a statefile is used).
-
-m match
Specify a regular-expression subset of orb source-names to monitor.
The default is .*/pf/st.
-
-p pffile
Specify a parameter file other than the default orb2rrdc.pf
-
-v
Verbose
-
-V
Very Verbose
PARAMETER FILE
Parameters
-
default_network
The rrdcache database table uses the seismic net name as one of the keys to uniquely identify each RRD
database file. If this net name cannot be derived from an incoming parameter-file of status information,
the value of net specified by this default_network parameter is assigned.
-
dls_vars
The dls_vars table specifies the variables from each incoming parameter-file packet of status information that
should be archived in RRD databases. Each table row consists of three (or more) elements separated by spaces.
The first element is the name of the status variable to archive. The second element is a string of data-source parameters
(rrdtool DS:... string) that is given to the rrdtool create command when first setting up the RRD database
for this variable. For further information on specifying the data-source string, see the documentation for
rrdcreate(1). The third (and following) elements give one or more round-robin archive specifiers
(rrdtool RRA:... strings), also given to the rrdtool create command when first setting up the RRD database
for this variable. For further information on specifying the RRA strings, see the documentation for rrdcreate(1).
-
rrdfile_pattern
This parameter specifies, in the style of the trwfname(3) function, the way to construct the names of rrd cache
files in which to save collected data points.
-
rrdtool
This parameter gives the name of the rrdtool executable to invoke. If rrdtool is on the execution
path, the value of this parameter may be simply rrdtool. Alternatively, an absolute path to the
rrdtool executable may be given.
-
status_stepsize_sec
This parameter specifies the base interval in seconds at which data will be fed into the RRD database. This value
is given as the --step argument to the rrdtool create command. For further explanation, see the rrdtool(1)
documentation.
-
suppress_egrep
If this string parameter is not empty, orb2rrdc uses it as an egrep(1) expression, passing the output of
rrdtool through the egrep(1) command with the -v option to filter out all lines matching the pattern.
(This parameter will have no effect if the egrep(1) command is not present on the execution path).
Parameter File Example
rrdtool rrdtool
# Convenient parameter-file macros:
# --------------------------------
status_heartbeat_sec 40 # status_stepsize_sec * 2
archives RRA:AVERAGE:0.5:&status_stepsize_sec:1200 RRA:MAX:0.5:60:700
# Actual orb2rrdc parameters:
# --------------------------
rrdfile_pattern rrd/%{net}_%{sta}_%{rrdvar}.rrd
status_stepsize_sec 20 # e.g. use statusreport_interval from q3302orb.pf
default_network &ref(site,default_seed_network)
suppress_OK 0
dls_vars &Tbl{
br24 GAUGE:&status_heartbeat_sec:U:U &archives
lcq GAUGE:&status_heartbeat_sec:U:U &archives
}
EXAMPLE
% orb2rrdc -v -s state/orb2rrdc anfops.ucsd.edu:usarray db/rrdcache
SEE ALSO
rrdtool(1)
BUGS AND CAVEATS
orb2rrdc will only compile and run if Tobias Oetiker's rrdtool(1) is
installed, currently available from
http://people.ee.ethz.ch/oetiker/webtools/rrdtool/
Currently orb2rrdc is designed to handle q3302orb .*/pf/st status packets.
If given a regular expression match for orb packets that include waveform
data, orb2rrdc will actually also save RRD databases of waveform
data (via the
chan_vars parameter-file array, similar to
dls_vars), however this is not advised for seismic waveform data proper due to the
built-in averaging and the limitation to one-second or greater time steps.
It might be nice to have a regular-expression limiting the stations which
are chosen out of the status packets. This can be added if necessary.
The orb2rrdc name is temporary until the newly written version has proven itself.
The rrdtool parameter-file value must either be the literal string
rrdtool
or an absolute path to the
rrdtool executable.
orb2rrdc will translate the string field
opt, if present in the input
parameter file, into the five fields
acok,
api,
isp1,
isp2,
and
ti. If any of those string fields are present in the value of
opt,
the corresponding added parameter will be assigned a value of 1. If
opt is present
and non-null but does not contain the name of the new parameter, the newly added
parameter will be assigned a value of 0. If
opt is missing or null ("-") for
a given station in an input parameter file, these five new parameters will be set to
"-".
When using the
-d option,
orb2rrdc assumes the rrdcached(1) daemon has been
separately started and is already running. For example, rrdcached(1) might be started
under
rtexec(1) with something like
rrdcached -F -g -l unix:/home/rt/rrdcached.sock
In that case, orb2rrdc would be started with the option
-d unix:/home/rt/rrdcached.sock.
At this time, rrdtool updates appear to experience problems if the rrdcached is restarted
and the rrdtool server launched by orb2rrdc is not restarted (the solution being to restart
orb2rrdc also if rrdcached is restarted).
orb2rrdc deliberately does not send
create commands through the rrdcached daemon, since
at the time of writing the daemon does not support them.
The
-f and
-s options provide potentially conflicting messages. Thus, if both are given,
the
-f option is ignored. In principle, one could allow both options to be specified, acting on the
-f option if and only if a state file were specified but not present. That would allow the user
to rewind to a given point to start catching up, then continue on once caught up without a restart. This
has not been implemented, however.
orb2rrdc currently ignores values of
- in input parameter files from the orbserver, since those
cannot be added as floating-point values to round-robin databases. Alternatively,
orb2rrdc could
add
U i.e. "UNKNOWN" values to the round-robin databases, however this also has not been implemented.
The
suppress_egrep capability filters out only output from
rrdtool. It will not suppress any
messages that come directly from
orb2rrdc itself. Some understanding of
rrdtool is thus necessary to
use this feature successfully.
AUTHOR
Kent Lindquist
Lindquist Consulting, Inc.
Antelope User Group Contributed Software