1NTPVIZ(1) NTPsec NTPVIZ(1)
2
6 ntpviz - make visualizations of offset, jitter, etc. from stats file
7 data
8
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
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 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 -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 -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 -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 -g or --generate
75 Run plot through gnuplot to make png. The default is to generate
76 gnuplot programs.
77 -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 -N or --nice
84 Run at the lowest possible priority. Only available on UNIX.
85 -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 -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 -s TIME or --starttime TIME
98 See -e and -p.
99 -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 -V or --version
106 Print program version and exit.
107 -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 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 The following plots are available:
119 --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 --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 --local-error
131 Clock frequency offset from the loop statistics (field 4)
132 --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 --local-jitter
139 Clock time-jitter plot from the loop statistics (field 5).
140 --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 --local-offset
147 Clock time and clock frequency offsets from the loop statistics
148 (fields 3 and 4).
149 --local-offset-histogram
151 Frequency histogram of distinct loopstats time offset values (field
152 3).
153 --local-offset-multiplot
155 Plot comparative local offsets for multiple directories.
156 --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 --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 --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 --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 If no individual plot is specified, all plots and an index HTML page
177 are generated into the output directory.
178 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 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 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 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 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 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 Comments may be added prepended with an octothorpe (#). Comments may
205 appear on a new line, or trailing, after the # .
206 When an option takes a parameter, the option and parameter must be
208 separated by an equal sign (=) or spaces.
209 These two ways to invoke ntpviz are equivalent:
211 $ ntpviz --period 1 --outdir day
213 $ cat day/config
215 --period=1
216 --outdir=day
217 $ ntpviz @day/config
218
220 Python and gnuplot. The plots will look better with the liberation font
221 package installed.
222
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
229 One of the following exit values will be returned:
230 0
232 Successful program execution.
233 1
235 The operation failed, usually due to a missing logfile required for
236 a plot.
237 2
239 Illegal command-line option.
240NTPsec 2023-08-03 NTPVIZ(1)