package require eventloggers
set id [eventlog::add db root source dest ?options?]
set loggerInfo [eventlog::listLoggers db]
eventlog::rm db id
eventlog::enable db id
eventlog::disable db id
eventlog::enableAll db
eventlog::disableAll db
eventlog::enableRecording db
eventlog::disableRecording db
set state [eventlog::isRecording db]
eventlog::start db
This package provides the database manipulations to set up and query event logger definitions.
An arbitrary number of event loggers of both types can be defined, enabled, disabled, and marked as critical. If a critical logger fails, a SHUTDOWN state transition is forced. In this sense, this package is dependent on the sequence package.
As you build the set of event loggers you will use, be careful to consider the bandwidth required to run them.
Event loggers have the following attributes:
A unique integer, or id is assigned to each logger as it is created. This id can be used to refer to that logger in the future.
Top level directory of the NSCLDAQ installation that contains the event logger that will be run. This determines the version of NSCLDAQ from which the event logger comes.
If the event logger is containerized (see options below), this path must be the correct path inside the running container.
The URL which defines the ring buffer from the logger logs data.
The host in which the event logger must run. It is assumed, that root is valid in that host and that the host is running the NSCLDAQ services.
The top level directory in which the loggers stores data. See TYPES OF LOGGERS below for more information about this.
Boolean value. If true, this logger is a partial logger. See TYPES OF LOGGERS below.
Boolean. If true, the logger is a critical component of the running DAQ system. If this logger fails, the manager will therefore force a SHUTDOWN transition.
Boolean that, if true, indicates the logger is enabled. If not enabled, a logger won't run to take data during a data taking run. If enabled it will.
Note that it is legal for critical loggers to be disabled.
THe name of the container the event logger will run in.
Destination directories, and data source URI's must be unique.
TYPES OF LOGGERS. The event logging subsystem recognizes two types of loggers, partial and complete. Partial loggers, like loggers in the NSCLDAQ multilogger package just log event files into a directory in a 'soup of files'. Event files are preceded with the date/time at which the logger started to ensure they are unique. For partial loggers, the destiniation is simply the directory in which these files are stored.
Full loggers, on the other hand, behave like the primary event logger in the NSCLDAQ ReadoutShell. The destination directory is the top level directory of the directory tree managed by the logger and its wrapper. The structure of this tree is shown below. The intent is to provide an experiment view and a per run view. The experiment view provides access to all event files while the per run view also provides access to associated run metadata stored in the experiment/current subdirectory when the run ended.
Figure 1. Full logger directory tree
(destiniation) +
+----> experiment+
| +---> current
| +---> run1
| +---> run2
... ...
+----> complete
In addition to the logger definitions, the configuration database includes a global enable flag which, if not boolean true ensures no logging is done. An entry also exists to start the appropriate loggers. This is normally done on a transition to BEGIN. If you implement PAUSE state machine semantics it is, therefore, very important to resume to a RESUME state and not the BEGIN state.
In all of the entry points described below, the
db parameter represents an
SQLite3 database connection command created using the
sqlite3 command.
Adds a new event logger definition to the database.
root is the NSCLDAQ installation
root directory who's event logger will be used.
source is the URI of the ringbuffer
from which the event data will be logged.
dest is the destination
directory that describes where data from
source will be logged.
The optional options parameter,
if supplied is a dict of options that overrides default
values. The keys in the dict we care about are:
The host in which the event logger will be run. Note that localhost will be the host in which the manager is run, not the host in which the definition was made.
If non zero, the logger is a partial loggers. See DESCRIPTION for information on what a partial logger is and, by contrast, what a complete logger is.
If non zero, if the logger fails or exits prior to the run attempting to transition out of BEGIN, the system will enforce a SHUTDOWN transition.
If nonzero the event logger will log the next run if global logging is enabled.
If a non-empty string, this specifies the name of a container defined in the containers package. The event logger, when run, will run in the container specified by this name.
Returns a list of dicts. Each dict describes one of the loggers that has been defined via eventlog::add. Each dict contains the following key/value pairs:
The integer id of the event logger. This is a unique id that can be used to refer to the logger.
Path to the root of the NSCLDAQ installation whose event logger will be run.
URI of the ringbuffer from which the event logger will accept data.
DNS name of the host in which the event logger will run.
If non zero, this is a partial logger.
The directory in which the data will be stored. See DESCRIPTION and the types of event loggers for the full meaning of this.
If non-zero, the event logger is considered critical and failure during a run will force a transition to SHUTDOWN.
If true the event logger is enabled and the eventlog::start will not start this logger.
Name of the container in which the logger will run if it is containerized. This will be an empty string if there is no container.
Id of the container that will run the logger. This will be an empty string if no container was specified.
Removes the event log definition associated with
the id id.
Enables the event logger identified by
id.
Disables the event logger identified by
id
Enables all event loggers.
Disables all event loggers.
Turns on the global recording flag. If this is off, no event loggers, regardless of their enabled state will record any data.
Turns off the global recording flag. If this is off, no event recording is done.
Returns the state of the global recording flag.
Starts all elligible event recorders. Event recorders that were started are expected to record a single run and then exit. The following pseudo code describes how the decision to start an event logger is made:
if global recording flag enabled
THEN
foreach event logger: logger
DO
if logger is enabled
THEN
start logger
ENDIF
END DO
ENDIF
From the psuedo code above you can see that a logger is started only if the global recording flag is enabled and the logger itself is enabled.