This document provides an introduction to the maintenance of the Physics E-log system for the logbooks maintained by the SLAC Controls department. These logbooks are:
All of the logbooks are hosted on the physics-elog machine. Some of the logbooks are in active production use (e.g. lclselog), some are inactive (e.g., pepelog), and some are for development/ testing (e.g., TESTelog).
Maintenance of the Physics E-log system requires sudo privilege on the physics-elog machine. After this privilege has been obtained from SCCS by requesting it through a form and obtaining permission from the physics-elog machine responsible engineer, one may logon as "root" to the physics-elog machine by:
The procedure to add a new Physics E-log system logbook is documented here: Physics E-log System Add New Logbook
Add New Keywords in Logbook -
Following was done for adding two new keywords in lclselog.
Keywords added -
Logon to physics-elog and become root.
cp -p conf.xml conf.xml.08092013
Edited conf.xml and added the keywords.
There is a print queue for each of the active logbooks that may be used for making a new E-log entry by printing a graphics file to the print queue. For the LCLS logbook (lclselog), this print queue is physics-lclslog. The general form for the print queue name for a logbook is "physics_[logbook name, minus the letter "e" before "log"].
A print request to a logbook print queue is directed to a UNIX named pipe. The named pipe for the LCLS logbook (lclselog) is /var/www/lclselog/lclslog and the pipe pathnames for the rest of the logbooks follow the same form (note the presence or absence of the letter "e" before "log"). A "lplisten" Bourne shell process runs for each process which listens for a new print request coming from the named pipe for the logbook. This process processes the graphics file sent via the print queue and creates a possibly converted file in the current day's data directory for the logbook. It also creates an associated E-log XML file in this data directory that refers to the (possibly converted) graphics file. This combination of an E-log XML file in the current day's data directory for the logbook and its referenced graphics file will cause the E-log web interface to display the newly created E-log entry along with a graphical image.
The "Physics E-log System Add New Logbook" document referenced previously contains details regarding how to create a "lplisten" process and a print queue for a logbook associated with a UNIX named pipe. The /etc/init.d/st.lplistenadm file may be used to stop or start the "lplisten" process for all of the logbooks. It invokes the Bourne shell script /var/www/elogbook/bin/lplistenadm for each of the logbooks to accomplish the requested stop or start of the "lplisten" process for a logbook. It runs the "lplisten" Bourne shell script for each logbook. The "lplisten" script for the LCLS logbook (lclselog) is /var/www/lclselog/lplisten. The "lplisten" script for each logbook is located in its corresponding logbook directory. Currently the contents of this script is the same for all of the logbooks but a logbook's "lplisten" script may be customized for the logbook's needs. The "lplisten" script for each logbook details the processing for each type of grapics file and the creation of print queue E-log XML entry and associated (possibly converted) graphics file in the current day's data directory for the logbook.
To debug the print queue mechanism for a logbook, it is first useful to determine whether the lplisten process and the printer pipe work correctly. To do this for the LCLS logbook (lclselog) enter the following command under the bash shell:
Next determine whether the full E-log printer queue chain works correctly by printing a text message to the print queue for the logbook. To do this for the LCLS logbook (lclselog):
Finally, one may also test whether a graphics file (e.g., tiger.ps) can be printed using the global print queue name. To do this for the LCLS logbook (lclselog) issue the following command from a flora machine, for example:
Data for a logbook is stored in subdirectories of a directory having the form: /var/www/[logbook_name]/data. For instance, data for the logbook lclselog is stored in subdirectories of the directory /var/www/lclelog/data. The immediate subdirectory of this directory indicates the year for the data: e.g., /var/www/lclselog/data/2010. The immediate subdirectory of a year data directory indicates the week number from the beginning of the year: e.g., /var/www/lclselog/data/2010/15 contains data for week 15 for 2010. The next subdirectory indicates a day, usually of the form "[day.month]": e.g., /var/www/lclselog/data/2010/15/15.04 indicates the day data directory in the lclselog logbook for April 15, 2010 (April is the 4th month of the year, which is the "04" part of the day/month subdirectory "15.04").
Within a day data directory for a logbook, such as /var/www/lclselog/data/2010/15/15.04, are the files for the E-log entries made that day. Each E-log entry has an associated XML file with a file name that indicates the timestamp when the entry was made. For example, file "2010-04-15T16:08:00-01.xml" indicates an E-log entry that was made April 15, 2010 at 16:08:00. An E-log XML file contains a subset of the possible E-log XML tags described in the "XML Tags Description" section of this document. It may contain references to the associated graphics files for the entry. For E-log entries made using the print queue mechanism, this typically includes a PostScript file referenced by the "link" tag (e.g., 2010-04-15T16:08:00-00.ps) and a JPG file created by converting this PostScript file to JPG format by the logbook's lplisten script, referenced by the "file" tag (e.g., 2010-04-15T16:08:00-00.jpg).
There also may be "backup" E-log XML files within a day data directory for a logbook with the extension ".xml.BAK". These files indicate the previous version of the corresponding E-log XML file with the extension ".xml" and are created when an E-log entry is edited using the E-log web interface.
In addition, in every day data directory there is a "init.xml" file that is created immediately after the day data directory is created. It contains metadata about the day data directory and the name of the previous day directory (unless it is the first day data directory for a logbook). It is edited with the name of the next day directory after the day data directory for the next day is created. The "prev_shift" XML tag (indicating the previous day directory) and "next_shift" XML tag (indicating the next day directory) in the "init.xml" file for the day data directories are used for navigating between day data directories on the E-log web interface using the green left arrow and right arrow icons at the top of a logbook's main E-log web page.
High-level Applications group Java applications have a "-> Log Book..." button in the applications GUI template. Selecting this button causes the instantiation of a new LogbookEntry class described by the source code located in the LCLS CVS path physics/Save2Logbook/src/edu/stanford/slac/Save2Logbook/LogbookEntry.java. A constructor for this class brings up a dialog box allowing the user to specify the information needed to create a Physics E-log entry. Upon selecting "Save Entry" in this dialog box, any graphics file associated with the new Physics E-log entry to be created is copied to $PHYSICS_DATA/logbook/data and an E-log XML file is created in this directory.
The Perl script lclselog_move.pl runs on the lcls-daemon2 machine to move E-log entry files from $PHYSICS_DATA/logbook/data to the physics-elog machine lclselog logbook current day's data directory, a subdirectory of /var/www/lclselog/data. This script runs continuously, sleeping (e.g., 8 seconds) between loops. For each loop it looks for new XML files in the $PHYSICS_DATA/logbook/data staging area. For each XML file found up to a maximum number (e.g., 5) the script: (1) validity checks the XML format to make sure it is a valid Physics E-log entry XML format file, (2) validity checks any graphics file links contained within the XML file, (3) copies the XML file and any associated graphics file to the lclselog logbook current day's data directory on the physics-elog machine, (4) copies the XML file and any associated graphics file to the backup directory on the physics-elog machine, and (5) removes the XML file and any associated graphics file from $PHYSICS_DATA/logbook/data. The lclselog_move.pl script logs conditions it encounters during processing to the /u1/lcls/physics/logbook/log/lclselog_move.log file, which is very useful for investigation of problems that may occur during processing.
To switch to the new search mechanism and new tree for a logbook that currently uses the old search mechanism, perform the following steps (which will also put the logbook under control of the elogbookManager):
For the new E-log search interface, "All Words" is an "AND" and "Any Word" is an "OR".
The search date picker does not work using Internet Explorer version 7 but does work using Firefox. IE users can enter dates by typing.
Logbooks that use the new search mechanism (all logbooks in active use) have navigation trees that are controlled by the elogbookManager. This section describes how to fix navigation tree problems for logbooks that are controlled by the elogbookManager.
Note - As per Raimund, for new elogbook manager no cronjob is needed.
All cronjob(s) are run by the elogbookManager - so NO cronjob(s) for elogbooks managed by the elogbookManager.
A "shift creation" script for each logbook runs right after midnight. At SLAC, "shift creation" actually means "day creation" since SLAC logbooks create new data directories at the start of a new day and not at the start of each new shift. For most logbooks, this script is the bin/crontjob.sh script for the logbook (e.g., /var/www/e164elog/bin/cronjob.sh). For the LCLS logbook (lclselog) this script is /var/www/lclselog/bin/chg_owner.sh, which not only performs the task of creating a new day data directory and creating/modifying directory init.xml files as described previously in the "Logbook Data Directory" section but also changes the ownership of the new day directory from "root" to "laci" so that the mechanism described in the "High-Level Applications Print to E-log Mechanism" section will work correctly.
The search index update for each logbook is performed every 4 hours beginning right after midnight. The bin/search-index script for a logbook is run with an "update" parameter (e.g., /var/www/lclselog/bin/search-index update).
There are two approaches to scheduling the day creation script and the search index update. For those logbooks that are under control of the elogbookManager, the script scheduling can be specified in the logbook jsp/conf.xml file and controlled by the elogbookManager web interface. See the last part of the /var/www/lclselog/jsp/conf.xml file to see how the scheduling of chg.owner.sh and "search-index update" is specified. To see the jobs controlled by the elogbookManager:
The second approach to scheduling the day creation script and the search index update is via the root crontab facility. To see examples of logbooks that use this approach, issue the command "crontab -l | more" as root on the physics-elog machine.
The bin/search-index script for a logbook accepts four parameters: start, add, remove, and update. It caused the running of the Java JVM using the class file resulting from the compilation of /var/www/elogbook/lucene_search/IndexFiles.java. For each of the four parameters, an argument is passed to the IndexFiles class that tells it where the index file for the logbook is located (e.g., /var/www/lclselog/work/index).
To recreate the search index for a logbook (in the example below, for the lclselog logbook):
For logbooks using the old search mechanism, the search web page (reached by selecting "Logbook Search" from the main E-log logbook web page) contains "From:" and "To:" year pull-down menus that do not contain new year numbers unless configuration files are modified. For instance, if a new year (e.g., 2010) is not in the pull-down menu:
As described elsewhere in this document, to logon to the elogbookManager enter the URL "http://physics-elog.slac.stanford.edu/elogbookManager" and enter the password obtained from the E-log administrator. Expand "+ Extra" to get information about the overall status of aspects of the elogbookManager (then select the "?" icon next to the "Log", "Cronjobs", or "Trees" labels).
The "?" icon provides additional information about the items next to it wherever it appears in the elogbookManager web interface.
The elogbookManager is a Tomcat worker process specified in the Apache configuration file, /etc/httpd/conf/httpd.conf. The elogbookManager code is located in and under the directory /usr/tomcat/webapps/elogbookManager. This software controls logbooks that have jsp/conf.xml files that contain a "tree_servlet" XML tag. However, for the elogbookManager to control a logbook whose jsp/conf.xml has been modified to add a "tree_servlet" XML tag, the Tomcat web server needs to be restarted.
In the data directory tree at the left in each logbook E-log web interface, a red book icon identifies data directories that contain at least on E-log entry. These were not appearing for the lclselog logbook after Raimund Kammering made modifications on March 26, 2010 to switch to a new search mechanism and new tree. To fix this Raimund created or modified the following files in /var/www/elogbook/xsl on April 12, 2010:
Raimund's explanation of the changes in an email on April 12, 2010:
For the marking of "filled folder" - I added a few missing lines to the XSL files so that starting from now any folder in which an entry has been "touched" using "edit this entry" will be marked as filled - meaning "pure" printed entries and copied stuff still not marks entries as filled.
To change the maximum length of the E-log entry author and title strings modify the file /var/www/elogbook/xsl/elog-fileform.xsl. Search for the author and title sections, replacing the "maxlength" values to the values you desire ("size" is just the visible area).
When creating a new logbook, by default "doocs" icon and GIF files are used for the logbook web interface, located in the directory /var/www/[logbook_name]/images (e.g., /var/www/lclselog/images). The web interface uses the files Icon.ico and logo.gif in this directory. The default versions of these files be replaced by icon and GIF files identifying the project associated with the logbook, giving the logbook web interface a more customized and identifable look.
The Java plug-in may not get loaded in a Physics E-log browser at an OPI in the MCC Control Room if too many Matlab applications are running on the OPI. If this problem occurs, the person using the OPI must kill the Matlab applications so that the Java plug-in has enough system resources to load in the Physics E-log browser.
NOTE: This problem only applies to logbooks that have an old version of the web interface (without the new search mechanism and new tree). The logbooks that have the new web inteface do not need a Java plug-in on the client.
A problem occurred on Jan. 12, 2009 at 02:43 with the lclselog logbook which caused the web interface to show the message "HTTP Status 500" instead of the logbook information. Restarting the Tomcat web server fixed the problem.
The tomcat.log file was examined in /usr/tomcat/log on the physics-elog machine. The log file showed entries indicating "Too many open files" about the time the problem was first reported. The error seems to come from the Linux operating systems indicating there are too many open files or socket descriptors. The maximum number of open file descriptors per process on the physics-elog machine is 1024.
The cause of this problem is unknown at this time. The crontab facility for the "root" account is used to run the /var/www/elogbook/bin/tomcat_open_files_monitor.pl script every hour to monitor the current number of files opened by the Tomcat web server to try to inform systems group members before this number exceeds the system limit of 1024 open files per process. A log file is appended to each time the script is run (/var/www/elogbook/log/tomcat_open_files_monitor.log). Email is sent to Ken Brobeck and Bob Hall every morning at 8 AM indicating the number and names of the files opened by the Tomcat web server and whenever this number exceeds 500.
The Tomcat web server may be stopped and then restarted from the "root" account as follows:
The "mail to experts" feature did not initially function because the Apache Tomcat servlet that is used to write a new E-log entry and optionally send mail assumed that a SMTP mail server was available on the local host (i.e., physics-elog). Since there is no SMTP mail server on physics-elog this servlet must be directed to send email to the SLAC mail server, smtp.slac.stanford.edu, as follows:
The /var/www directory and subdirectories are backed up daily. If there is a need to restore lost files, refer to the following SCCS document: SCCS Backup/Restore
The creation or modification of an E-log entry by cutting and pasting from applications such as Microsoft Word can introduce non-ASCII characters in the entry's XML file and cause previous entries in the day's data directory for the associated logbook not to be displayed. The most common occurance of this problem is the creation of a new entry in a logbook for the current day that contains non-ASCII characters. This is fixed by the root cronjob /var/www/elogbook/bin/remove-non-ascii-characters-from-xml-files, which runs every three minutes and removes non-ASCII characters for all XML files created in the last 12 minutes for each logbook. This minimizes the amount of time a new E-log entry's XML file containing non-ASCII characters cause previous entries for the current day not to be displayed for the associated logbook.
In rare cases this problem can be caused by modifying an existing E-log entry in a logbook's current day data directory or an entry in a previous day's data directory. When this condition is reported the script /var/www/elogbook/bin/clean_dir_xml_files.bash may be run to remove non-ASCII characters from all XML files for a specified logbook and day. As usual with the Physics E-log system, you must run it after logging in as yourself and using "sudo" to run as root. This script takes two arguments: (1) the name of the logbook (e.g., lclselog), and (2) the date for the data directory where the problem occurred in dd-mmm-yyyy format (e.g., 06-Apr-2015). For example:
Miscellaneous problems –
Problem - Cannot see files from a folder.
There was lot of data entered today but we cannot see that !
This effect is ALWAYS due to not well formed XML data in one of the entries within the shift 3. Finding this entry is (unfortunately) difficult
The corrupt entry is: 2013-01-08T17:06:49-00.xml
There is a unquoted ampersand in the entry. Looks like a matlab script did this entry. If it would be entered via web browser or printed using the virtual logbook printer queue, this can not happen! So the only way this could have happened is that the matlab script directly wrote the entry to the elogbook data directory - might that be true? If so we/you must ensure that instead of:
& one must write & And the same is true for the following characters:
Problem - Search functionality not working for lclselog.
Get following error while trying search a word for lclselog –
ERROR opening the Index - contact sysadmin!
Error message: /a/surrey04b/vol/vol1/g.cd_physicselog2/lclselog/work/index/_47g2.fnm (No such file or directory)
# cd /var/www/lclselog/work
# mv index index.old
# mkdir index
# cd /var/www/lclselog/bin
# search-index start
The "search-index start" process will take lot of time. Ones that is completed, issue following commands -
# /etc/init.d/st.tomcat stop
# /etc/init.d/st.tomcat start
Author: Bob Hall 14-Apr-2010
Modified by: Bob Hall 21-Apr-2010, Added section for restoring files.
Modified by: Bob Hall 22-Apr-2010, Added new information regarding the elogbookManager and the new search mechanism procedure.
Modified by: Bob Hall 11-Nov-2010, Added new section for the mail to experts feature.
Modified by: Bob Hall 27-Jan-2012, Added new section for fixing navigation tree problems.
Modified by: Bob Hall 07-Apr-2015, Added new section for fixing directory display problem caused by non-ASCII characters in XML files.