contrib/ntp/html/monopt.htm

   1 <html><head><title>
   2 Monitoring Options
   3 </title></head><body><h3>
   4 Monitoring Options
   5 </h3>
   6
   7 <img align=left src=pic/pogo8.gif><a href=http://www.eecis.udel.edu/~mills/pictures.htm>from <i>Pogo</i>, Walt Kelly</a>
   8
   9 <p>The pig watches the logs.
  10 <br clear=left><hr>
  11
  12 <h4>Monitoring Support</h4>
  13
  14 <tt>ntpd</tt> includes a comprehensive monitoring facility suitable for
  15 continuous, long term recording of server and client timekeeping
  16 performance. See the <tt>statistics</tt> command below for a listing and
  17 example of each type of statistics currently supported. Statistic files
  18 are managed using file generation sets and scripts in the ./scripts
  19 directory of this distribution. Using these facilities and Unix
  20 <tt>cron</tt> jobs, the datacan be automatically summarized and archived
  21 for retrospective analysis.
  22
  23 <h4>Monitoring Commands</h4>
  24
  25 <dl>
  26
  27 <dt><tt>statistics <I>name</I> [...]</tt></dt>
  28 <dd>Enables writing of statistics records. Currently, four kinds of
  29 <I><tt>name</tt></I>statistics are supported.</dd>
  30
  31 <dl>
  32
  33 <dt><tt>loopstats</tt></dt>
  34 <dd>Enables recording of loop filter statistics information. Each update
  35 of the local clock outputs a line of the following form to the file
  36 generation set named <tt>loopstats</tt>:</dd>
  37
  38 <p><dd><tt>50935 75440.031 0.000006019 13.778190 0.000351733 0.013380
  39 6</tt></dd>
  40
  41 <p><dd>The first two fields show the date (Modified Julian Day) and time
  42 (seconds and fraction past UTC midnight). The next five fields show time
  43 offset (seconds), frequency offset (parts per million - PPM), RMS jitter
  44 (seconds), Allan deviation (PPM) and clock discipline time
  45 constant.</dd>
  46
  47 <dt><tt>peerstats</tt></dt>
  48 <dd>Enables recording of peer statistics information. This includes
  49 statistics records of all peers of a NTP server and of special signals,
  50 where present and configured. Each valid update appends a line of the
  51 following form to the current element of a file generation set named
  52 <tt>peerstats</tt>:</dd>
  53
  54 <p><dd><tt>48773 10847.650 127.127.4.1 9714 -0.001605 0.00000
  55 0.00142</tt></dd>
  56
  57 <p><dd>The first two fields show the date (Modified Julian Day) and time
  58 (seconds and fraction past UTC midnight). The next two fields show the
  59 peer address in dotted-quad notation and status, respectively. The
  60 status field is encoded in hex in the format described in Appendix A of
  61 the NTP specification RFC 1305. The final three fields show the offset,
  62 delay and RMS jitter, all in seconds.</dd>
  63
  64 <dt><tt>clockstats</tt></dt>
  65 <dd>Enables recording of clock driver statistics information. Each
  66 update received from a clock driver appends a line of the following form
  67 to the file generation set named <tt>clockstats</tt>:</dd>
  68
  69 <p><dd><tt>49213 525.624 127.127.4.1 93 226 00:08:29.606 D</tt></dd>
  70 <p><dd>The first two fields show the date (Modified Julian Day) and time
  71 (seconds and fraction past UTC midnight). The next field shows the clock
  72 address in dotted-quad notation, The final field shows the last timecode
  73 received from the clock in decoded ASCII format, where meaningful. In
  74 some clock drivers a good deal of additional information can be gathered
  75 and displayed as well. See information specific to each clock for
  76 further details.</dd>
  77
  78 <dt><tt>rawstats</tt></dt>
  79 <dd>Enables recording of raw-timestamp statistics information. This
  80 includes statistics records of all peers of a NTP server and of special
  81 signals, where present and configured. Each NTP message received from a
  82 peer or clock driver appends a line of the following form to the file
  83 generation set named <tt>rawstats</tt>:</dd>
  84
  85 <p><dd><tt>50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000
  86 3102453281.58622800031 02453332.540806000 3102453332.541458000</tt></dd>
  87
  88 <p><dd>The first two fields show the date (Modified Julian Day) and time
  89 (seconds and fraction past UTC midnight). The next two fields show the
  90 remote peer or clock address followed by the local address in
  91 dotted-quad notation, The final four fields show the originate, receive,
  92 transmit and final NTP timestamps in order. The timestamp values are as
  93 received and before processing by the various data smoothing and
  94 mitigation algorithms.</dd>
  95
  96 </dl>
  97
  98 <dt><tt>statsdir <I>directory_path</I></tt></dt>
  99 <dd>Indicates the full path of a directory where statistics files should
 100 be created (see below). This keyword allows the (otherwise constant)
 101 <tt>filegen</tt> filename prefix to be modified for file generation
 102 sets, which is useful for handling statistics logs.</dd>
 103
 104 <dt><tt>filegen <I>name</I> [file <I>filename</I>] [type
 105 <I>typename</I>] [link | nolink] [enable | disable]</tt></dt>
 106 <dd>Configures setting of generation file set <I>name</I>. Generation
 107 file sets provide a means for handling files that are continuously
 108 growing during the lifetime of a server. Server statistics are a typical
 109 example for such files. Generation file sets provide access to a set of
 110 files used to store the actual data. At any time at most one element of
 111 the set is being written to. The type given specifies when and how data
 112 will be directed to a new element of the set. This way, information
 113 stored in elements of a file set that are currently unused are available
 114 for administrational operations without the risk of disturbing the
 115 operation of <tt>ntpd</tt>. (Most important: they can be removed to free
 116 space for new data produced.)</dd>
 117
 118 <dd>Note that this command can be sent from the <tt>ntpdc</tt> program
 119 running at a remote location.</dd>
 120
 121 <dl>
 122
 123 <dt><I><tt>name</tt></I></dt>
 124 <dd>This is the type of the statistics records, as shown in the
 125 <tt>statistics</tt> command.</dd>
 126
 127 </dl>
 128
 129 <dd><tt>file <I>filename</I></tt></dd>
 130
 131 <dl>
 132
 133 <dd>This is the file name for the statistics records. Filenames of set
 134 members are built from three concatenated elements
 135 <I><tt>prefix</tt></I>, <I><tt>filename</tt></I> and
 136 <I><tt>suffix</tt></I>:</dd>
 137
 138 <dl>
 139
 140 <dt><I><tt>prefix</tt></I></dt>
 141 <dd>This is a constant filename path. It is not subject to modifications
 142 via the <tt>filegen</tt> option. It is defined by the server, usually
 143 specified as a compile-time constant. It may, however, be configurable
 144 for individual file generation sets via other commands. For example, the
 145 prefix used with <tt>loopstats</tt> and <tt>peerstats</tt> generation
 146 can be configured using the <tt>statsdir</tt> option explained
 147 above.</dd>
 148
 149 <dt><I><tt>filename</tt></I></dt>
 150 <dd>This string is directly concatenated to the prefix mentioned above
 151 (no intervening <tt>/</tt> (slash)). This can be modified using the
 152 <tt>file</tt> argument to the <tt>filegen</tt> statement. No <tt>..</tt>
 153 elements are allowed in this component to prevent filenames referring to
 154 parts outside the filesystem hierarchy denoted by <tt>prefix</tt>.</dd>
 155
 156 <dt><I><tt>suffix</tt></I></dt>
 157 <dd>This part is reflects individual elements of a file set. It is
 158 generated according to the type of a file set.</dd>
 159
 160 </dl>
 161
 162 </dl>
 163
 164 <dd><tt>type <I>typename</I></tt></dd>
 165
 166 <dl>
 167
 168 <dd>A file generation set is characterized by its type. The following
 169 types are supported:</dd>
 170
 171 <dl>
 172
 173 <dt><tt>none</tt></dt>
 174 <dd>The file set is actually a single plain file.</dd>
 175
 176 <dt><tt>pid</tt></dt>
 177 <dd>One element of file set is used per incarnation of a <tt>ntpd</tt>
 178 server. This type does not perform any changes to file set members
 179 during runtime, however it provides an easy way of separating files
 180 belonging to different <tt>ntpd</tt> server incarnations. The set member
 181 filename is built by appending a <tt>.</tt> (dot) to concatenated
 182 <I>prefix</I> and <I>filename</I> strings, and appending the decimal
 183 representation of the process ID of the <tt>ntpd</tt> server
 184 process.</dd>
 185
 186 <dt><tt>day</tt></dt>
 187 <dd>One file generation set element is created per day. A day is defined
 188 as the period between 00:00 and 24:00 UTC. The file set member suffix
 189 consists of a <tt>.</tt> (dot) and a day specification in the form
 190 <tt>YYYYMMdd. YYYY</tt> is a 4-digit year number (e.g., 1992).
 191 <tt>MM</tt> is a two digit month number. <tt>dd</tt> is a two digit day
 192 number. Thus, all information written at 10 December 1992 would end up
 193 in a file named <tt><I>prefix filename</I>.19921210</tt>.</dd>
 194
 195 <dt><tt>week</tt></dt>
 196 <dd>Any file set member contains data related to a certain week of a
 197 year. The term week is defined by computing day-of-year modulo 7.
 198 Elements of such a file generation set are distinguished by appending
 199 the following suffix to the file set filename base: A dot, a 4-digit
 200 year number, the letter <tt>W</tt>, and a 2-digit week number. For
 201 example, information from January, 10th 1992 would end up in a file with
 202 suffix <tt>.1992W1</tt>.</dd>
 203
 204 <dt><tt>month</tt></dt>
 205 <dd>One generation file set element is generated per month. The file
 206 name suffix consists of a dot, a 4-digit year number, and a 2-digit
 207 month.</dd>
 208
 209 <dt><tt>year</tt></dt>
 210 <dd>One generation file element is generated per year. The filename
 211 suffix consists of a dot and a 4 digit year number.</dd>
 212
 213 <dt><tt>age</tt></dt>
 214 <dd>This type of file generation sets changes to a new element of the
 215 file set every 24 hours of server operation. The filename suffix
 216 consists of a dot, the letter <tt>a</tt>, and an 8-digit number. This
 217 number is taken to be the number of seconds the server is running at the
 218 start of the corresponding 24-hour period. Information is only written
 219 to a file generation by specifying <tt>enable</tt>; output is prevented
 220 by specifying <tt>disable</tt>.</dd>
 221
 222 </dl>
 223
 224 </dl>
 225
 226 <dd><tt>link | nolink</tt></dd>
 227
 228 <dl>
 229
 230 <dd>It is convenient to be able to access the current element of a file
 231 generation set by a fixed name. This feature is enabled by specifying
 232 <tt>link</tt> and disabled using <tt>nolink</tt>. If <tt>link</tt> is
 233 specified, a hard link from the current file set element to a file
 234 without suffix is created. When there is already a file with this name
 235 and the number of links of this file is one, it is renamed appending a
 236 dot, the letter <tt>C</tt>, and the pid of the <tt>ntpd</tt> server
 237 process. When the number of links is greater than one, the file is
 238 unlinked. This allows the current file to be accessed by a constant
 239 name.</dd>
 240
 241 </dl>
 242
 243 <dd><tt>enable | disable</tt></dd>
 244
 245 <dl>
 246
 247 <dd>Enables or disables the recording function.</dd>
 248
 249 </dl>
 250
 251 </dl>
 252
 253 <hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a
 254 href=mailto:mills@udel.edu> David L. Mills &lt;mills@udel.edu&gt;</a>
 255 </address></a></body></html>