BNMR: Shift Monitor
Links
Introduction
The BNMR shift monitor system consists of two perlscripts in directory /home/bnmr/online/perl :
- monitor.pl
- cycle_monitor_logfiles.pl
both of which are normally run as cron jobs. They are run as user bnmr, and access the required information from both the bnmr and bnqr ODBs.
The Shift Monitor program
monitor.pl keeps a running total of how much usable beam time (in minutes) each TRIUMF experimental group has had access to, while running as experiment bnmr or bnqr (or both). It reads the proton current from EPICS once per minute.
The information is stored in shift files in the directory
/isdaq/data1/bnmr/mon/<year>/. This is also the location of the log files used to store messages.
How it works
The perlscript /home/bnmr/online/perl/monitor.pl is run on isdaq01 (i.e. the midas host for bnmr and bnqr experiments) as a cron job (except for testing). Its output is written to a log file. It is run only as user bnmr, which has permission to access the EPICS variables needed.
The script determines which TRIUMF experimental group is running by reading the experiment number from the ODB parameter /Experiment/Edit on start/experiment number on both experiments. Access to the bnqr ODB is done using odbedit, i.e.
| for bnmr | odbedit -c 'ls "/Experiment/Edit on start/experiment number" ' |
| for bnqr | odbedit -h isdaq01:1177 -e bnqr -c 'ls "/Experiment/Edit on start/experiment number" ' |
The perlscript
monitor.pl reads the proton current from EPICS (via caget "CCS2ISAC:BL2ACURRENT").
- If it is below the threshold value (supplied as the first input parameter to monitor.pl), it exits.
- Otherwise it reads from the EPICS switches which experiment(s) is/are enabled:
- bnmr in single channel mode, or
- bnqr in single channel mode,or
- both experiments (in dual channel mode)
- It reads the experiment number from the enabled experiment(s). The experiment number must be > 0, otherwise no beam time will be allocated.
- The program determines the name of the shift file by date and by 12-hour shift (AM/PM).
- If no file of that filename exists, it is created and a line written for each different experiment number, and each running experiment assigned 1 minute of running time.
- If bnmr and bnqr are both running with the same experiment number, only one line will be created with bnmr and bnqr experiments each given 1 minute accumulated time.
- If there is an existing file, the program looks for a line with the experiment number. If it finds one, the accumulated time is incremented for the appropriate experiment. All other lines are copied and an updated file is written. If no line exists for this experiment number, a new line will be written.
- If test mode is enabled (see #Input Parameters) an entry to the shift file written in test mode will be followed by an asterisk (see example).
The script cycle_monitor_logfiles.pl cycles the logfiles to save disk space. After 5 days, the logfile information is deleted.
- Note
- the shift files are never deleted unless by the user.
Log files
The current log file is /isdaq/data1/bnmr/mon/<year>/monitor.log
When running monitor.pl as a cron job, the output of the program can only be found in the log file, since printing to the screen must be suppressed (to prevent excessive email).
Cycling the log files
A second cron job cycle_monitor_logfiles.pl cycles the log files, so that a new monitor.log file is started every 24 hours. Five days worth of logs are retained in files monitor.log_1 to monitor.log_5 where monitor.log_5 is the oldest. Each day the cron job deletes monitor.log_5, renames monitor.log_n to monitor.log_n+1 and renames monitor.log to monitor.log_1. This is done to limit the disk space taken up by the log files.
cycle_monitor_logfiles.pl takes one parameter, which when set to 1 suppresses printing to the screen. Output from
cycle_monitor_logfiles.pl can be found in
cycle_files.log. A version of this file is created each time the script runs.
Shift files
Shift files are located in the directory /isdaq/data1/bnmr/mon/<year>/ and filenames are of the form
24Jul2014_AM.txt, 24Jul2014_PM.txt. The AM shift starts at 8.30am, the PM shift at 8:30pm.
The format of the shift files is e.g.
# Shift Monitor File first opened at Thu Jul 24 13:52:21 2014 # Threshold(uA) ExptNum BNMR(min) BNQR(min) Time line written Testing 10.000 00001508 0080 0036 Thu Jul 24 15:50:01 2014 * 10.000 00001412 0035 0021 Thu Jul 24 15:49:02 2014 *
The * under "Testing" indicates test mode (see #How it works).
Input Parameters
| Input Parameter | Explanation | |
|---|---|---|
| 1 | Proton Current Threshold (uA) | User selected value. If proton current is less than this value, program will exit without updating shift file. |
| 2 | Suppress printing | Must be TRUE if running as a cron job |
| 3 | Test Mode | Set TRUE for testing if EPICS switches are set to "off" |
| 4 | BNMR enabled | In Test Mode, set TRUE to enable BNMR regardless of EPICS switch |
| 5 | BNQR enabled | In Test Mode, set TRUE to enable BNQR regardless of EPICS switch |
Running the program by hand
The perlscript monitor.pl can be run by hand to check its operation. However, each time it is run, a minute will be added to the current experiment(s) in the shift files.
- Therefore, it should not be run by hand during the beam period if the cron job is running.
To run the program, as user bnmr, in an xterm type e.g.
/home/bnmr/vmic_online/perl/monitor.pl 15
Printing to the screen ( input parameter 2) need not be suppressed when running by hand.
The program can also be run in test mode, e.g
/home/bnmr/vmic_online/perl/monitor.pl 0 0 1 0 1
This would enable the bnqr experiment regardless of the state of the proton current and the EPICS switches (see #Input Parameters).
The program cycle_monitor_logfiles.pl can also be run by hand at any time. Printing messages to the screen will not be suppressed if run as follows:
/home/bnmr/vmic_online/perl/cycle_monitor_logfiles.pl
Running the cron job
As user bnmr, in an xterm type
$ crontab -l
to list the crontab file, or to edit it
$ crontab -e
The crontab file will be displayed as follows:
# MAILTO=GM <gmorris@triumf.ca> SHELL=/bin/csh # cron parameters : # minute hour dayofmonth month dayofweek command # # cycle_monitor_logfiles.pl : cycle the logfiles monitor.log # #: output from this script in cycle_files.log # run like this as cron job (argument=1 suppresses printing to screen) 30 8,20 * * * /home/bnmr/vmic_online/perl/cycle_monitor_logfiles.pl 1 # # # monitor.pl parameters: proton_current(uA) noprint testing bnmr_running bnqr_running # # run like this for TESTING cron job when epics switches are not set correctly and proton I is zero: # #use the odb to change the experiment numbers under "/experiment/edit on start/" #* * * * * /home/bnmr/vmic_online/perl/monitor.pl 0 1 1 1 1 # # run like this normally (change "10" to required proton current threshold) : # Uncomment to turn on logging # this editor is emacs: use C-x C-c y to save changes and exit # typical BL2A current is about 40 \mu A; set a threshold somewhat less. # * * * * * /home/bnmr/vmic_online/perl/monitor.pl 35 1
The example above shows
- the script cycle_monitor_logfiles.pl run twice per day (cron parameters are minute=30 hour=8,20 i.e. 8.30am and pm)
- the shift program monitor.pl being run as a cron job every minute (cron parameters all = *)
with parameters
- minimum proton current 10
- suppress printing TRUE
Printing must be suppressed when running as a cron job, otherwise the MAILTO recipient will get long email messages every minute. If the last line is commented out, the cron job will not be running the monitor program (see stopping the cron job).
Stopping the cron job
As user bnmr, in an xterm type
$ crontab -e
which will display the crontab file to be edited (see above). Comment out the two lines that starts the perlscripts, i.e.
# ...........
#30 20 * * * /home/bnmr/vmic_online/perl/cycle_monitor_logfiles.pl 1
# ...........
# * * * * * /home/bnmr/vmic_online/perl/monitor.pl 10 1
and exit from the editor.