wcglog

wcglog

Logfile

This program is used to browse a logfile that is produced by [wcgresults]. The most common way of producing that logfile is through crontab, using something like wcgresults -daf LOGFILE (where LOGFILE is the name that you specify for the logfile, e.g. "WCG/WCG.log").

After configuring wcgresults, see [Configuration], having specified the name of your account on World Community Grid and your verificationcode, you will be able to save the statistical data from your results, using wcgresults, into the logfile.

How does it look?
Using a condensed view (taking less columns than the default), here is an example:

Fig.: wcglog -w -l 10

Location

If you put the logfile in a common place, i.e. predefined by wcglog, then the program will automatically locate the logfile by itself. By default, the program uses a number of directories and a number of filenames to search when trying to locate the logfile.
By default, the directories that wcglog uses to locate the logfile are all relative to your homedirectory. They are: .BOINC, BOINC, WCG, wcg, www and tmp.
By default, the filenames that wcglog uses to find the logfile start with WCG and wcg and end with .log.

You can also produce a temporary logfile (using wcgresults) and browse it using wcglog. Simply specify its filename — just like you did with [wcgresults] (see above) — to wcglog, e.g.: wcglog LOGFILE.

The output of wcglog can also be viewed, page by page, by piping it to less -r.

When you think that your logfile has grown too large to process (e.g. by [wcgresults] or by [wcglog] itself), you could rename it. Let's suppose that your logfile is named "WCG.log". If you would move it to "WCG.log.begin", then wcglog will still understand that new location, since wcglog also knows about that name, because it is denoted as the 'historical beginning' of the logfile. It's the name of the current logfile plus the suffix .begin, so - in fact - wcglog knows about two logfiles. Generally speaking, if the name of the logfile is LOGFILE symbolically, then LOGFILE.begin denotes a second logfile, the 'historical beginning'. Note: if LOGFILE does not exist, then wcglog will not find LOGFILE.begin either.

---

Options

Without options, wcglog will show the data from all entries in the logfile.

Option -/

This will just show the location of the logfile, if it can be found, else it will produce an empty line.

Option -0

That's a zero. By default, wcglog skips any entries that received 0 credit. With this option, entries that received 0 credit can also be shown. These entries will be shown in standoutmode (unless you specify option -A).
By specifying this option twice, only entries that received 0 credit will be shown.

Option -1

With this option, only a grand total of all entries will be shown. Example:

Fig. 1: wcglog -1 LOGFILE

Option -2

With this option, only entries will be shown, without a grand total (and without headerlines). This option is almost the reverse of option -1.

Option -A

This is used to omit ANSI-escape-sequences in the output on your screen: the word Credit will not be underlined, the words Claimed and Granted will not be in standoutmode and the same goes for any entries that received 0 credit.
Adding another -A will add some formattingcodes to the output for making it easy to post it on the WCG-forum.

Option -c

This option takes an argument that controls which items (columns in the logfile) - and in what order - to show. The default is to show the items AppName, CpuTime, ElapsedTime, ClaimedCredit, GrantedCredit, ModTime, Exit, Outcome, SentTime, ReceivedTime, DeviceName and Name (i.e. TaskName), in that order.
Each available item (column) of an entry in the logfile has two corresponding values (a letter or a digit) to be used with option -c; the correlation between value and item is shown in the following table:

1st	2nd	item
0	a	AppName
1	c	ClaimedCredit
2	u	CpuTime
3	e	ElapsedTime
4	x	ExitStatus
5	g	GrantedCredit
6	y	DeviceId
7	z	DeviceName
8	m	ModTime
9	w	WorkunitId
A	i	ResultId
B	n	Name
C	o	Outcome
D	r	ReceivedTime
E	d	ReportDeadline
F	t	SentTime
G	s	ServerState
H	v	ValidateState
I	f	FileDeleteState

So, to show the items ClaimedCredit and GrantedCredit in that order, there are four possibilities for the argument of option -c: '15', '1g', 'c5' and 'cg'.
The first column in the table above, here named "1st", has a logical order, as it sums up the items by their values 0..9 and A..I. The second column, "2nd", has a more meaningful fashion as some of the values (note that all are lowercase letters) match the first letter of an item.
NB: An alternative for the item 'n' (TaskName) is the letter 'N'.

Specifying '?' as argument will list all possible, recognized values by this option.

Option -C

This option will show the numerical value of the order of each column in the logfile. The name of the column in the logfile is shown in the first column, the numerical value of the order of its column in the logfile is shown in the second column. Example: the first column in the logfile contains the AppName, so the corresponding value is 1, and the twelfth column in the logfile contains the (Task)Name, so the corresponding value is 12.
With this knowledge it's possible to use the shellcommand cut, e.g. to count the number of logged results per device (by DeviceName, its column in the logfile is 8): cut -f 8 LOGFILE | sort | uniq -c

In addition, both the third and the fourth column contain one alphanumeric character that corresponds to a certain column in the logfile, indicated by the name in the first column, that you can use with option -c of wcglog. Example: to list all TaskNames in the logfile, each together with their own DeviceName, you could pick the letters n and z, as shown in the output of wcglog -C (the letter 'n' in column 3 corresponds to "TaskName" in column 1, while the letter 'z' in column 3 corresponds to "DeviceName" in column 1), and apply them - in this case in reverse order - to option -c of wcglog like this: wcglog -c zn. The first few lines of the output would then look something like this:

DeviceName       Name
laptop           OPN1_0109712_00295_1
desktop          ARP1_0014553_127_0
laptop           MCM1_0191384_3201_1

Option -e

This option takes an expression as argument that will show all entries that match the expression, e.g. wcglog -e ^mcm1 will match all entries where column 1 (the AppName) begins with the string 'mcm1'.

Option -E

Same as option -e, except that the output will consist of unformatted entries only. In this way it is possible to pipe the output into another instance of wcglog (by using the option -t), e.g. wcglog -E ^mcm1 | wcglog -t -l 25 (which will show the last 25 entries belonging to AppName 'mcm1').

Option -f

With this option it is possible to 'follow' (like the shellcommand tail -f) a logfile that was created by wcgresults -df. By using wcglog -fyou will also be able to suspend the output of wcglog (by typing ctrl-Z), then do something else on the commandline, and after a while, as soon as the logfile has grown, typing fg again to bring wcglog back on the foreground, showing any entries that have been appended to the logfile.

Option -F

This option takes an argument that specifies the pathname of a logfile that was created by wcgresults -dF. It will use sqlite3 to query the logfile. You cannot use both the option -F and the option -f simultaneously.
If you want to query the logfile yourself, you could use sqlite3 LOGFILE 'select * from wcgresults', where LOGFILE is the name of the logfile. This will produce a long line - with the '|'-symbol as the default column separator - like this:
scc1|0.0|0.0|0.0|202|0.0|999|pc|1684608153|29808|51296|SCC1_0004175_MyoD1-C_25069_1|3|2023-05-19T17:49:47|2023-05-25T15:29:28|2023-05-19T15:29:28|5|2|2
If you want to have each '|'-symbol changed into a tab-character (often denoted as \t in C and many other programming languages), you could use sqlite3 LOGFILE 'select * from wcgresults' | tr '|' '\t' (the last tr part will translate each '|'-symbol into a tab-character); wcglog would then be able to understand the output of that operation and you could directly pipe the output into wcglog -t.

Option -h

This is the help option. It shows which options are available (with concise explanations) and how to use them. (It will also show the version of this program, since option -V is already in use for something else.)

Option -H

This option will make wcglog show only one line: the header that usually appears above (and below) all selected entries from the logfile. By specifying the option -H twice, one line will be inserted with the alphanumerical representations of the columns.

Option -i

This option will cause executing wcgresults with the option -i and its same argument that was specified here. See [wcgresults] for more information.
Note: this will only work if the program wcgresults can be executed, because the option with its argument will be passed to that program.
However, if the program wcgresults exists by an alternative name, you could configure the variable WCGRESULTS and let it point to that alternative name.

Option -I

This option (using a capital I, pronounced 'eye' or 'i') will also search the so called 'historical beginning' of the logfile, if it exists. It concerns a separate file. Specifying option -I means that wcglog will first search the 'historical beginning' of the logfile and then the current logfile. The name of the file containing the 'historical beginning' of the logfile is the name of the current logfile with ".begin" appended. Explanation: if the name of the current logfile would be LOGFILE symbolically, then LOGFILE.begin denotes another valid name that will be understood by wcglog. So there will be two valid names for the logfile, LOGFILE and LOGFILE.begin symbolically, and the latter is supposed to be the 'historical beginning' of the logfile.

Option -l

This option (ell) takes a number as argument, representing the number of entries that were most recently appended to the logfile. Example: wcglog -l 25 will show the last 25 lines that were added.

Option -L

Same as option -l (ell), except that the output will consist of unformatted entries only. In this way it is possible to pipe the output into another instance of wcglog (by using the option -t), e.g. wcglog -L 25 | wcglog -t -e ^mcm1 (which will show all matches with AppName 'mcm1' in the last 25 entries).

Option -o

This option takes an argument that specifies which items (columns in the logfile) to omit when showing entries from the logfile. This option can be useful when specifying the options -w and/or -W. It can also be used when you don't specify the option -c. The table underneath option -c shows which items you can specify with option -o. As an example, specifying -o zm or -o 78 would omit the items DeviceName and ModTime.

Option -t

This option is used to tell the program that it should read raw database entries from standard input, as generated by e.g. wcglog -E, wcglog -L or wcglog -V. Example: for app in mcm1 opn1; do echo $app:; wcglog -E ^$app | wcglog -t -l 25; done (which will show the last 25 entries for each specified app, in this case 'mcm1' and 'opn1').

Option -u

If you have other accounts, this option lets you specify which other account to use. Probably best practice is to number other accounts 1, 2, 3, etc.
If the name of the logfile can be found through the symbolical pathname LOGDIR/PREFIX.log, then specifying account 1 would mean that the symbolical pathname would change into LOGDIR/PREFIX-u1.log (with -u1 inserted between PREFIX and suffix ".log").

Option -U

This option lets you update the program. The argument specifies the file that is the new version. In this way your configuration inside the program itself will be kept intact.

Option -v

This option takes an expression as argument that will show all entries that do not match the expression, e.g. wcglog -e ^mcm1 will match all entries where column 1 (the AppName) doesn't begin with the string 'mcm1'.

Option -V

Same as option -v, except that the output will consist of unformatted entries only. In this way it is possible to pipe the output into another instance of wcglog (by using the option -t), e.g. wcglog -V ^mcm1 | wcglog -t -l 25 (which will show the last 25 entries not belonging to AppName 'mcm1').

Option -w

This option is used to show fewer columns (on a smaller screen) than the default (see option -c). The items (columns) are CpuTime, ElapsedTime, ClaimedCredit, GrantedCredit, ReceivedTime, DeviceName and Name (i.e. TaskName), in that order.

Option -W

This option is used to show the extra column WorkunitId (i.e. one more than the default, see option -c). This column is placed before the column Name (i.e. TaskName).

Option -@

This option will hide the item DeviceName, it will be omitted in the output.

Environment

WCGLOGFILE - The location of the logfile. If this shellvariable is detected in the environment and its value is non-empty, wcglog will use it as the location of the logfile.
WCGLOG_FMT - A replacement for option -c. If this shellvariable is detected in the environment and its value is non-empty, wcglog will use it as the value for option -c. It can then only be overridden by actually using option -c.