Visualizing data

The best tool for visualizing TimeKeeper’s data is the web interface, covered in the “Web management” and “TimeKeeper web interface” sections, or with the PDF reports generated by TimeKeeper Compliance.

plot.sh

However, in some cases it’s helpful to post process data, either on the host directly or on another machine. A script is provided for this on Linux, and can interactively plot timing data or generate plot images of aspects of timing quality over time.

The script is provided here:

/opt/timekeeper/release64/plots/plot.sh

Also included in that directory are a number of gnuplot scripts to parse TimeKeeper files. plot.sh can use any of these, but offsetplot.in is of the most interest to users (this is the default plot). It shows the clock offset from the source, both the raw input TimeKeeper received, and the smoothed clock presented to the user.

Here’s an example of how to use the script:

# ./plot.sh

or for a specific file:

# ./plot.sh -f /var/log/timekeeper_1.data

This will show an interactive plot of the local system’s TimeKeeper data, updating every 5 seconds. Similarly:

# ./plot.sh -l user@host:/var/log/timekeeper_0.data -f 30

Will plot results of TimeKeeper data from host ‘host’, retrieving the data file and updating every 30 seconds. Both of the above commands will generate plots of the clock offset - specifying -p plotfile.in allows you to create a different graph. Another example is:

# ./plot.sh -p clockrateplot.in

This will generate a plot of the changes in clock rate on the local machine running TimeKeeper. Running plot.sh -h will print a full list of accepted arguments.

The gnuplot scripts can also be customized to display other information as needed.

Extracting data with tkcat

tkcat is a command line tool to extract TimeKeeper source data from the log files. It’s handy to use when you want timing behavior about a particular source over a specific span of time. That data might be in the most recent .data file, or it may be in a previous logrotated file, or it may span multiple files. tkcat finds and extracts that data for you without having to worry about which files contain what data.

If you wanted to get data from source 1 about its behavior from 6am-4pm June 1 2018 (UTC), you’d get the start and stop UTC epoch seconds for that time window (1527832800 and 1527868800 respectively), and pass that information along to tkcat, which is provided in the release64 directory within the TimeKeeper installation:

# ./tkcat -e 1527832800 -l 1527868800 -f /var/log/timekeeper_1.data

This will print to stdout source 1’s samples from within that time period. If the samples span logrotated or compressed files that’s fine, tkcat will handle that detail and just provide the clock sample data. This can be redirected and then optionally fed into other tools like plot.sh above, Excel, and so on.

Other options include the ability to subsample with -s (only provide 1000 samples over the given time period), -r for human readable output, and -n to only extract data from the newest file.

Alternative tools

Since the data is stored in an open format, documented in the “File formats” section, there are other alternatives for post processing data too.

The data is easily imported into Excel, at which point many common processing and plotting options are available.