• Antelope Release 5.5 Mac OS X 10.8.5 2015-04-21

 

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

PARAMETER FILE

Parameters

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
Printer icon