doc/xml/AdminReference/sect1/afsmonitor.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="afsmonitor1">
   3   <refmeta>
   4     <refentrytitle>afsmonitor</refentrytitle>
   5     <manvolnum>1</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>afsmonitor</refname>
   9     <refpurpose>Monitors File Servers and Cache Managers</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">afsmonitor</emphasis> [<emphasis role="bold">initcmd</emphasis>] [-config &lt;<emphasis>configuration file</emphasis>&gt;]
  14         [<emphasis role="bold">-frequency</emphasis> &lt;<emphasis>poll frequency, in seconds</emphasis>&gt;]
  15         [<emphasis role="bold">-output</emphasis> &lt;<emphasis>storage file name</emphasis>&gt;] [<emphasis role="bold">-detailed</emphasis>]
  16         [<emphasis role="bold">-debug</emphasis> &lt;<emphasis>debug output file</emphasis>&gt;]
  17         [<emphasis role="bold">-fshosts</emphasis> &lt;<emphasis>list of file servers to monitor</emphasis>&gt;+]
  18         [<emphasis role="bold">-cmhosts</emphasis> &lt;<emphasis>list of cache managers to monitor</emphasis>&gt;+]
  19         [<emphasis role="bold">-buffers</emphasis> &lt;<emphasis>number of buffer slots</emphasis>&gt;] [<emphasis role="bold">-help</emphasis>]</para>
  20
  21     <para><emphasis role="bold">afsmonitor</emphasis> [<emphasis role="bold">i</emphasis>]  [-co &lt;<emphasis>configuration file</emphasis>&gt;]
  22         [<emphasis role="bold">-fr</emphasis> &lt;<emphasis>poll frequency, in seconds</emphasis>&gt;]
  23         [<emphasis role="bold">-o</emphasis> &lt;<emphasis>storage file name</emphasis>&gt;] [<emphasis role="bold">-det</emphasis>]
  24         [<emphasis role="bold">-deb</emphasis> &lt;<emphasis>debug output file</emphasis>&gt;]
  25         [<emphasis role="bold">-fs</emphasis> &lt;<emphasis>list of file servers to monitor</emphasis>&gt;+]
  26         [<emphasis role="bold">-cm</emphasis> &lt;<emphasis>list of cache managers to monitor</emphasis>&gt;+]
  27         [<emphasis role="bold">-b</emphasis> &lt;<emphasis>number of buffer slots</emphasis>&gt;] [<emphasis role="bold">-h</emphasis>]</para>
  28
  29   </refsect1>
  30   <refsect1>
  31     <title>Description</title>
  32     <para>The afsmonitor command initializes a program that gathers and displays
  33     statistics about specified File Server and Cache Manager operations. It
  34     allows the issuer to monitor, from a single location, a wide range of File
  35     Server and Cache Manager operations on any number of machines in both
  36     local and foreign cells.</para>
  37
  38     <para>There are 271 available File Server statistics and 571 available Cache
  39     Manager statistics, listed in the appendix about <emphasis role="bold">afsmonitor</emphasis> statistics
  40     in the <emphasis>IBM AFS Administration Guide</emphasis>. By default, the command displays
  41     all of the relevant statistics for the file server machines named by the
  42     <emphasis role="bold">-fshosts</emphasis> argument and the client machines named by the <emphasis role="bold">-cmhosts</emphasis>
  43     argument. To limit the display to only the statistics of interest, list
  44     them in the configuration file specified by the <emphasis role="bold">-config</emphasis> argument. In
  45     addition, use the configuration file for the following purposes:</para>
  46
  47     <itemizedlist>
  48       <listitem>
  49         <para>To set threshold values for any monitored statistic. When the value of a
  50         statistic exceeds the threshold, the <emphasis role="bold">afsmonitor</emphasis> command displays it in
  51         reverse video. There are no default threshold values.</para>
  52
  53       </listitem>
  54       <listitem>
  55         <para>To invoke a program or script automatically when a statistic exceeds its
  56         threshold. The AFS distribution does not include any such scripts.</para>
  57
  58       </listitem>
  59       <listitem>
  60         <para>To list the file server and client machines to monitor, instead of using
  61         the <emphasis role="bold">-fshosts</emphasis> and <emphasis role="bold">-cmhosts</emphasis> arguments.</para>
  62
  63       </listitem>
  64     </itemizedlist>
  65     <para>For a description of the configuration file, see <link linkend="afsmonitor5">afsmonitor(5)</link>.</para>
  66
  67   </refsect1>
  68   <refsect1>
  69     <title>Cautions</title>
  70     <para>The following software must be accessible to a machine where the
  71     <emphasis role="bold">afsmonitor</emphasis> program is running:</para>
  72
  73     <itemizedlist>
  74       <listitem>
  75         <para>The AFS xstat libraries, which the afsmonitor program uses to gather data.</para>
  76
  77       </listitem>
  78       <listitem>
  79         <para>The curses graphics package, which most UNIX distributions provide as a
  80         standard utility.</para>
  81
  82       </listitem>
  83     </itemizedlist>
  84     <para>The <emphasis role="bold">afsmonitor</emphasis> screens format successfully both on so-called dumb
  85     terminals and in windowing systems that emulate terminals. For the output
  86     to looks its best, the display environment needs to support reverse video
  87     and cursor addressing. Set the TERM environment variable to the correct
  88     terminal type, or to a value that has characteristics similar to the
  89     actual terminal type. The display window or terminal must be at least 80
  90     columns wide and 12 lines long.</para>
  91
  92     <para>The <emphasis role="bold">afsmonitor</emphasis> program must run in the foreground, and in its own
  93     separate, dedicated window or terminal. The window or terminal is
  94     unavailable for any other activity as long as the <emphasis role="bold">afsmonitor</emphasis> program is
  95     running. Any number of instances of the <emphasis role="bold">afsmonitor</emphasis> program can run on a
  96     single machine, as long as each instance runs in its own dedicated window
  97     or terminal. Note that it can take up to three minutes to start an
  98     additional instance.</para>
  99
 100   </refsect1>
 101   <refsect1>
 102     <title>Options</title>
 103     <variablelist>
 104       <varlistentry>
 105         <term><emphasis role="bold">initcmd</emphasis></term>
 106         <listitem>
 107           <para>Accommodates the command's use of the AFS command parser, and is optional.</para>
 108
 109         </listitem>
 110       </varlistentry>
 111       <varlistentry>
 112         <term><emphasis role="bold">-config</emphasis> &lt;<emphasis>file</emphasis>&gt;</term>
 113         <listitem>
 114           <para>Names the configuration file which lists the machines to monitor,
 115           statistics to display, and threshold values, if any. A partial pathname is
 116           interpreted relative to the current working directory. Provide this
 117           argument if not providing the <emphasis role="bold">-fshosts</emphasis> argument, <emphasis role="bold">-cmhosts</emphasis> argument,
 118           or neither. For instructions on creating this file, see the preceding
 119           <emphasis role="bold">DESCRIPTION</emphasis> section, and the section on the <emphasis role="bold">afsmonitor</emphasis> program in
 120           the <emphasis>IBM AFS Administration Guide</emphasis>.</para>
 121
 122         </listitem>
 123       </varlistentry>
 124       <varlistentry>
 125         <term><emphasis role="bold">-frequency</emphasis> &lt;<emphasis>poll frequency</emphasis>&gt;</term>
 126         <listitem>
 127           <para>Specifies in seconds how often the afsmonitor program probes the File
 128           Servers and Cache Managers. Valid values range from <computeroutput>1</computeroutput> to <computeroutput>86400</computeroutput>
 129           (which is 24 hours); the default value is <computeroutput>60</computeroutput>. This frequency applies to
 130           both File Servers and Cache Managers, but the <emphasis role="bold">afsmonitor</emphasis> program
 131           initiates the two types of probes, and processes their results,
 132           separately. The actual interval between probes to a host is the probe
 133           frequency plus the time required for all hosts to respond.</para>
 134
 135         </listitem>
 136       </varlistentry>
 137       <varlistentry>
 138         <term><emphasis role="bold">-output</emphasis> &lt;<emphasis>file</emphasis>&gt;</term>
 139         <listitem>
 140           <para>Names the file to which the afsmonitor program writes all of the
 141           statistics that it collects. By default, no output file is created. See
 142           the section on the <emphasis role="bold">afsmonitor</emphasis> command in the <emphasis>IBM AFS Administration
 143           Guide</emphasis> for information on this file.</para>
 144
 145         </listitem>
 146       </varlistentry>
 147       <varlistentry>
 148         <term><emphasis role="bold">-detailed</emphasis></term>
 149         <listitem>
 150           <para>Formats the information in the output file named by <emphasis role="bold">-output</emphasis> argument in
 151           a maximally readable format. Provide the <emphasis role="bold">-output</emphasis> argument along with
 152           this one.</para>
 153
 154         </listitem>
 155       </varlistentry>
 156       <varlistentry>
 157         <term><emphasis role="bold">-fshosts</emphasis> &lt;<emphasis>host</emphasis>&gt;+</term>
 158         <listitem>
 159           <para>Names one or more machines from which to gather File Server
 160           statistics. For each machine, provide either a fully qualified host name,
 161           or an unambiguous abbreviation (the ability to resolve an abbreviation
 162           depends on the state of the cell's name service at the time the command is
 163           issued). This argument can be combined with the <emphasis role="bold">-cmhosts</emphasis> argument, but
 164           not with the <emphasis role="bold">-config</emphasis> argument.</para>
 165
 166         </listitem>
 167       </varlistentry>
 168       <varlistentry>
 169         <term><emphasis role="bold">-cmhosts</emphasis> &lt;<emphasis>host</emphasis>&gt;+</term>
 170         <listitem>
 171           <para>Names one or more machines from which to gather Cache Manager
 172           statistics. For each machine, provide either a fully qualified host name,
 173           or an unambiguous abbreviation (the ability to resolve an abbreviation
 174           depends on the state of the cell's name service at the time the command is
 175           issued). This argument can be combined with the <emphasis role="bold">-fshosts</emphasis> argument, but
 176           not with the <emphasis role="bold">-config</emphasis> argument.</para>
 177
 178         </listitem>
 179       </varlistentry>
 180       <varlistentry>
 181         <term><emphasis role="bold">-buffers</emphasis> &lt;<emphasis>slots</emphasis>&gt;</term>
 182         <listitem>
 183           <para>Is nonoperational and provided to accommodate potential future
 184           enhancements to the program.</para>
 185
 186         </listitem>
 187       </varlistentry>
 188       <varlistentry>
 189         <term><emphasis role="bold">-help</emphasis></term>
 190         <listitem>
 191           <para>Prints the online help for this command. All other valid options are
 192           ignored.</para>
 193
 194         </listitem>
 195       </varlistentry>
 196     </variablelist>
 197   </refsect1>
 198   <refsect1>
 199     <title>Output</title>
 200     <para>The afsmonitor program displays its data on three screens:</para>
 201
 202     <variablelist>
 203       <varlistentry>
 204         <term>System Overview</term>
 205         <listitem>
 206           <para>This screen appears automatically when the <emphasis role="bold">afsmonitor</emphasis> program
 207           initializes. It summarizes separately for File Servers and Cache Managers
 208           the number of machines being monitored and how many of them have <emphasis>alerts</emphasis>
 209           (statistics that have exceeded their thresholds). It then lists the
 210           hostname and number of alerts for each machine being monitored, indicating
 211           if appropriate that a process failed to respond to the last probe.</para>
 212
 213         </listitem>
 214       </varlistentry>
 215       <varlistentry>
 216         <term>File Server</term>
 217         <listitem>
 218           <para>This screen displays File Server statistics for each file server machine
 219           being monitored. It highlights statistics that have exceeded their
 220           thresholds, and identifies machines that failed to respond to the last
 221           probe.</para>
 222
 223         </listitem>
 224       </varlistentry>
 225       <varlistentry>
 226         <term>Cache Managers</term>
 227         <listitem>
 228           <para>This screen displays Cache Manager statistics for each client machine
 229           being monitored. It highlights statistics that have exceeded their
 230           thresholds, and identifies machines that failed to respond to the last
 231           probe.</para>
 232
 233         </listitem>
 234       </varlistentry>
 235     </variablelist>
 236     <para>Fields at the corners of every screen display the following information:</para>
 237
 238     <itemizedlist>
 239       <listitem>
 240         <para>In the top left corner, the program name and version number.</para>
 241
 242       </listitem>
 243       <listitem>
 244         <para>In the top right corner, the screen name, current and total page numbers,
 245         and current and total column numbers. The page number (for example, <computeroutput>p. 1
 246         of 3</computeroutput>) indicates the index of the current page and the total number of
 247         (vertical) pages over which data is displayed. The column number (for
 248         example, <computeroutput>c. 1 of 235</computeroutput>) indicates the index of the current leftmost
 249         column and the total number of columns in which data appears. (The symbol
 250         <computeroutput>&gt;&gt;&gt;</computeroutput> indicates that there is additional data to the right; the
 251         symbol <computeroutput>&lt;&lt;&lt;</computeroutput> indicates that there is additional data to the
 252         left.)</para>
 253
 254       </listitem>
 255       <listitem>
 256         <para>In the bottom left corner, a list of the available commands. Enter the
 257         first letter in the command name to run that command. Only the currently
 258         possible options appear; for example, if there is only one page of data,
 259         the <computeroutput>next</computeroutput> and <computeroutput>prev</computeroutput> commands, which scroll the screen up and down
 260         respectively, do not appear. For descriptions of the commands, see the
 261         following section about navigating the display screens.</para>
 262
 263       </listitem>
 264       <listitem>
 265         <para>In the bottom right corner, the <computeroutput>probes</computeroutput> field reports how many times the
 266         program has probed File Servers (<computeroutput>fs</computeroutput>), Cache Managers (<computeroutput>cm</computeroutput>), or
 267         both. The counts for File Servers and Cache Managers can differ. The
 268         <computeroutput>freq</computeroutput> field reports how often the program sends probes.</para>
 269
 270       </listitem>
 271     </itemizedlist>
 272     <refsect2>
 273       <title>Navigating the afsmonitor Display Screens</title>
 274       <para>As noted, the lower left hand corner of every display screen displays the
 275       names of the commands currently available for moving to alternate screens,
 276       which can either be a different type or display more statistics or
 277       machines of the current type. To execute a command, press the lowercase
 278       version of the first letter in its name. Some commands also have an
 279       uppercase version that has a somewhat different effect, as indicated in
 280       the following list.</para>
 281
 282       <variablelist>
 283         <varlistentry>
 284           <term><computeroutput>cm</computeroutput></term>
 285           <listitem>
 286             <para>Switches to the <computeroutput>Cache Managers</computeroutput> screen. Available only on the <computeroutput>System
 287             Overview</computeroutput> and <computeroutput>File Servers</computeroutput> screens.</para>
 288
 289           </listitem>
 290         </varlistentry>
 291         <varlistentry>
 292           <term><computeroutput>fs</computeroutput></term>
 293           <listitem>
 294             <para>Switches to the <computeroutput>File Servers</computeroutput> screen. Available only on the <computeroutput>System
 295             Overview</computeroutput> and the <computeroutput>Cache Managers</computeroutput> screens.</para>
 296
 297           </listitem>
 298         </varlistentry>
 299         <varlistentry>
 300           <term><computeroutput>left</computeroutput></term>
 301           <listitem>
 302             <para>Scrolls horizontally to the left, to access the data columns situated to
 303             the left of the current set. Available when the <computeroutput>&lt;&lt;&lt;</computeroutput> symbol
 304             appears at the top left of the screen. Press uppercase <computeroutput>L</computeroutput> to scroll
 305             horizontally all the way to the left (to display the first set of data
 306             columns).</para>
 307
 308           </listitem>
 309         </varlistentry>
 310         <varlistentry>
 311           <term><computeroutput>next</computeroutput></term>
 312           <listitem>
 313             <para>Scrolls down vertically to the next page of machine names.  Available when
 314             there are two or more pages of machines and the final page is not
 315             currently displayed. Press uppercase <computeroutput>N</computeroutput> to scroll to the final page.</para>
 316
 317           </listitem>
 318         </varlistentry>
 319         <varlistentry>
 320           <term><computeroutput>oview</computeroutput></term>
 321           <listitem>
 322             <para>Switches to the <computeroutput>System Overview</computeroutput> screen. Available only on the <computeroutput>Cache
 323             Managers</computeroutput> and <computeroutput>File Servers</computeroutput> screens.</para>
 324
 325           </listitem>
 326         </varlistentry>
 327         <varlistentry>
 328           <term><computeroutput>prev</computeroutput></term>
 329           <listitem>
 330             <para>Scrolls up vertically to the previous page of machine names.  Available
 331             when there are two or more pages of machines and the first page is not
 332             currently displayed. Press uppercase <computeroutput>N</computeroutput> to scroll to the first page.</para>
 333
 334           </listitem>
 335         </varlistentry>
 336         <varlistentry>
 337           <term><computeroutput>right</computeroutput></term>
 338           <listitem>
 339             <para>Scrolls horizontally to the right, to access the data columns situated to
 340             the right of the current set. This command is available when the <computeroutput>&gt;&gt;&gt;</computeroutput> symbol appears at the upper right of the screen. Press uppercase <computeroutput>R</computeroutput>
 341             to scroll horizontally all the way to the right (to display the final set
 342             of data columns).</para>
 343
 344           </listitem>
 345         </varlistentry>
 346       </variablelist>
 347     </refsect2>
 348     <refsect2>
 349       <title>The System Overview Screen</title>
 350       <para>The <computeroutput>System Overview</computeroutput> screen appears automatically as the <emphasis role="bold">afsmonitor</emphasis>
 351       program initializes. This screen displays the status of as many File
 352       Server and Cache Manager processes as can fit in the current window;
 353       scroll down to access additional information.</para>
 354
 355       <para>The information on this screen is split into File Server information on
 356       the left and Cache Manager information on the right. The header for each
 357       grouping reports two pieces of information:</para>
 358
 359       <itemizedlist>
 360         <listitem>
 361           <para>The number of machines on which the program is monitoring the indicated
 362           process.</para>
 363
 364         </listitem>
 365         <listitem>
 366           <para>The number of alerts and the number of machines affected by them (an
 367           <emphasis>alert</emphasis> means that a statistic has exceeded its threshold or a process
 368           failed to respond to the last probe).</para>
 369
 370         </listitem>
 371       </itemizedlist>
 372       <para>A list of the machines being monitored follows. If there are any alerts on
 373       a machine, the number of them appears in square brackets to the left of
 374       the hostname. If a process failed to respond to the last probe, the
 375       letters <computeroutput>PF</computeroutput> (probe failure) appear in square brackets to the left of the
 376       hostname.</para>
 377
 378     </refsect2>
 379     <refsect2>
 380       <title>The File Servers Screen</title>
 381       <para>The <computeroutput>File Servers</computeroutput> screen displays the values collected at the most
 382       recent probe for File Server statistics.</para>
 383
 384       <para>A summary line at the top of the screen (just below the standard program
 385       version and screen title blocks) specifies the number of monitored File
 386       Servers, the number of alerts, and the number of machines affected by the
 387       alerts.</para>
 388
 389       <para>The first column always displays the hostnames of the machines running the
 390       monitored File Servers.</para>
 391
 392       <para>To the right of the hostname column appear as many columns of statistics
 393       as can fit within the current width of the display screen or window; each
 394       column requires space for 10 characters. The name of the statistic appears
 395       at the top of each column. If the File Server on a machine did not respond
 396       to the most recent probe, a pair of dashes (<computeroutput>--</computeroutput>) appears in each
 397       column. If a value exceeds its configured threshold, it is highlighted in
 398       reverse video. If a value is too large to fit into the allotted column
 399       width, it overflows into the next row in the same column.</para>
 400
 401     </refsect2>
 402     <refsect2>
 403       <title>The Cache Managers Screen</title>
 404       <para>The <computeroutput>Cache Managers</computeroutput> screen displays the values collected at the most
 405       recent probe for Cache Manager statistics.</para>
 406
 407       <para>A summary line at the top of the screen (just below the standard program
 408       version and screen title blocks) specifies the number of monitored Cache
 409       Managers, the number of alerts, and the number of machines affected by the
 410       alerts.</para>
 411
 412       <para>The first column always displays the hostnames of the machines running the
 413       monitored Cache Managers.</para>
 414
 415       <para>To the right of the hostname column appear as many columns of statistics
 416       as can fit within the current width of the display screen or window; each
 417       column requires space for 10 characters. The name of the statistic appears
 418       at the top of each column. If the Cache Manager on a machine did not
 419       respond to the most recent probe, a pair of dashes (<computeroutput>--</computeroutput>) appears in each
 420       column. If a value exceeds its configured threshold, it is highlighted in
 421       reverse video. If a value is too large to fit into the allotted column
 422       width, it overflows into the next row in the same column.</para>
 423
 424     </refsect2>
 425     <refsect2>
 426       <title>Writing to an Output File</title>
 427       <para>Include the <emphasis role="bold">-output</emphasis> argument to name the file into which the
 428       <emphasis role="bold">afsmonitor</emphasis> program writes all of the statistics it collects.  The
 429       output file can be useful for tracking performance over long periods of
 430       time, and enables the administrator to apply post-processing techniques
 431       that reveal system trends. The AFS distribution does not include any
 432       post-processing programs.</para>
 433
 434       <para>The output file is in ASCII format and records the same information as the
 435       <computeroutput>File Server</computeroutput> and <computeroutput>Cache Manager</computeroutput> display screens.  Each line in the
 436       file uses the following format to record the time at which the
 437       <emphasis role="bold">afsmonitor</emphasis> program gathered the indicated statistic from the Cache
 438       Manager (<computeroutput>CM</computeroutput>) or File Server (<computeroutput>FS</computeroutput>) running on the machine called
 439       <emphasis>host_name</emphasis>. If a probe failed, the error code <computeroutput>-1</computeroutput> appears in the
 440       <emphasis>statistic</emphasis> field.</para>
 441
 442 <programlisting>
 443    &amp;lt;time&amp;gt;  &amp;lt;host_name&amp;gt;  CM|FS   &amp;lt;statistic&amp;gt;
 444
 445 </programlisting>
 446         <para>If the administrator usually reviews the output file manually, rather than
 447         using it as input to an automated analysis program or script, including
 448         the <emphasis role="bold">-detail</emphasis> flag formats the data in a more easily readable form.</para>
 449
 450       </refsect2>
 451     </refsect1>
 452     <refsect1>
 453       <title>Examples</title>
 454       <para>For examples of commands, display screens, and configuration files, see
 455       the section about the <emphasis role="bold">afsmonitor</emphasis> program in the <emphasis>IBM AFS
 456       Administration Guide</emphasis>.</para>
 457
 458     </refsect1>
 459     <refsect1>
 460       <title>Privilege Required</title>
 461       <para>None</para>
 462
 463     </refsect1>
 464     <refsect1>
 465       <title>See Also</title>
 466       <para><link linkend="afsmonitor5">afsmonitor(5)</link>
 467       <link linkend="fstrace8">fstrace(8)</link>,
 468       <link linkend="scout1">scout(1)</link></para>
 469
 470     </refsect1>
 471     <refsect1>
 472       <title>Copyright</title>
 473       <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 474
 475       <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 476       converted from HTML to POD by software written by Chas Williams and Russ
 477       Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 478
 479     </refsect1>
 480   </refentry>