[[ coldCLOUD ]]
Table of Contents

# 2008.10 Timelog

A piece of software to record the time of the beginning and the end of a user defined event.

Timelog was originally written for registering the time spend on work. The idea was to have the computer run Timelog on startup and shutdown - i.e. the beginning and end of the working day.

## Description

Timelog is a script that simply writes the time of the beginning and end of a user defined event to a plain text file - i.e. a Timelog file.

Initially Timelog looks at the exit status of a user defined script to decide whether to write to the file right away or to wait and try again later. The name of the Timelog file is returned by the script along with an exit status. On a successful exit Timelog writes a time entry to the Timelog file. Whether it is the time of the beginning or end is defined in the main Timelog call.

The time is written in an ISO-8601-type format (ex. 2008-12-31T12:00:00+0200) followed by either ON or OFF. There is only one Timelog entry per line in the Timelog file.

## Interpreter

Timelog is written in perl (version 5.8.8) and utilise the following modules,

• Getopt::Long (version 2.35)
• POSIX (version 1.09)
• Date::Manip (version 5.54)

Timelog is only tested with the above stated versions - however, it may very well run fine with other versions.

## Documentation

The documentation for Timelog is seen by running perldoc on Timelog itself,

perldoc timelog

A compact help menu is given by running,

./timelog -h

### Arguments

A more detailed description of the important arguments.

#### --check

Check the consistency of the file. Now, Timelog makes sure the last time entry is not newer than the entry to be written. Also, it makes sure the last entry is not of the same type (ON or OFF) as the one to be written.

#### --wait

This argument states how long (in seconds) Timelog should wait before running the user defined program again when receiving a failed exit status.

#### --retry

This states how many times Timelog should try to run the user defined program on failures. It runs this number of times before writing a Timelog entry to the Timelog file returned on latest failure. Note, if the program returns sucessfully Timelog writes to that Timelog file immediately.

## Example

We would like to register the time when booting up and shutting down a laptop. At the same time these times should be sorted by where we are (f.ex. on work or at home).

To this end we have a shell-script (find_ip.sh) that looks at the IP address of the local host. If it finds,

• the work IP address, it exits successfully along with the path /home/bo/work.timelog
• the home IP address, it exits successfully along with the path /home/bo/home.timelog
• an unknown IP address, it exits with a failure along with the path /home/bo/unknown.timelog

Now, we create a script (f.ex. using a couple of Linux RC programs in /etc/rc*.d/) that calls Timelog when the laptop is booting up and shutting down. This way the starting and ending time of the laptop is written to either of the files: work.timelog, home.timelog or unknown.timelog - depending on the local host IP address.

Here is an example of a such Timelog file,

...
2007-12-30T16:14:15+0200 ON
2007-12-30T16:20:30+0200 OFF
2007-12-31T15:14:15+0200 ON
2007-12-31T17:14:15+0200 OFF
2008-01-06T13:14:15+0200 ON
2008-01-06T17:14:15+0200 OFF
2008-01-07T12:14:15+0200 ON
...

Timelog does not necessarily write to the file right away, but may be told to try several times until the user defined script (here it's find_ip.sh) exits successfully. When Timelog is run in debug mode it may look like this,

* Timelog starting: 2008-08-31T15:04:10+0200
* Selected mode: ON
* Using script: /home/bo/find_ip.sh
+ failed, retry 0/10 (wait 60 secs)
+ failed, retry 1/10 (wait 60 secs)
+ failed, retry 2/10 (wait 60 secs)
+ success, retry 3/10
* Using log: /home/bo/home.timelog
* Writing new entry to log

## Accessories

Some additional software.

### guessLog

This script tries to identify the IP address of the computer as being a part of the work or home network.

Download: guessLog

### rc.timelogON

A Linux RC script that calls Timelog and turns the time logging ON. This script could be placed in the folder /etc/rc3.d/ (assuming the host boots into run-level 3) - this way it's called on boot-up.

Download: rc.timelogON

### rc.timelogOFF

A Linux RC script that calls Timelog and turns the time logging OFF. This script could be placed in the folder /etc/rc0.d/ - this way it is called on shut-down.

Download: rc.timelogOFF

### TimeLog::Manip

Timelog itself is not capable of reading Timelog files. To do this a perl module called Timelog::Manip is needed.