// Monitoring commands. Is included twice.

[[statistics]]+statistics+ _name..._::
  Enables writing of statistics records. Currently, eight kinds of
  _name_ statistics 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 SPECTRACOM(1) 93 226 00:08:29.606
-----------------------------------------------
+
[width="100%",cols="<34%,<33%,<33%"]
|====================================================================
|Item                |Units     |Description
|49213               |MJD       |modified Julian day number
|525.624             |s         |time of day (s) past midnight UTC
|SPECTRACOM(1)       |          |receiver identifier (Spectracom unit 1)
|93 226 00:08:29.606 |          |timecode (format varies by refclock)
|====================================================================
+
The first two fields show the date (Modified Julian Day) and time
(seconds and fraction past UTC midnight). The next
normally shows clock type and unit (but if you are running in strict
Classic compatibility mode it will show the magic clock address in
dotted-quad notation). The final field is the last timecode received from the
clock in decoded ASCII format, where meaningful. For 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.
+
  +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
-----------------------------------------------------------
+
[width="100%",cols="<34%,<33%,<33%"]
|==================================
|Item         |Units     |Description
|+50935+      |MJD       |date
|+75440.031+  |s         |time past midnight
|+0.000006019+|s         |clock offset
|+13.778+     |PPM       |drift (frequency offset)
|+0.000351733+|s         |RMS jitter
|+0.013380+   |PPM       |RMS frequency jitter (aka wander)
|+6+          |log~2~ s  |clock discipline loop time constant
|==================================
+
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.
+
  +protostats+;;
    Record significant peer and system events. Each significant
    event appends one line to the +protostats+ file set:
+
+49213 525.624 128.4.1.1 963a 8a+ _message_
+
[width="100%",cols="<34%,<33%,<33%"]
|====================================
|Item       |Units     |Description
|+49213+    |MJD       |date
|+525.624+  |s         |time past midnight
|+128.4.1.1+|IP        |source address (+0.0.0.0+ for system)
|+963a+     |code      |status word
|+8a+       |code      |event message code
|_message_  |text      |event message
|====================================
+
The event message code and _message_ field are described on the
"Event Messages and Status Words" page.
+
  +peerstats+;;
    Enables recording of peer statistics information. This includes
    statistics records of all peers of an 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 SPECTRACOM(4) 9714 -0.001605376 0.000000000
    0.001424877 0.000958674
---------------------------------------------------------------------------------
+
[width="100%",cols="<34%,<33%,<33%"]
|===================================================
|Item            |Units   |Description
|+48773+         |MJD     |date
|+10847.650+     |s       |time past midnight
|+SPECTRACOM(4)+ |        |clock name (unit) or source address
|+9714+          |hex     |status word
|+-0.001605376+  |s       |clock offset
|+0.000000000+   |s       |roundtrip delay
|+0.001424877+   |s       |dispersion
|+0.000958674+   |s       |RMS jitter
|===================================================
+
The first two fields show the date (Modified Julian Day) and time
(seconds and fraction past UTC midnight). The third field shows
the reference clock type and unit number (but if you are running in
the peer address in dotted-quad notation instead) The fourth field
is a status word, encoded in hex in the format described in
Appendix A of the NTP specification RFC 1305. The final four fields
show the offset, delay, dispersion and RMS jitter, all in seconds.
+
  +rawstats+;;
    Enables recording of raw-timestamp statistics information. This
    includes statistics records of all peers of an 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_:
+
---------------------------------------------------------------------------------
56285 54575.160 128.4.1.1 192.168.1.5 3565350574.400229473
    3565350574.442385200 3565350574.442436000
    3565350575.154505763 0 4 4 1 8 -21 0.000000 0.000320
    PPS 0
---------------------------------------------------------------------------------
+
[width="100%"]
|==============================================================================
|Item                |Units                             |Description
|56285               |MJD                               |date
|54575.160           |s                                 |time past midnight
|128.4.1.1           |IP                                |source address
|192.168.1.5         |IP                                |destination address
|3565350574.400229473|NTP s                             |origin timestamp
|3565350574.442385200|NTP s                             |receive timestamp
|3565350574.442436000|NTP s                             |transmit timestamp
|3565350575.154505763|NTP s                             |destination timestamp
|0                   |0: OK, 1: insert pending, 2: delete pending, 3: not synced  |leap warning indicator
|4                   |4 was current in 2012             |NTP version
|4                   |3: client, 4: server, 6: ntpq     |mode
|1                   |1-15, 16: not synced              |stratum
|8                   |log~2~ seconds                    |poll
|-21                 |log~2~ seconds                    |precision
|0.000000            |seconds                           |total roundtrip delay from the remote server to the primary reference clock
|0.000320            |seconds                           |total dispersion from the remote server to the primary reference clock
|.PPS.               |IP or text                        |refid, association ID
| 0                  |integer                           |lost packets since last response
|==============================================================================
+
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 identification 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.
+
  +sysstats+;;
    Enables recording of ntpd statistics counters on a periodic basis.
    Each hour a line of the following form is appended to the file
    generation set named _sysstats_:
+
-----------------------------------------------------------
50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 1
-----------------------------------------------------------
+
[width="100%",cols="<34%,<33%,<33%",]
|==================================================
|Item      |Units    |Description
|+50928+   |MJD      |date
|+2132.543+|s        |time past midnight
|+3600+    |s        |time since reset
|+81965+   |#        |packets received
|+0+       |#        |packets for this host
|+9546+    |#        |current versions
|+56+      |#        |old version
|+512+     |#        |access denied
|+540+     |#        |bad length or format
|+10+      |#        |bad authentication
|+4+       |#        |declined
|+147+     |#        |rate exceeded
|+1+       |#        |kiss-o'-death packets sent
|==================================================
+
The first two fields show the date (Modified Julian Day) and time
(seconds and fraction past UTC midnight). The remaining ten fields
show the statistics counter values accumulated since the last
generated line.
+
  +usestats+;;
    Enables recording of ntpd resource usage statistics.
    Each hour a line of the following form is appended to the file
    generation set named _usestats_:
+
-----------------------------------------------------------
57570 83399.541 3600 0.902 1.451 164 0 0 0 2328 64226 1 0 4308
-----------------------------------------------------------
+
[width="100%",cols="<34%,<33%,<33%",]
|==================================================
|Item       |Units    |Description
|+57570+    |MJD      |date
|+83399.541+|s        |time past midnight
|+3600+     |s        |time since reset
|+0.902+    |s        |ru_utime: CPU seconds - user mode
|+1.451+    |s        |ru_stime: CPU seconds - system
|+164+      |#        |ru_minflt: page faults - reclaim/soft (no I/O)
|+0+        |#        |ru_majflt: page faults - I/O
|+0+        |#        |ru_nswap: process swapped out
|+0+        |#        |ru_inblock: file blocks in
|+2328+     |#        |ru_oublock: file blocks out
|+64226+    |#        |ru_nvcsw: context switches, wait
|+1+        |#        |ru_nivcsw: context switches, preempts
|+0+        |#        |ru_nsignals: signals
|+4308+     |#        |ru_maxrss: resident set size, kilobytes
|==================================================
+
The first two fields show the date (Modified Julian Day) and time
(seconds and fraction past UTC midnight).  The ru_ tags are the
names from the rusage struct.  See +man getrusage+ for details.
(The NetBSD and FreeBSD man pages have more details.)
The maxrss column is the high water mark since the process was started.
The remaining fields show the values used since the last report.

// End of super-long series of statistics directives

[[statsdir]]+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]]+filegen+ _name_ [+file+ _filename_] [+type+ _typename_] [+link+ | +nolink+] [+enable+ | +disable+]::
    Configures setting of the 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 administrative 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
{ntpqman} 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_:
+
[width="100%"]
|====================================
|Attribute         |Description
|__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 ‘/’). 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:
      // The following are tables only because indent lists cannot be
      // nested more than 2 deep.
+
[width="100%"]
|====================================
|Attribute         |Description
|+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 {ntpdman} server
        incarnations. The set member filename is built by appending a
        ‘.’ to concatenated prefix and filename strings, and appending the
        decimal representation of the process ID of the
        {ntpdman} 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 ‘.’ 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.
|====================================
   +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.
      Information is only written to a file generation by specifying
      +enable+; output is prevented by specifying +disable+.

// end