Provided by: ntpsec-ntpviz_1.1.8+dfsg1-4build1_amd64 
NAME
ntpviz - make visualizations of offset, jitter, etc. from stats file data
SYNOPSIS
ntpviz [OPTIONS]
[-c | --clip]
[-D DLVL | --debug DLVL]
[-d LOGDIR]
[-e endtime]
[-g | --general]
[-h | --help]
[-n NAME | --name NAME]
[-N | --nice]
[-o OUTDIR | --outdir OUTDIR]
[-p DAYS | --period DAYS`]
[-s STARTTIME | --starttime STARTTIME]
[-T TERMINAL | --terminal TERMINAL]
[-V | --version]
[-w SIZE | --width SIZE]
[--all-peer-jitters |
--all-peer-offsets |
--local-error |
--local-freq-temps |
--local-gps |
--local-jitter |
--local-offset |
--local-offset-histogram |
--local-offset-multiplot |
--local-stability |
--local-temps |
--peer-jitters=hosts |
--peer-offsets=hosts]
[@OPTIONFILE]
DESCRIPTION
ntpviz analyzes files in an NTP log directory and generates statistical plots from them.
It can output either PNG images or the gnuplot programs to generate them to standard
output. In its default mode it generates an HTML directory containing an index page and
either (a) all plots, for a single statfiles directory, or (b) a subset of comparative
plots for multiple directories.
Basic Options
-c or --clip
Normally all data are plotted. This option limits the range of the plots to the data
between 1% and 99%; this is useful for ignoring a few spikes in the data.
-d LOGDIR or --datadir LOGDIR
Specifies one or more logfile directories to examine; the default is the single
directory /var/log/ntpstats.
-D DLVL or --debug DLVL
Set the debug level to DLVL. Larger DLVL leads to more verbosity.
0 is the default, quiet except for all ERRORs and some WARNINGs.
1 shows some environment info and basic program progress.
2 leaves the plot file in the system temp directory.
9 is painfully verbose. 9 also includes profile data.
-e TIME or --endtime TIME
With -s and -e you set the start and end times. TIME is either numeric POSIX time
(seconds since the start of the epoch) or ISO 8601-style timestamps
(yyyy-mmm-ddThh:mm:ss).
The default end time is the last logfile entry timestamp.
The default start time is computed as the end time minus DAYS.
Alternatively, you may specify either -s or -e (but not both) and use -p to set the
plot period in days.
-g or --generate
Run plot through gnuplot to make png. The default is to generate gnuplot programs.
-n STR or --name STR
Set the sitename shown in the plot title, and is effective only for the
single-directory case. The default is the basename of the log directory.
-N or --nice
Run at the lowest possible priority. Only available on UNIX.
-o OUTDIR or --outdir OUTDIR
Set the directory for all output to be OUTDIR, if OUTDIR does not exist it gets
created. The default OUTDIR is ntpgraphs. Warning: existing PNG files and index.html
in the output directory will be clobbered.
-p DAYS or --period DAYS
The default DAYS is for 7 days. DAYS can be a floating point number, so "-p 0.5" plots
12 hours. DAYS is ignored if -s and -e are given.
-s TIME or --starttime TIME
See -e and -p.
-T TERMINAL or --terminal TERMINAL
Set the gnuplot terminal type for generating the graphs. Supported types are gif, jpg,
png, pngcairo, and svg. The default is png. Some prefer pngcairo or svg.
-V or --version
Print program version and exit.
-w SIZE or --width SIZE
Set the size of the output plots. SIZE can be one of s, m, or l. s is for browser on
small screens (1024x768). m for medium screens (1388x768). l for large screens
(1920x1080). m is the default.
Individual Plots
The plot options choose what graph is generated; invoke only one. By default, the gnuplot
for the graph is reported; with -g you get the rendered PNG.
The following plots are available:
--all-peer-jitters
Report all peer jitters; this is a different option name from --peer-jitters only
because of a limitation in the Python standard library.
--all-peer-offsets
Report all peer offsets; this is a different option name from --peer-offsets only
because of a minor limitation in the Python standard library.
--local-error
Clock frequency offset from the loop statistics (field 4)
--local-freq-temps
Plot local frequency offset and local temperatures. This plot is only generated if
there is a log file named temps in the log file directory.
--local-jitter
Clock time-jitter plot from the loop statistics (field 5).
--local-gps
Plot GPS Time Dilution of Precision (TDOP) and the number of satellites used (nSats).
This plot is only generated if there is a log file named gpsd in the log file
directory.
--local-offset
Clock time and clock frequency offsets from the loop statistics (fields 3 and 4).
--local-offset-histogram
Frequency histogram of distinct loopstats time offset values (field 3).
--local-offset-multiplot
Plot comparative local offsets for multiple directories.
--local-temps
Plot local temperatures. This plot is only generated if there is a log file named
temps in the log file directory.
--local-stability
RMS frequency-jitter plot from the loop statistics (field 6); this is deviation from a
root-mean-square extrapolation of the moving average of past frequency readings.
--peer-jitters=host1[,host2...]
Peer jitter from local clock time, from peerstats (field 7) A comma-separated list of
peer names must follow. It is a fatal error for any of these names not to appear in
peerstats.
--peer-offsets=host1[,host2...]
Peer offset from local clock time from peerstats (field 4). A comma-separated list of
peer names or IP addresses must follow. It is a fatal error for any of these names not
to appear in peerstats.
If no individual plot is specified, all plots and an index HTML page are generated into
the output directory.
When an index is generated, ntpviz will look for a header and footer file in the output
directory. Neither of these files are required. These files may contain arbitrary HTML.
The header file will be added almost at the top of the body of the generated index page,
and the footer file will be added almost at the bottom of the body of the generated index
page.
As a special exception, the default cron job in the ntpsec-ntpviz package has symlinks
such that it uses /etc/ntpviz/day/header.html and /etc/ntpviz/week/header.html.
The contents are at the discretion of the operator. One might put links to other related
web pages, or notes on the server OS, software versions, hardware configuration, etc. into
either of these files, as desired.
The code includes various sanity checks and will bail out with a message to standard error
on, for example, missing logfile data required for a plot.
Argument File
Any command line options may also be placed into a command file. The command file name
(OPTIONFILE) is prefixed on the command line with an atsign (@).
Each line in the command file should contain just one option. Multiple options per line
are allowed but discouraged. Blank lines are allowed.
Comments may be added prepended with an octothorpe (#). Comments may appear on a new line,
or trailing, after the # .
When an option takes a parameter, the option and parameter must be separated by an equal
sign (=) or spaces.
These two ways to invoke ntpviz are equivalent:
$ ntpviz --period 1 --outdir day
$ cat day/config
--period=1
--outdir=day
$ ntpviz @day/config
REQUIREMENTS
Python and gnuplot. The plots will look better with the liberation font package installed.
AUTHORS
Eric S. Raymond, Gary E. Miller, and Daniel Drown. The gnuplot in this package is largely
based on templates in Daniel Drown’s chrony-graph project:
https://github.com/ddrown/chrony-graph/tree/ntpd
EXIT STATUS
One of the following exit values will be returned:
0
Successful program execution.
1
The operation failed, usually due to a missing logfile required for a plot.
2
Illegal command-line option.