Installation
Much of the Bookie code is in an experimental state. Don't deploy it to production environments yet!
To install the Bookie utilities, run the command gem install bookie_accounting.
You must have GCC and the development packages for Ruby on your system.
Also install the correct ActiveRecord connection adapter for your database.
The omibus-bookie_accounting project contains an Omnibus project that can be used to create a full-stack installation package for many systems. See its page for more details.
Ownership and permissions can be adjusted on the Bookie executables to prevent unauthorized access, but doing so is not strictly necessary if the Bookie configuration file is only readable by root or another privileged user. By default, the full-stack installer makes the configuration file readable only to the root user.
Before configuring Bookie, you should have an empty database set up for Bookie to use. You should also have the correct ActiveRecord database adapter installed.
For example, if you are using MySQL and you installed Bookie as a gem, you should run the following command:
gem install activerecord-mysql2-adapter
If the installation fails, you may need to install the header files for your database.
When using the full-stack installer, the MySQL ActiveRecord adapter is already included.
The next step is to create the configuration file for Bookie. The format is described on the Configuration format page. The default location of the file is /etc/bookie/config.json; you should normally create it there.
{
"Database type" : "mysql2",
"Database" : "bookie",
"Server" : "localhost",
"Port" : 8080,
"Username" : "root",
"Password" : "test",
"Hostname" : "localhost",
"System type" : "torque_cluster",
"Cores" : 4,
"Memory" : 1000000000
}If the database is empty, execute the command bookie-migrate to perform the initial database setup.
You need to create an entry for the system in the database before you can record any of its jobs. See the page on managing systems for more details.
Bookie is designed to work with a scheduling system such as cron. There are two main steps to follow when setting up the cron jobs:
Bookie is not designed to handle log files that the system is still updating, such as the default Linux process accounting file. To handle these files, the data must be split off to a new file before processing. The easiest method of accompishing this is to use logrotate.
TODO: update examples to note concurrency issues
If you are using logrotate on a standalone CentOS machine, the rotation configuration will probably look something like this:
/var/account/pacct {
daily
rotate 5
compress
#Bookie can't yet read compressed files, so we need
#at least one day's worth of uncompressed data.
delaycompress
create 0600 root root
#Make the suffix a date (YYYYMMDD) rather than a number:
dateext
dateformat %Y%m%d
prerotate
service psacct stop
endscript
postrotate
service psacct start
endscript
}
The script for Ubuntu (and probably other Debian-based systems) is similar, but the file to be rotated is /var/log/account/pacct, and the process accounting service is just named acct.
On systems such as TORQUE, where the logs are already split by day, this extra splitting step is unnecessary as long as you never send data from the current day's log (to which TORQUE is still writing entries).
Schedule bookie-send
A cron script should be set up to run the bookie-send command at some point after the log rotation is over, passing the name of the most recently rotated file.
Here's an example of a working crontab entry (assuming that logrotate uses the naming convention "pacctYYYYMMDD" and is always started at or after 12:00 AM and finished by 1:00 AM):
0 1 * * * bookie-send pacct`date \%Y\%m\%d`