1NTPVIZ(1)                           NTPsec                           NTPVIZ(1)
2
3
4

NAME

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

SYNOPSIS

10       ntpviz [OPTIONS]
11                [-c | --clip]
12                [-D DLVL | --debug DLVL]
13                [-d LOGDIR[,LOGDIR]...]
14                [-e endtime]
15                [-g | --general]
16                [-h | --help]
17                [-n NAME | --name NAME]
18                [-N | --nice]
19                [-o OUTDIR | --outdir OUTDIR]
20                [-p DAYS | --period DAYS]
21                [-s STARTTIME | --starttime STARTTIME]
22                [-T TERMINAL | --terminal TERMINAL]
23                [-V | --version]
24                [-w SIZE | --width SIZE]
25                [--all-peer-jitters |
26                 --all-peer-offsets |
27                 --local-error |
28                 --local-freq-temps |
29                 --local-gps |
30                 --local-jitter |
31                 --local-offset |
32                 --local-offset-histogram |
33                 --local-offset-multiplot |
34                 --local-stability |
35                 --local-temps |
36                 --peer-jitters=hosts |
37                 --peer-offsets=hosts]
38                [@OPTIONFILE]
39

DESCRIPTION

41       ntpviz analyzes files in an NTP log directory and generates statistical
42       plots from them. It can output either PNG images or the gnuplot
43       programs to generate them to standard output. In its default mode it
44       generates an HTML directory containing an index page and either (a) all
45       plots, for a single statfiles directory, or (b) a subset of comparative
46       plots for multiple directories.
47
48   Basic Options
49       -c or --clip
50           Normally all data are plotted. This option limits the range of the
51           plots to the data between 1% and 99%; this is useful for ignoring a
52           few spikes in the data.
53
54       -d LOGDIR[,LOGDIR]... or --datadir LOGDIR[,LOGDIR]...
55           Specifies one or more logfile directories to examine; the default
56           is the single directory /var/log/ntpstats.
57
58       -D DLVL or --debug DLVL
59           Set the debug level to DLVL. Larger DLVL leads to more verbosity.
60           0 is the default, quiet except for all ERRORs and some WARNINGs.
61           1 shows some environment info and basic program progress.
62           2 leaves the plot file in the system temp directory.
63           9 is painfully verbose. 9 also includes profile data.
64
65       -e TIME or --endtime TIME
66           With -s and -e you set the start and end times. TIME is either
67           numeric POSIX time (seconds since the start of the epoch) or ISO
68           8601-style timestamps (yyyy-mmm-ddThh:mm:ss).
69           The default end time is the last logfile entry timestamp.
70           The default start time is computed as the end time minus DAYS.
71           Alternatively, you may specify either -s or -e (but not both) and
72           use -p to set the plot period in days.
73
74       -g or --generate
75           Run plot through gnuplot to make png. The default is to generate
76           gnuplot programs.
77
78       -n STR or --name STR
79           Set the sitename shown in the plot title, and is effective only for
80           the single-directory case. The default is the basename of the log
81           directory.
82
83       -N or --nice
84           Run at the lowest possible priority. Only available on UNIX.
85
86       -o OUTDIR or --outdir OUTDIR
87           Set the directory for all output to be OUTDIR, if OUTDIR does not
88           exist it gets created. The default OUTDIR is ntpgraphs. Warning:
89           existing PNG files and index.html in the output directory will be
90           clobbered.
91
92       -p DAYS or --period DAYS
93           The default DAYS is for 7 days. DAYS can be a floating point
94           number, so "-p 0.5" plots 12 hours. DAYS is ignored if -s and -e
95           are given.
96
97       -s TIME or --starttime TIME
98           See -e and -p.
99
100       -T TERMINAL or --terminal TERMINAL
101           Set the gnuplot terminal type for generating the graphs. Supported
102           types are gif, jpg, png, pngcairo, and svg. The default is png.
103           Some prefer pngcairo or svg.
104
105       -V or --version
106           Print program version and exit.
107
108       -w SIZE or --width SIZE
109           Set the size of the output plots. SIZE can be one of s, m, or l. s
110           is for browser on small screens (1024x768). m for medium screens
111           (1388x768). l for large screens (1920x1080). m is the default.
112
113   Individual Plots
114       The plot options choose what graph is generated; invoke only one. By
115       default, the gnuplot for the graph is reported; with -g you get the
116       rendered PNG.
117
118       The following plots are available:
119
120       --all-peer-jitters
121           Report all peer jitters; this is a different option name from
122           --peer-jitters only because of a limitation in the Python standard
123           library.
124
125       --all-peer-offsets
126           Report all peer offsets; this is a different option name from
127           --peer-offsets only because of a minor limitation in the Python
128           standard library.
129
130       --local-error
131           Clock frequency offset from the loop statistics (field 4)
132
133       --local-freq-temps
134           Plot local frequency offset and local temperatures. This plot is
135           only generated if there is a log file named temps in the log file
136           directory.
137
138       --local-jitter
139           Clock time-jitter plot from the loop statistics (field 5).
140
141       --local-gps
142           Plot GPS Time Dilution of Precision (TDOP) and the number of
143           satellites used (nSats). This plot is only generated if there is a
144           log file named gpsd in the log file directory.
145
146       --local-offset
147           Clock time and clock frequency offsets from the loop statistics
148           (fields 3 and 4).
149
150       --local-offset-histogram
151           Frequency histogram of distinct loopstats time offset values (field
152           3).
153
154       --local-offset-multiplot
155           Plot comparative local offsets for multiple directories.
156
157       --local-temps
158           Plot local temperatures. This plot is only generated if there is a
159           log file named temps in the log file directory.
160
161       --local-stability
162           RMS frequency-jitter plot from the loop statistics (field 6); this
163           is deviation from a root-mean-square extrapolation of the moving
164           average of past frequency readings.
165
166       --peer-jitters=host1[,host2...]
167           Peer jitter from local clock time, from peerstats (field 7) A
168           comma-separated list of peer names must follow. It is a fatal error
169           for any of these names not to appear in peerstats.
170
171       --peer-offsets=host1[,host2...]
172           Peer offset from local clock time from peerstats (field 4). A
173           comma-separated list of peer names or IP addresses must follow. It
174           is a fatal error for any of these names not to appear in peerstats.
175
176       If no individual plot is specified, all plots and an index HTML page
177       are generated into the output directory.
178
179       When an index is generated, ntpviz will look for a header and footer
180       file in the output directory. Neither of these files are required.
181       These files may contain arbitrary HTML.
182
183       The header file will be added almost at the top of the body of the
184       generated index page, and the footer file will be added almost at the
185       bottom of the body of the generated index page.
186
187       The contents are at the discretion of the operator. One might put links
188       to other related web pages, or notes on the server OS, software
189       versions, hardware configuration, etc. into either of these files, as
190       desired.
191
192       The code includes various sanity checks and will bail out with a
193       message to standard error on, for example, missing logfile data
194       required for a plot.
195
196   Argument File
197       Any command line options may also be placed into a command file. The
198       command file name (OPTIONFILE) is prefixed on the command line with an
199       atsign (@).
200
201       Each line in the command file should contain just one option. Multiple
202       options per line are allowed but discouraged. Blank lines are allowed.
203
204       Comments may be added prepended with an octothorpe (#). Comments may
205       appear on a new line, or trailing, after the # .
206
207       When an option takes a parameter, the option and parameter must be
208       separated by an equal sign (=) or spaces.
209
210       These two ways to invoke ntpviz are equivalent:
211
212           $ ntpviz --period 1 --outdir day
213
214           $ cat day/config
215           --period=1
216           --outdir=day
217           $ ntpviz @day/config
218

REQUIREMENTS

220       Python and gnuplot. The plots will look better with the liberation font
221       package installed.
222

AUTHORS

224       Eric S. Raymond, Gary E. Miller, and Daniel Drown. The gnuplot in this
225       package is largely based on templates in Daniel Drown’s chrony-graph
226       project: https://github.com/ddrown/chrony-graph/tree/ntpd
227

EXIT STATUS

229       One of the following exit values will be returned:
230
231       0
232           Successful program execution.
233
234       1
235           The operation failed, usually due to a missing logfile required for
236           a plot.
237
238       2
239           Illegal command-line option.
240
241
242
243NTPsec                            2022-01-20                         NTPVIZ(1)
Impressum