1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
// This is the body of the manual page for ntpviz.
// It's included in two places: once for the docs/ HTML
// tree, and once to make an individual man page.
== SYNOPSIS
[verse]
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
// end
|
