external/bsd/ntp/dist/html/monopt.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
   5 <meta name="generator" content="HTML Tidy, see www.w3.org">
   6 <title>Monitoring Options</title>
   7 <link href="scripts/style.css" type="text/css" rel="stylesheet">
   8 </head>
   9 <body>
  10 <h3>Monitoring Options</h3>
  11 <img src="pic/pogo8.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>,
  12 Walt Kelly</a>
  13 <p>Pig was hired to watch the logs.</p>
  14 <p>Last update:
  15         <!-- #BeginDate format:En2m -->10-May-2009  16:19<!-- #EndDate -->
  16         UTC</p>
  17 <br clear="left">
  18 <h4>Related Links</h4>
  19 <script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
  20 <script type="text/javascript" language="javascript" src="scripts/monopt.txt"></script>
  21 <h4>Table of Contents</h4>
  22 <ul>
  23         <li class="inline"><a href="#intro">introduction</a></li>
  24         <li class="inline"><a href="#cmd">Monitoring Options</a></li>
  25         <li class="inline"><a href="#types">File Set Types</a></li>
  26 </ul>
  27 <hr>
  28 <h4 id="intro">Introduction</h4>
  29 <p>The <tt>ntpd</tt> includes a comprehensive monitoring facility which collects
  30         statistical data of various types and writes the data to files associated with
  31         each type at defined events or intervals. The files associated with a particular
  32         type are collectively called the generation file set for that type. The files
  33         in the file set are the members of that set.</p>
  34 <p>File sets have names specific to the type and generation epoch. The names
  35         are constructed from three concatenated elements <i><tt>prefix</tt></i>, <i><tt>filename</tt></i> and <i><tt>suffix</tt></i>:</p>
  36 <dl>
  37         <dt><i><tt>prefix</tt></i></dt>
  38         <dd>The directory path specified in the <tt>statsdir</tt> command.</dd>
  39         <dt><i><tt>name</tt></i></dt>
  40         <dd>The name specified by the <tt>file</tt> option of the <tt>filegen</tt> command.</dd>
  41         <dt><i><tt>suffix</tt></i></dt>
  42         <dd>A string of elements bdginning with . (dot) followed by a number of elements
  43                 depending on the file set type.</dd>
  44 </dl>
  45 <p>Statistics files can be managed using scripts, examples of which are in the <tt>./scripts</tt> directory.
  46         Using these or similar scripts and Unix <tt>cron</tt> jobs, the files can be
  47         automatically summarized and archived for retrospective analysis.</p>
  48 <h4 id="cmd">Monitoring Commands</h4>
  49 <dl>
  50         <dt id="filegen"><tt>filegen <i>name</i> file <i>filename</i> [type <i>type</i>]
  51                         [link | nolink] [enable | disable]</tt></dt>
  52         <dd>
  53                 <dl>
  54                         <dt><i><tt>name</tt></i></dt>
  55                         <dd>Specifies the file set type from the list in the next section.</dd>
  56                         <dt><tt>file <i>filename</i></tt></dt>
  57                         <dd>Specfies the file set name.</dd>
  58                         <dt><tt>type <i>typename</i></tt></dt>
  59                         <dd>Specifies the file set interval. The following intervals are supported
  60                                 with default <tt>day</tt>:</dd>
  61                         <dd>
  62                                 <dl>
  63                                         <dt><tt>none</tt></dt>
  64                                         <dd>The file set is actually a single plain file.</dd>
  65                                         <dt><tt>pid</tt></dt>
  66                                         <dd>One file set member is created for every incarnation of <tt>ntpd</tt>.
  67                                                 The file name suffix is the string .<tt>n</tt>, where <tt>n</tt> is the
  68                                                 process ID of the <tt>ntpd</tt> server process.</dd>
  69                                         <dt><tt>day</tt></dt>
  70                                         <dd>One file set member is created per day. A day is defined as the period
  71                                                 between 00:00 and 23:59 UTC. The file name suffix is the string .<tt>yyyymmdd</tt>,
  72                                                 where <tt>yyyy</tt> is the year, <tt>mm</tt> the month of the year and <tt>dd</tt> the
  73                                                 day of the month. Thus, member created on 10 December 1992 would have suffix <tt>.19921210</tt>.</dd>
  74                                         <dt><tt>week</tt></dt>
  75                                         <dd>One file set member is created per week. The week is defined as the
  76                                                 day of year modulo 7. The file name suffix is the string .<tt>yyyyWww</tt>,
  77                                                 where <tt>yyyy</tt> is the year, <tt>W</tt> stands for itself and <tt>ww</tt> the
  78                                                 week number starting from 0. For example, The member created on 10 January
  79                                                 1992 would have suffix <tt>.1992W1</tt>.</dd>
  80                                         <dt><tt>month</tt></dt>
  81                                         <dd>One file set member is created per month. The file name suffix is the
  82                                                 string .<tt>yyyymm</tt>, where <tt>yyyy</tt> is the year and <tt>mm</tt> the
  83                                                 month of the year starting from 1. For example, The member created on 10
  84                                                 January 1992 would have suffix <tt>.199201</tt>.</dd>
  85                                         <dt><tt>year</tt></dt>
  86                                         <dd>One file set member is generated per year. The file name suffix is the
  87                                                 string .<tt>yyyy</tt>, where <tt>yyyy</tt> is the year. For example, The
  88                                                 member created on 1 January 1992 would have suffix <tt>.1992</tt>.</dd>
  89                                         <dt><tt>age</tt></dt>
  90                                         <dd>One file set member is generated every 24 hours of <tt>ntpd</tt> operation.
  91                                                 The filename suffix is the string <tt>.adddddddd</tt>, where <tt>a</tt> stands
  92                                                 for itself and <tt>dddddddd</tt> is the <tt>ntpd</tt> running time in seconds
  93                                                 at the start of the corresponding 24-hour period.</dd>
  94                                 </dl>
  95                         </dd>
  96                         <dt><tt>link | nolink</tt></dt>
  97                         <dd>It is convenient to be able to access the current file set members by
  98                                 file name, but without the suffix. This feature is enabled by <tt>link</tt> and
  99                                 disabled by <tt>nolink</tt>. If enabled, which is the default, a hard link
 100                                 from the current file set member to a file without suffix is created. When
 101                                 there is already a file with this name and the number of links to this file
 102                                 is one, it is renamed by appending a dot, the letter <tt>C</tt>, and the
 103                                 pid of the <tt>ntpd</tt> server process. When the number of links is greater
 104                                 than one, the file is unlinked. This allows the current file to be accessed
 105                                 by a constant name.</dd>
 106                         <dt><tt>enable | disable</tt></dt>
 107                         <dd>Enable or disable the recording function, with default <tt>enable</tt>.
 108                                 These options are intended for remote configutation commands.</dd>
 109                 </dl>
 110         </dd>
 111         <dt><tt>statsdir <i>directory_path</i></tt></dt>
 112         <dd>Specify the directory path prefix for statistics file names.</dd>
 113 </dl>
 114 <h4 id="types">File Set Types</h4>
 115 <dl>
 116         <dt><tt>clockstats</tt></dt>
 117         <dd>Record reference clock statistics. Each update received from a reference
 118                 clock driver appends one line to the <tt>clockstats</tt> file set:</dd>
 119         <dd><tt>49213 525.624 127.127.4.1 93 226 00:08:29.606 D</tt></dd>
 120         <dd>
 121                 <table width="100%" border="1" cellspacing="2" cellpadding="2">
 122                         <tr>
 123                                 <td>Item</td>
 124                                 <td>Units</td>
 125                                 <td>Description</td>
 126                         </tr>
 127                         <tr>
 128                                 <td><tt>49213</tt></td>
 129                                 <td>MJD</td>
 130                                 <td>date</td>
 131                         </tr>
 132                         <tr>
 133                                 <td><tt>525.624</tt></td>
 134                                 <td>s</td>
 135                                 <td>time past midnight</td>
 136                         </tr>
 137                         <tr>
 138                                 <td><tt>127.127.4.1</tt></td>
 139                                 <td>IP</td>
 140                                 <td>reference clock address</td>
 141                         </tr>
 142                         <tr>
 143                                 <td><tt><i>message</i></tt></td>
 144                                 <td>text</td>
 145                                 <td>log message</td>
 146                         </tr>
 147                 </table>
 148         </dd>
 149         <dd>The <tt><i>message</i></tt> field includes the last timecode received in
 150                 decoded ASCII format, where meaningful. In some cases a good deal of additional
 151                 information is displayed. See information specific to each reference clock
 152                 for further details.</dd>
 153         <dt><tt>cryptostats</tt></dt>
 154         <dd>Record significant events in the Autokey protocol. This option requires
 155                 the OpenSSL cryptographic software library. Each event appends one line to
 156                 the <tt>cryptostats</tt> file set:</dd>
 157         <dd><tt>49213 525.624 128.4.1.1 <i>message</i></tt></dd>
 158         <dd>
 159                 <table width="100%" border="1" cellspacing="2" cellpadding="2">
 160                         <tr>
 161                                 <td>Item</td>
 162                                 <td>Units</td>
 163                                 <td>Description</td>
 164                         </tr>
 165                         <tr>
 166                                 <td><tt>49213</tt></td>
 167                                 <td>MJD</td>
 168                                 <td>date</td>
 169                         </tr>
 170                         <tr>
 171                                 <td><tt>525.624</tt></td>
 172                                 <td>s</td>
 173                                 <td>time past midnight</td>
 174                         </tr>
 175                         <tr>
 176                                 <td><tt>128.4.1.1</tt></td>
 177                                 <td>IP</td>
 178                                 <td>source address (<tt>0.0.0.0</tt> for system)</td>
 179                         </tr>
 180                         <tr>
 181                                 <td><tt><i>message</i></tt></td>
 182                                 <td>text</td>
 183                                 <td>log message</td>
 184                         </tr>
 185                 </table>
 186         </dd>
 187         <dd>The <tt><i>message</i></tt> field includes the message type and certain
 188                 ancillary information. See the <a href="authopt.html">Authentication Options</a> page
 189                 for further information.</dd>
 190         <dt><tt>loopstats</tt></dt>
 191         <dd>Record clock discipline loop statistics. Each system clock update appends
 192                 one line to the <tt>loopstats</tt> file set:</dd>
 193         <dd><tt>50935 75440.031 0.000006019 13.778 0.000351733 0.013380 6</tt></dd>
 194         <dd>
 195                 <table width="100%" border="1" cellspacing="2" cellpadding="2">
 196                         <tr>
 197                                 <td>Item</td>
 198                                 <td>Units</td>
 199                                 <td>Description</td>
 200                         </tr>
 201                         <tr>
 202                                 <td><tt>50935</tt></td>
 203                                 <td>MJD</td>
 204                                 <td>date</td>
 205                         </tr>
 206                         <tr>
 207                                 <td><tt>75440.031</tt></td>
 208                                 <td>s</td>
 209                                 <td>time past midnight</td>
 210                         </tr>
 211                         <tr>
 212                                 <td><tt>0.000006019</tt></td>
 213                                 <td>s</td>
 214                                 <td>clock offset</td>
 215                         </tr>
 216                         <tr>
 217                                 <td><tt>13.778</tt></td>
 218                                 <td>PPM</td>
 219                                 <td>frequency offset</td>
 220                         </tr>
 221                         <tr>
 222                                 <td><tt>0.000351733</tt></td>
 223                                 <td>s</td>
 224                                 <td>RMS jitter</td>
 225                         </tr>
 226                         <tr>
 227                                 <td><tt>0.013380</tt></td>
 228                                 <td>PPM</td>
 229                                 <td>RMS&nbsp;frequency jitter (aka wander)</td>
 230                         </tr>
 231                         <tr>
 232                                 <td><tt>6 </tt></td>
 233                                 <td>log<sub>2</sub> s</td>
 234                                 <td>clock discipline loop time constant</td>
 235                         </tr>
 236                 </table>
 237         </dd>
 238         <dt><tt>peerstats</tt></dt>
 239         <dd>Record peer statistics. Each NTP packet or reference clock update received
 240                 appends one line to the <tt>peerstats</tt> file set:</dd>
 241         <dd><tt>48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877
 242                         0.000958674</tt></dd>
 243         <dd>
 244                 <table width="100%" border="1" cellspacing="2" cellpadding="2">
 245                         <tr>
 246                                 <td>Item</td>
 247                                 <td>Units</td>
 248                                 <td>Description</td>
 249                         </tr>
 250                         <tr>
 251                                 <td><tt>48773</tt></td>
 252                                 <td>MJD</td>
 253                                 <td>date</td>
 254                         </tr>
 255                         <tr>
 256                                 <td><tt>10847.650</tt></td>
 257                                 <td>s</td>
 258                                 <td>time past midnight</td>
 259                         </tr>
 260                         <tr>
 261                                 <td><tt>127.127.4.1</tt></td>
 262                                 <td>IP</td>
 263                                 <td>source address</td>
 264                         </tr>
 265                         <tr>
 266                                 <td><tt>9714</tt></td>
 267                                 <td>hex</td>
 268                                 <td>status word</td>
 269                         </tr>
 270                         <tr>
 271                                 <td><tt>-0.001605376</tt></td>
 272                                 <td>s</td>
 273                                 <td>clock offset</td>
 274                         </tr>
 275                         <tr>
 276                                 <td><tt>0.000000000 </tt></td>
 277                                 <td>s</td>
 278                                 <td>roundtrip delay</td>
 279                         </tr>
 280                         <tr>
 281                                 <td><tt>0.001424877</tt></td>
 282                                 <td>s</td>
 283                                 <td>dispersion</td>
 284                         </tr>
 285                         <tr>
 286                                 <td><tt>0.000958674</tt></td>
 287                                 <td>s</td>
 288                                 <td>RMS&nbsp;jitter</td>
 289                         </tr>
 290                 </table>
 291         </dd>
 292         <dd>The status field is encoded in hex format as described in Appendix B of
 293                 the NTP specification RFC 1305.</dd>
 294         <dt><tt>protostats</tt></dt>
 295         <dd>Record significant peer, system and [rptpcp; events. Each significant event
 296                 appends one line to the <tt>protostats</tt> file set:</dd>
 297         <dd><tt>49213 525.624 128.4.1.1 963a 8a <i>message</i></tt></dd>
 298         <dd>
 299                 <table width="100%" border="1" cellspacing="2" cellpadding="2">
 300                         <tr>
 301                                 <td>Item</td>
 302                                 <td>Units</td>
 303                                 <td>Description</td>
 304                         </tr>
 305                         <tr>
 306                                 <td><tt>49213</tt></td>
 307                                 <td>MJD</td>
 308                                 <td>date</td>
 309                         </tr>
 310                         <tr>
 311                                 <td><tt>525.624</tt></td>
 312                                 <td>s</td>
 313                                 <td>time past midnight</td>
 314                         </tr>
 315                         <tr>
 316                                 <td><tt>128.4.1.1</tt></td>
 317                                 <td>IP</td>
 318                                 <td>source address (<tt>0.0.0.0</tt> for system)</td>
 319                         </tr>
 320                         <tr>
 321                                 <td><tt>963a</tt></td>
 322                                 <td>code</td>
 323                                 <td>status word</td>
 324                         </tr>
 325                         <tr>
 326                                 <td><tt>8a</tt></td>
 327                                 <td>code</td>
 328                                 <td>event message code</td>
 329                         </tr>
 330                         <tr>
 331                                 <td><tt><i>message</i></tt></td>
 332                                 <td>text</td>
 333                                 <td>event message</td>
 334                         </tr>
 335                 </table>
 336         </dd>
 337         <dd>The event message code and <tt><i>message</i></tt> field are described on
 338                 the <a href="decode.html">Event Messages and Status Words</a> page.</dd>
 339         <dt><tt>rawstats</tt></dt>
 340         <dd>Record timestamp statistics. Each NTP packet received appends one line to
 341                 the <tt>rawstats</tt> file set:</dd>
 342         <dd><tt>50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031
 343                         02453332.540806000 3102453332.541458000</tt></dd>
 344         <dd>
 345                 <table width="100%" border="1" cellspacing="2" cellpadding="2">
 346                         <tr>
 347                                 <td>Item</td>
 348                                 <td>Units</td>
 349                                 <td>Description</td>
 350                         </tr>
 351                         <tr>
 352                                 <td><tt>50928</tt></td>
 353                                 <td>MJD</td>
 354                                 <td>date</td>
 355                         </tr>
 356                         <tr>
 357                                 <td><tt>2132.543</tt></td>
 358                                 <td>s</td>
 359                                 <td>time past midnight</td>
 360                         </tr>
 361                         <tr>
 362                                 <td><tt>128.4.1.1</tt></td>
 363                                 <td>IP</td>
 364                                 <td>source address</td>
 365                         </tr>
 366                         <tr>
 367                                 <td><tt>128.4.1.20</tt></td>
 368                                 <td>IP</td>
 369                                 <td>destination address</td>
 370                         </tr>
 371                         <tr>
 372                                 <td><tt>3102453281.584327000</tt></td>
 373                                 <td>NTP&nbsp;s</td>
 374                                 <td>origin timestamp</td>
 375                         </tr>
 376                         <tr>
 377                                 <td><tt>3102453281.586228000</tt></td>
 378                                 <td>NTP s</td>
 379                                 <td>receive timestamp</td>
 380                         </tr>
 381                         <tr>
 382                                 <td><tt>3102453332.540806000 </tt></td>
 383                                 <td>NTP s</td>
 384                                 <td>transmit timestamp</td>
 385                         </tr>
 386                         <tr>
 387                                 <td><tt>3102453332.541458000</tt></td>
 388                                 <td>NTP&nbsp;s</td>
 389                                 <td>destination timestamp</td>
 390                         </tr>
 391                 </table>
 392         </dd>
 393         <dt><tt>sysstats</tt></dt>
 394         <dd>Record system statistics. Each hour one line is appended to the <tt>sysstats</tt> file
 395                 set in the following format:</dd>
 396         <dd><tt>50928 2132.543 3600 81965 0 9546 56 512 540 10 4 147 1</tt></dd>
 397         <dd>
 398                 <table width="100%" border="1" cellspacing="2" cellpadding="2">
 399                         <tr>
 400                                 <td>Item</td>
 401                                 <td>Units</td>
 402                                 <td>Description</td>
 403                         </tr>
 404                         <tr>
 405                                 <td><tt>50928</tt></td>
 406                                 <td>MJD</td>
 407                                 <td>date</td>
 408                         </tr>
 409                         <tr>
 410                                 <td><tt>2132.543</tt></td>
 411                                 <td>s</td>
 412                                 <td>time past midnight</td>
 413                         </tr>
 414                         <tr>
 415                                 <td><tt>3600</tt></td>
 416                                 <td>s</td>
 417                                 <td>time since reset</td>
 418                         </tr>
 419                         <tr>
 420                                 <td><tt>81965</tt></td>
 421                                 <td>#</td>
 422                                 <td>packets received</td>
 423                         </tr>
 424                         <tr>
 425                                 <td><tt>0</tt></td>
 426                                 <td>#</td>
 427                                 <td>packets for this host</td>
 428                         </tr>
 429                         <tr>
 430                                 <td><tt>9546</tt></td>
 431                                 <td>#</td>
 432                                 <td>current versions</td>
 433                         </tr>
 434                         <tr>
 435                                 <td><tt>56</tt></td>
 436                                 <td>#</td>
 437                                 <td>old version</td>
 438                         </tr>
 439                         <tr>
 440                                 <td><tt>512</tt></td>
 441                                 <td>#</td>
 442                                 <td>access denied</td>
 443                         </tr>
 444                         <tr>
 445                                 <td><tt>540</tt></td>
 446                                 <td>#</td>
 447                                 <td>bad length or format</td>
 448                         </tr>
 449                         <tr>
 450                                 <td><tt>10</tt></td>
 451                                 <td>#</td>
 452                                 <td>bad authentication</td>
 453                         </tr>
 454                         <tr>
 455                                 <td><tt>4</tt></td>
 456                                 <td>#</td>
 457                                 <td>declined</td>
 458                         </tr>
 459                         <tr>
 460                                 <td><tt>147</tt></td>
 461                                 <td>#</td>
 462                                 <td>rate exceeded</td>
 463                         </tr>
 464                         <tr>
 465                                 <td><tt>1</tt></td>
 466                                 <td>#</td>
 467                                 <td>kiss-o'-death packets sent</td>
 468                         </tr>
 469                 </table>
 470         </dd>
 471         <dt><tt>timingstats</tt></dt>
 472         <dd>(Only available when the deamon is compiled with process time debugging
 473                 support (--enable-debug-timing - costs performance). Record processing time
 474                 statistics for various selected code paths.</dd>
 475         <dd><tt>53876 36.920 10.0.3.5 1 0.000014592 input processing delay</tt></dd>
 476         <dd>
 477                 <table width="100%" border="1" cellspacing="2" cellpadding="2">
 478                         <tr>
 479                                 <td>Item</td>
 480                                 <td>Units</td>
 481                                 <td>Description</td>
 482                         </tr>
 483                         <tr>
 484                                 <td><tt>53876</tt></td>
 485                                 <td>MJD</td>
 486                                 <td>date</td>
 487                         </tr>
 488                         <tr>
 489                                 <td><tt>36.920</tt></td>
 490                                 <td>s</td>
 491                                 <td>time past midnight</td>
 492                         </tr>
 493                         <tr>
 494                                 <td><tt>10.0.3.5</tt></td>
 495                                 <td>IP</td>
 496                                 <td>server address</td>
 497                         </tr>
 498                         <tr>
 499                                 <td><tt>1</tt></td>
 500                                 <td>#</td>
 501                                 <td>event count</td>
 502                         </tr>
 503                         <tr>
 504                                 <td><tt>0.000014592</tt></td>
 505                                 <td>s</td>
 506                                 <td>total time</td>
 507                         </tr>
 508                         <tr>
 509                                 <td><tt><i>message</i></tt></td>
 510                                 <td>text</td>
 511                                 <td>code path description (see source)</td>
 512                         </tr>
 513                 </table>
 514         </dd>
 515 </dl>
 516 <hr>
 517 <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
 518 </body>
 519 </html>