NAME

       ntpviz - make visualizations of offset, jitter, etc. from stats file data

SYNOPSIS

       ntpviz [-d LOGDIR] [-g] [-n name] [-p DAYS]
                [-s starttime] [-e endtime]
                [-o OUTDIR]
                [-c | --clip]
                [-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]
                [-D DLVL | --debug DLVL]
                [-N | --nice]
                [-V | --version]
                [@OPTIONFILE]

DESCRIPTION

       This utility 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
       -d LOGDIR or --datadir LOGDIR
           Specifies one or more logfile directories to examine; the default is the single
           directory /var/log/ntpstats.

       -g or --generate
           Run plot through gnuplot to make png. The default is to generate gnuplot programs.

       -o OUTDIR or --outdir OUTDIR
           Set the directory for all output to be OUTDIR. If OUTDIR does not exist it is created.
           The default OUTDIR is ntpgraphs. Warning: existing PNG files and index.html in the
           output directory will be clobbered.

       -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.

       -p DAYS or --period DAYS
           The default DAYS is for the period of 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.

       -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 can specify either -s or -e (but not both) and use -p to set the
           plot period in days.

       -s TIME or --starttime TIME
           See -e and -p.

       -c or --clip
           Normally all the data is 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.

       -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.

       -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.

       -N or --nice
           Run at the lowest possible priority. Only available on UNIX.

       -V or --version: Print program version and exit.

   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 Number of Sats 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 two files in the output directory.
       Neither of these files need be present, and the header and footer files may contain
       arbitrary HTML.

       The first file is named header. The contents of that file will be added almost at the top
       of the body on 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.

       This is the place to put links to other web pages, or headline notes.

       The second file is named footer. The contents of that file will be added almost at the
       bottom of the body on the generated index. As a special exception, the default cron job in
       the ntpsec-ntpviz package has symlinks such that it uses /etc/ntpviz/day/footer.html and
       /etc/ntpviz/week/footer.html.

       It is suggested that notes on the server be included in the footer file: OS, versions, CPU
       speed, etc. You may also put links there.

       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 can 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 can be added, and start 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 a space.

       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.