Keygrabber configuration¶
Command-line options¶
All options can be specified on the command line, though most are only used
for debugging. It is recommended that only the -c option be used for
production use.
The following is the output of keygrabber -h, which describes the available
command line options.
Usage: keygrabber [options]
Optional flags:
-h,-? Print verbose help (this output)
--help
-c filename Set config file location (recommended)
--config=filename Default: None
-y filename Set keyheader config file location
--keyheader-config=filename Default: None
-l logdirectory Directory for secondary keyword log files
--logpath=logdirectory Set to 'none' to disable this log.
Default: /tmp
-g period How often to synchronously purge recorded events
--purge=period Must be one of: hourly daily weekly
monthly. Set to 'none' to disable.
Default: None
-s servicename KTL service to monitor
--service=servicename Must be set here or in config file
-b keyword Keyword to monitor service connectivity
--heartbeat=keyword Applies to the most recent --service,
or if defined with 'service.keyword'
syntax, will apply to the designated
service; only the absence or return
of a heartbeat is recorded, its normal
value will not be recorded.
-i keyword Keyword name to ignore
--ignore=keyword Applies to the most recent --service,
or if defined with 'service.keyword'
syntax, will apply to the designated
service.
-r fidelity Recording level to use
--record=fidelity Applies globally if no --service has
been specified, otherwise to the most
recent --service. Valid values are
'most', 'all', or 'none'.
Default: most
-e period Synchronous processing interval to record data
--period=period Applies globally if no --service has
been specified, otherwise to the most
recent --service. Any floating point
number is acceptable.
Default: 0.9
-t window Time window for the retention of events
--expiration=window The value specified must be parseable
by GNU `date`. Useful values will be
strings like "5 minutes ago", "2 hours
ago", "7 days ago." Set to 'none' to
disable.
Default: None
-v representation KTL representation used to determine duplicates
-value=representation Must be one of 'ascii' or 'binary'.
Applies globally if no --service has
been specified, otherwise to the most
recent --service.
Default: binary
-a hostname PostgreSQL database host
--hostname=hostname Default: localhost
-d database PostgreSQL database name
--database=database Default: keywordlog
-u username PostgreSQL role
--user username Default: turk
-p password PostgreSQL password
--password=password Default: no password
Configuration file¶
keygrabber uses the ConfigParser Python module to parse its
configuration file. All of the module’s syntax features, such as inline
variable substitutions and explicit default values, are supported by keygrabber.
Refer to the sample configuration file below and to the
ConfigParser documentation for specific information on the
required file structure.
Sample configuration¶
# Sample configuration file for the 'keygrabber' KTL keyword logger. # # The configuration file is broken into named sections, with each section # labelled in the following manner: # # [label] # # All section names designate KTL services, with four exceptions: the # [main] section, which contains options relevant for the entire keygrabber # instance; the [database] section, which contains options relating to the # PostgreSQL configuration; the [environment] section, which contains # environment variables that will be set early in the execution sequence; # and the [DEFAULT] section, which contains options that will be used as # default values for all other [service] blocks. # # All sections, including [main], [database], and [environment] are strictly # optional. # # The order in which options will be applied are as follows: # # [DEFAULT] configuration block # [service] configuration block # command line options # # Each subsequent option assignment overwrites the previous assignment, with # the sole exception of 'heartbeat' and 'ignore' declarations on the command # line. # # Configuration directives are of the form: # # Option: value # Option = value # # Option names are case-insensitive; values typically are case-insensitive. # Values should not be quoted, even if there is embedded whitespace. # The hash (#) character starts a comment, as does a semi-colon (;); only # the semi-colon may be used for inline comments. # # For more information on the parsing of the file, see the Python documentation: # # http://docs.python.org/2/library/configparser.html # # Unless specified otherwise, the example values used in the commented-out # assignments are the default values for the individual parameters. [main] # Where to write out the PostgreSQL COPY-formatted log and a log of any # UPDATE statements for any monitored services. These secondary log files # are vital for archived data, as they allow trivial backups of accumulated # data, and make migration to a new database host relatively trivial. Set # to 'none' to disable the secondary logs for this keygrabber instance. # # Logs: /tmp # How often to purge records in the PostgreSQL database. In addition to # setting this 'purge' directive, the 'expiration' directive must also be # set on a per-service basis (or in the DEFAULT block). These expiration # options should not be used with a keygrabber operating in an archival # mode; they are intended for instances whose objective is short-term # data retention, as might facilitate the acquisition of KTL keyword data # for inclusion in FITS headers. # # Valid options for 'purge' are: # # hourly # daily # weekly # monthly # # For maximum effectiveness, the period of 'purge' operations should be # shorter than the expiration window. If set to 'None' or to an empty # value, no purges will occur. # # Purge: None [database] # PostgreSQL server host name. # # Hostname: localhost # PostgreSQL database name. # # Database: keywordlog # PostgreSQL user (role) name. # # Username: turk # PostgreSQL password. The default is to not use a password, but if one # is set, it will be used. # # Password: None [environment] # All entries in the [environment] block are value assignments for environment # variables. All values set in this way will be exported before any KTL services # are loaded. This is useful for KTL client architectures that require the use # of environment variables to load correctly (RPC, CAke). Any variables set in # this way will override any value(s) already present in the process's # environment. # EPICS_CA_AUTO_ADDR_LIST=NO # EPICS_CA_ADDR_LIST: 128.171.136... # All [service] blocks can contain the same options. Multiple [service] # blocks may be declared in a single keygrabber configuration file; if # there are configuration options that are common to all the [service] # blocks, they should be declared in the special [DEFAULT] block. [servicename] # Options go here... [anotherservice] # Different options go here... [thirdservice] # The remaining options in this file would be part of this block. # Recording level to use. Valid values are as follows: # # most record all unique broadcasts, but discard any broadcasts # that arrive before Period seconds have elapsed. # # all record all broadcasts, regardless of the rate at which the # broadcasts arrive or whether the broadcast is a repeat of # the current value. # # none record no broadcasts. This is not a terribly useful # setting for production use. # # Record: most # Keyword broadcast events are put into a queue when they arrive, and # are subsequently processed at synchronous intervals determined by the # Period parameter. If Record is set to 'most', only one broadcast event # within Period seconds will be recorded for an individual keyword. # Any floating point number is valid. # # Period: 0.9 # If Record is set to 'most', the KTL representation selected by Value # will be used to determine whether a given KTL broadcast is a duplicate # of the previous broadcast. Valid choices are 'ascii' and 'binary'. # # Value: binary # Heartbeat keyword associated with this Service. May be specified # with multiple comma or whitespace-separated values, and may use # common glob wildcards (? or *). There is no default. If declared # multiple times, only the last declaration will be used, they are # not cumulative. # # Heartbeat: heartbeat1 # Heartbeat: heartbeat2, heartbeat3 # Heartbeat: heartbeat4 heartbeat5 # Heartbeat: heartbeat* # Grace period before the absence of a heartbeat update is considered # a problem. Most heartbeat keywords broadcast on a 1 Hz basis; some # do not. The same grace period will be applied for all heartbeat # keywords defined for this service. The grace period is defined as a # floating point number of seconds. # # Grace: 7 # Style of updates for a heartbeat keyword. A typical heartbeat keyword # is a monotonically increasing numeric value; some older KTL services # do not provide a dedicated heartbeat keyword but do provide keywords # that update regularly, but are not necessarily monotonically increasing. # The default style is "increment" where the heartbeat keyword is expected # to monotonically increase. The "change" style expects the heartbeat keyword # to change (and be broadcast) within the grace period. The "broadcast" style # only expects a broadcast to occur with or without an actual change in the # reported value. # # The same beat style will be used for all heartbeat keywords defined for # this service. # # Beats: increment # Beats: change # Beats: broadcast # Keyword to exclude/ignore within this Service. May be specified with multiple # comma or whitespace-separated values, and may use common glob wildcards # (? or *). There is no default. If declared multiple times, only the last # declaration will be used, they are not cumulative. 'Ignore' and 'Exclude' # are both accepted. # # Ignore: ignore1 # Exclude: ignore2, ignore3 # Ignore: ignore4 ignore5 # Exclude: ignore* # An Include directive specifies which keywords in a service will be # recorded. The syntax is the same as for the Exclude directive above. # It is _highly_ recommended to _not_ use Include directives unless # there is an overwhelming reason to do so. The default is to include # all non-excluded keywords in a service. # # Include: include1 # Include: include2, include3 # Include: include4 include5 # Include: include* # Expiration for events recorded in the database. This option will have no # effect if 'purge' is not set in the [main] configuration block. # # The format for the expiration string must be one that is recognized by # the GNU `date` utility. The most useful formats will involve negative # relative offsets against the current time; for example: # # 5 days ago # 2 hours ago # 15 minutes ago # 2 months ago # # See the commentary for the 'purge' directive for more information. If set # to 'None' or the empty string, no expirations will occur. # # Expiration: None