rsync-dist-info.py

a tool to analyze rsync-dist log files

Overview

This tool can be used to analyze the rsync-dist LOG-LINKS file. A LOG-LINKS file is modified by rsync-dist.pl each time one or more links are changed. Although the format of the log file contains all necessary information, it is difficult to see which links point to which version or to see what versions are no longer in use.

Here are the terms used in this manual:

version: This is a single version of the distributed software. A version is a directory in the rsync-dist distribution directory whose last part is an ISO Date string like "2009-04-01T12:15".
link: This is a symbolic link in the rsync-dist link directory that points to a specific version. Links may come into existence at some point of time pointing to a specific version. They may be changed at another time to point to another version and they may be deleted some time later.
name: In this program, this is the name of a link.
in use: A version is called "in use" when at least one name points to that version.
active: A version is called active when it is "in use" today
lifetime: This is the sum of days a version was "in use". Note that the precise times are taken into account by using fractions of whole days.

Quick reference

show statistics on link names:

rsync-dist-info.py -c rsync-dist.config -n

show statistics on versions:

rsync-dist-info.py -c rsync-dist.config -v

show statistics on version lifetimes:

rsync-dist-info.py -c rsync-dist.config -l

show an overview on IOC boot times:

rsync-dist-info.py -c rsync-dist.config --boot-times

show fallback recommendation:

rsync-dist-info.py -c rsync-dist.config --fallback-info [linkname]

show information for a list of versions:

rsync-dist-info.py -c rsync-dist.config --version-info [version1,version2...]

Output formats

rsync-dist-info has four output formats.

the names format

In this format, each symlink-name is followed by a colon and a number of lines describing at what date this link pointed to what version. If the symbolic link was removed at a certain time, the string "REMOVED" is printed instead of a version. An active version, that means the version the link currently points to, is marked with a star "*". Here is an example:

SIOC7C:
     2009-10-05 11:40:10    2009-10-05T11:39:00
     2009-10-06 13:26:18    2009-10-06T13:25:13
*    2009-10-06 13:40:49    2009-10-06T13:40:40

SIOC8C:
     2009-10-05 11:40:10    2009-10-05T11:39:00
     2009-10-06 13:26:18    2009-10-06T13:25:13
*    2009-10-06 13:40:49    2009-10-06T13:40:40

SIOC9C:
     2009-10-05 11:40:10    2009-10-05T11:39:00
     2009-10-06 13:26:18    2009-10-06T13:25:13
     2009-10-06 13:40:49    REMOVED

the versions format

This format shows for each version at what time what symbolic links (names) pointed to this version. If a symbolic link was made to point to a different version at a certain date, the old version has a new entry with that timestamp with this symbolic link removed. If there are no symbolic links for a version, the list is empty. This shows that from this date on, the version is no longer in use. Here is an example:

2009-07-06T13:22:40:
     2009-07-06 13:22:59    SIOC1C
     2009-10-05 11:25:11

2009-07-09T13:42:56:
     2009-07-09 13:43:17    IOC1S15G
     2009-07-09 13:43:43    IOC1S15G IOC1S1G
     2009-07-13 08:13:32    IOC1S1G
     2009-07-16 11:50:50

the lifetimes format

This format shows the timespan a version was in use, meaning the time when at least one symbolic link pointed to that version. In this format the first and last date of any usage is printed as well as the lifetime in fractions of days. If the version is at this time still in use, the second date is "NOW". Here is an example:

2009-09-22T11:56:18:
     2009-09-22 11:56:43    2009-10-05 11:25:11
                                                    13.0
2009-09-28T09:29:48:
     2009-09-28 09:31:04    2009-10-05 11:25:11
     2009-10-05 19:25:18    2009-10-06 13:26:18
                                                     7.8
2009-09-28T12:42:12:
     2009-09-28 12:42:29    2009-10-05 11:25:11
                                                     6.9
                                                     0.97

the idles format

This format is used for the special -i or --idle option. It is a list of the sub-directories in the distribution directory that are not and were never in use, meaning no symbolic link ever pointed to them. Here is an example:

2009-07-06T09:08:56
2009-09-14T09:40:01
2009-10-06T10:22:52

the boottimes format

This format displays an overview on all names and the times when the corresponding IOCs were booted. Here is an example:

name            version              activated            booted               comment
BAWATCHP        2009-02-18T15:10:54  2009-02-18T15:11:06  -                    dont't known how to find boottime for this name
IOC1S1GP        2009-10-23T14:06:35  2009-10-23T14:07:06  2009-10-09T16:27:09  IOC doesn't run with active version
IOC1S4GP        2009-10-09T14:54:54  2009-10-09T14:55:18  2009-10-09T14:56:54
IOC2S1GP        2009-11-13T11:58:23  2009-11-13T11:58:36  2009-11-13T13:30:15

If the option --verbose is used together with --boot-times, the number of days the IOC's are running is also printed:

name            version              activated            booted               days running  comment
BAWATCHP        2009-02-18T15:10:54  2009-02-18T15:11:06  -                               -  dont't known how to find boottime for this name
IOC1S1GP        2009-10-23T14:06:35  2009-10-23T14:07:06  2009-10-09T16:27:09          38.8  IOC doesn't run with active version (for 24.9 days)
IOC1S4GP        2009-10-09T14:54:54  2009-10-09T14:55:18  2009-10-09T14:56:54          38.9
IOC2S1GP        2009-11-13T11:58:23  2009-11-13T11:58:36  2009-11-13T13:30:15           3.9

Reference of command line options

`--version`	print the version number of the script
`-h, --help`	print a short help
`--summary`	print a one-line summary of the script function
`--doc`	create online help in restructured text format. Use "./rsync-dist-info.py --doc \| rst2html" to create html-help"
`-t, --test`	perform a simple self-test of some internal functions
`--debug`	show executed rsync-dist.pl commands
`-c CONFIGFILE, --call CONFIGFILE`
	call rsync-dist.pl directly with CONFIGFILE. With this option it is no longer necessary to call rsync-dist.pl directly.
`-n, --names`	print summary for each link name
`-v, --versions`	print summary for each version
`-l, --lifetimes`
	print lifetime summary for each version
`-i, --idle`	print idle versions, versions that are not in use and never have been.
`--version-info VERSIONS`
	show logfile information for VERSIONS. VERSIONS is a comma-separated list of version strings.
`--boot-times`	check boot-times in relation with times a version was activated.
`-b, --brief`	brief output, with -n just show link names, with -v just show version and most recent links, with -l just show version names.
`--last NO`	with --names, print only the last NO versions for each name
`--filter-names NAMES`
	NAMES may be a comma separated list. Only these names and their versions are printed.
`--filter-versions VERSIONS`
	show only information for versions specified by VERSIONS, which may be a comma-separated list of versions.
`--filter-active`
	show only versions that are now in use
`--filter-inactive`
	show only versions that are not in use
`--filter-inactive-since=DATE`
	filter versions inactive for longer than a given DATE
`--filter-lifetime-smaller=DAYS`
	filter versions with a lifetime smaller than DAYS
`--filter-lifetime-bigger=DAYS`
	filter versions with a lifetime bigger than DAYS
`--filter-existent`
	show only version that are still existent in the distribution directory.
`--filter-nonexistent`
	show only version that are not existent in the distribution directory.
`--filter-ignexistent`
	show versions no matter if they exist or exist not in the distribution directory. This is needed if you want to overturn the implicit --filter-existent that is otherwise set.
`--fallback-info LINKNAME`
	show a short list of recommended versions for the given linkname. This option corresponds to -n --filter-lifetime-bigger 2 --last 3 --filter-names LINKNAME.