Monitoring Options
from Pogo,
Walt Kelly
The pig watches the logs.
Monitoring Support
ntpd includes a comprehensive monitoring facility suitable
for continuous, long term recording of server and client
timekeeping performance. See the statistics command below
for a listing and example of each type of statistics currently
supported. Statistic files are managed using file generation sets
and scripts in the ./scripts directory of this distribution. Using
these facilities and Unix cron jobs, the datacan be
automatically summarized and archived for retrospective analysis.
Monitoring Commands
- statistics name [...]
- Enables writing of statistics records. Currently, four kinds of
namestatistics are supported.
-
- clockstats
- Enables recording of clock driver statistics information. Each
update received from a clock driver appends a line of the following
form to the file generation set named clockstats:
- 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
- The first two fields show the date (Modified Julian Day) and
time (seconds and fraction past UTC midnight). The next field shows
the clock address in dotted-quad notation, The final field shows
the last timecode received from the clock in decoded ASCII format,
where meaningful. In some clock drivers a good deal of additional
information can be gathered and displayed as well. See information
specific to each clock for further details.
- cryptostats
- This option requires the OpenSSL cryptographic software
library. It enables recording of cryptographic public key protocol
information. Each message received by the protocol module appends a
line of the following form to the file generation set named
cryptostats:
- 49213 525.624 127.127.4.1 message
- The first two fields show the date (Modified Julian Day) and
time (seconds and fraction past UTC midnight). The next field shows
the peer address in dotted-quad notation, The final
message field includes the message type and certain
ancillary information. See the Authentication
Options page for further information.
- loopstats
- Enables recording of loop filter statistics information. Each
update of the local clock outputs a line of the following form to
the file generation set named loopstats:
- 50935 75440.031 0.000006019 13.778190 0.000351733
0.0133806
- The first two fields show the date (Modified Julian Day) and
time (seconds and fraction past UTC midnight). The next five fields
show time offset (seconds), frequency offset (parts per million -
PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
discipline time constant.
- peerstats
- Enables recording of peer statistics information. This includes
statistics records of all peers of a NTP server and of special
signals, where present and configured. Each valid update appends a
line of the following form to the current element of a file
generation set named peerstats:
- 48773 10847.650 127.127.4.1 9714 -0.001605 0.00000
0.00142
- The first two fields show the date (Modified Julian Day) and
time (seconds and fraction past UTC midnight). The next two fields
show the peer address in dotted-quad notation and status,
respectively. The status field is encoded in hex in the format
described in Appendix A of the NTP specification RFC 1305. The
final three fields show the offset, delay and RMS jitter, all in
seconds.
- rawstats
- Enables recording of raw-timestamp statistics information. This
includes statistics records of all peers of a NTP server and of
special signals, where present and configured. Each NTP message
received from a peer or clock driver appends a line of the
following form to the file generation set named
rawstats:
- 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000
3102453281.58622800031 02453332.540806000
3102453332.541458000
- The first two fields show the date (Modified Julian Day) and
time (seconds and fraction past UTC midnight). The next two fields
show the remote peer or clock address followed by the local address
in dotted-quad notation, The final four fields show the originate,
receive, transmit and final NTP timestamps in order. The timestamp
values are as received and before processing by the various data
smoothing and mitigation algorithms.
- statsdir directory_path
- Indicates the full path of a directory where statistics files
should be created (see below). This keyword allows the (otherwise
constant) filegen filename prefix to be modified for file
generation sets, which is useful for handling statistics logs.
- filegen name [file filename] [type
typename] [link | nolink] [enable | disable]
- Configures setting of generation file set name.
Generation file sets provide a means for handling files that are
continuously growing during the lifetime of a server. Server
statistics are a typical example for such files. Generation file
sets provide access to a set of files used to store the actual
data. At any time at most one element of the set is being written
to. The type given specifies when and how data will be directed to
a new element of the set. This way, information stored in elements
of a file set that are currently unused are available for
administrational operations without the risk of disturbing the
operation of ntpd. (Most important: they can be removed to
free space for new data produced.)
- Note that this command can be sent from the ntpdc
program running at a remote location.
-
- name
- This is the type of the statistics records, as shown in the
statistics command.
- file filename
-
- This is the file name for the statistics records. Filenames of
set members are built from three concatenated elements
prefix, filename and
suffix:
-
- prefix
- This is a constant filename path. It is not subject to
modifications via the filegen option. It is defined by the
server, usually specified as a compile-time constant. It may,
however, be configurable for individual file generation sets via
other commands. For example, the prefix used with
loopstats and peerstats generation can be configured
using the statsdir option explained above.
- filename
- This string is directly concatenated to the prefix mentioned
above (no intervening / (slash)). This can be modified
using the file argument to the filegen statement.
No .. elements are allowed in this component to prevent
filenames referring to parts outside the filesystem hierarchy
denoted by prefix.
- suffix
- This part is reflects individual elements of a file set. It is
generated according to the type of a file set.
- type typename
-
- A file generation set is characterized by its type. The
following types are supported:
-
- none
- The file set is actually a single plain file.
- pid
- One element of file set is used per incarnation of a
ntpd server. This type does not perform any changes to file
set members during runtime, however it provides an easy way of
separating files belonging to different ntpd server
incarnations. The set member filename is built by appending a
. (dot) to concatenated prefix and filename
strings, and appending the decimal representation of the process ID
of the ntpd server process.
- day
- One file generation set element is created per day. A day is
defined as the period between 00:00 and 24:00 UTC. The file set
member suffix consists of a . (dot) and a day
specification in the form YYYYMMdd. YYYY is a 4-digit year
number (e.g., 1992). MM is a two digit month number.
dd is a two digit day number. Thus, all information written at
10 December 1992 would end up in a file named prefix
filename.19921210.
- week
- Any file set member contains data related to a certain week of
a year. The term week is defined by computing day-of-year modulo 7.
Elements of such a file generation set are distinguished by
appending the following suffix to the file set filename base: A
dot, a 4-digit year number, the letter W, and a 2-digit
week number. For example, information from January, 10th 1992 would
end up in a file with suffix .1992W1.
- month
- One generation file set element is generated per month. The
file name suffix consists of a dot, a 4-digit year number, and a
2-digit month.
- year
- One generation file element is generated per year. The filename
suffix consists of a dot and a 4 digit year number.
- age
- This type of file generation sets changes to a new element of
the file set every 24 hours of server operation. The filename
suffix consists of a dot, the letter a, and an 8-digit
number. This number is taken to be the number of seconds the server
is running at the start of the corresponding 24-hour period.
Information is only written to a file generation by specifying
enable; output is prevented by specifying
disable.
- link | nolink
-
- It is convenient to be able to access the current element of a
file generation set by a fixed name. This feature is enabled by
specifying link and disabled using nolink. If
link is specified, a hard link from the current file set
element to a file without suffix is created. When there is already
a file with this name and the number of links of this file is one,
it is renamed appending a dot, the letter C, and the pid
of the ntpd server process. When the number of links is
greater than one, the file is unlinked. This allows the current
file to be accessed by a constant name.
- enable | disable
-
- Enables or disables the recording function.
David L. Mills
<mills@udel.edu>