contrib/ofed/management/opensm/doc/performance-manager-HOWTO.txt

   1 OpenSM Performance manager HOWTO
   2 ================================
   3
   4 Introduction
   5 ============
   6
   7 OpenSM now includes a performance manager which collects Port counters from
   8 the subnet and stores them internally in OpenSM.
   9
  10 Some of the features of the performance manager are:
  11
  12         1) Collect port data and error counters per v1.2 spec and store in
  13            64bit internal counts.
  14         2) Automatic reset of counters when they reach approximatly 3/4 full.
  15            (While not guarenteeing that counts will not be missed this does
  16            keep counts incrementing as best as possible given the current
  17            hardware limitations.)
  18         3) Basic warnings in the OpenSM log on "critical" errors like symbol
  19            errors.
  20         4) Automatically detects "outside" resets of counters and adjusts to
  21            continue collecting data.
  22         5) Can be run when OpenSM is in standby or inactive states.
  23
  24 Known issues are:
  25
  26         1) Data counters will be lost on high data rate links.  Sweeping the
  27            fabric fast enough for a DDR link is not practical.
  28         2) Default partition support only.
  29
  30
  31 Setup and Usage
  32 ===============
  33
  34 Using the Performance Manager consists of 3 steps:
  35
  36         1) compiling in support for the perfmgr (Optionally: the console
  37            socket as well)
  38         2) enabling the perfmgr and console in opensm.conf
  39         3) retrieving data which has been collected.
  40            3a) using console to "dump data"
  41            3b) using a plugin module to store the data to your own
  42                "database"
  43
  44 Step 1: Compile in support for the Performance Manager
  45 ------------------------------------------------------
  46
  47 Because of the performance manager's experimental status, it is not enabled at
  48 compile time by default.  (This will hopefully soon change as more people use
  49 it and confirm that it does not break things...  ;-)  The configure option is
  50 "--enable-perf-mgr".
  51
  52 At this time it is really best to enable the console socket option as well.
  53 OpenSM can be run in an "interactive" mode.  But with the console socket option
  54 turned on one can also make a connection to a running OpenSM.  The console
  55 option is "--enable-console-socket".  This option requires the use of
  56 tcp_wrappers to ensure security.  Please be aware of your configuration for
  57 tcp_wrappers as the commands presented in the console can affect the operation
  58 of your subnet.
  59
  60 The following configure line includes turning on the performance manager as
  61 well as the console:
  62
  63         ./configure --enable-perf-mgr --enable-console-socket
  64
  65
  66 Step 2: Enable the perfmgr and console in opensm.conf
  67 -----------------------------------------------------
  68
  69 Turning the Perfmorance Manager on is pretty easy, set the following options in
  70 the opensm.conf config file.  (Default location is
  71 /usr/local/etc/opensm/opensm.conf)
  72
  73         # Turn it all on.
  74         perfmgr TRUE
  75
  76         # sweep time in seconds
  77         perfmgr_sweep_time_s 180
  78
  79         # Dump file to dump the events to
  80         event_db_dump_file /var/log/opensm_port_counters.log
  81
  82 Also enable the console socket and configure the port for it to listen to if
  83 desired.
  84
  85         # console [off|local|socket]
  86         console socket
  87
  88         # Telnet port for console (default 10000)
  89         console_port 10000
  90
  91 As noted above you also need to set up tcp_wrappers to prevent unauthorized
  92 users from connecting to the console.[*]
  93
  94         [*] As an alternate you can use the loopback mode but I noticed when
  95         writing this (OpenSM v3.1.10; OFED 1.3) that there are some bugs in
  96         specifying the loopback mode in the opensm.conf file.  Look for this to
  97         be fixed in newer versions.
  98
  99         [**] Also you could use "local" but this is only useful if you run
 100         OpenSM in the foreground of a terminal.  As OpenSM is usually started
 101         as a daemon I left this out as an option.
 102
 103 Step 3: retrieve data which has been collected
 104 ----------------------------------------------
 105
 106 Step 3a: Using console dump function
 107 ------------------------------------
 108
 109 The console command "perfmgr dump_counters" will dump counters to the file
 110 specified in the opensm.conf file.  In the example above
 111 "/var/log/opensm_port_counters.log"
 112
 113 Example output is below:
 114
 115 <snip>
 116 "SW1 wopr ISR9024D (MLX4 FW)" 0x8f10400411f56 port 1 (Since Mon May 12 13:27:14 2008)
 117      symbol_err_cnt       : 0
 118      link_err_recover     : 0
 119      link_downed          : 0
 120      rcv_err              : 0
 121      rcv_rem_phys_err     : 0
 122      rcv_switch_relay_err : 2
 123      xmit_discards        : 0
 124      xmit_constraint_err  : 0
 125      rcv_constraint_err   : 0
 126      link_integrity_err   : 0
 127      buf_overrun_err      : 0
 128      vl15_dropped         : 0
 129      xmit_data            : 470435
 130      rcv_data             : 405956
 131      xmit_pkts            : 8954
 132      rcv_pkts             : 6900
 133      unicast_xmit_pkts    : 0
 134      unicast_rcv_pkts     : 0
 135      multicast_xmit_pkts  : 0
 136      multicast_rcv_pkts   : 0
 137 </snip>
 138
 139
 140 Step 3b: Using a plugin module
 141 ------------------------------
 142
 143 If you want a more automated method of retrieving the data OpenSM provides a
 144 plugin interface to extend OpenSM.  The header file is osm_event_plugin.h.
 145 The functions you register with this interface will be called when data is
 146 collected.  You can then use that data as appropriate.
 147
 148 An example plugin can be configured at compile time using the
 149 "--enable-default-event-plugin" option on the configure line.  This plugin is
 150 very simple.  It logs "events" recieved from the performance manager to a log
 151 file.  I don't recomend using this directly but rather use it as a templat to
 152 create your own plugin.
 153