TAO/docs/notification/monitor.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <html>
   3 <head>
   4   <title>Notification Service Monitor</title>
   5   <!--  -->
   6 </head>
   7 <h2>Description</h2>
   8 <p>
   9 The notification service monitor adds monitoring capabilities to the TAO
  10 Notification Service so that potential problems can be detected in time to
  11 take remedial action.
  12 </p>
  13 <p>
  14 The monitoring and control capability is enabled and configured
  15 via a service configuration directive.  The impact on normal operation of
  16 the Notification Service should be minimized whether or not Monitoring
  17 and Control is configured.
  18 </p>
  19 <h2>Using the Notification Service Monitor</h2>
  20 <h3>Configuration</h3>
  21 <p>
  22 The monitor is enabled via the Service Configurator.  These instructions
  23 assume that ACE and TAO are built as dynamic libraries.  If you are using
  24 static libraries, read these instructions first, then refer to the
  25 <a href="#static">special procedures for static libraries</a> section below.
  26
  27 The following
  28 Service Configurator commands will enable the monitor:</p>
  29 <pre>
  30   dynamic TAO_MonitorAndControl Service_Object * TAO_CosNotification_MC:_make_TAO_MonitorAndControl () ""
  31   dynamic TAO_MC_Notify_Service Service_Object * TAO_CosNotification_MC_Ext:_make_TAO_MC_Notify_Service () ""
  32 </pre>
  33 <p>
  34 When the notification service is initialized, the monitor will start up in
  35 it's own thread (using it's own ORB) and work in conjunction with the
  36 notification service to provide statistics through an IDL interface.
  37 </p>
  38 <p>
  39 The TAO_MonitorAndControl object accepts the following options:</p>
  40 <table border=1 summary="TAO_MonitorAndControl configuration options">
  41   <tr><th>Option</th><th>Description</th></tr>
  42   <tr>
  43     <td>-NoNameSvc</td>
  44     <td>Instructs the monitor not to register itself with the Name Service.
  45         Otherwise, it will be registered as TAO_MonitorAndControl.
  46     </td>
  47   </tr>
  48   <tr>
  49     <td>-ORBArg &lt;parameter&gt;</td>
  50     <td>Passes &lt;parameter&gt; to the monitor's ORB upon initialization.
  51         There is no limit to the number of times this argument can be
  52         provided.
  53     </td>
  54   </tr>
  55   <tr>
  56     <td>-o &lt;file&gt;</td>
  57     <td>Write the IOR of the monitor out to &lt;file&gt;.</td>
  58   </tr>
  59 </table>
  60 <h3>Obtaining a reference to the Monitor</h3>
  61 <p>
  62 The object reference to the Notification Service Monitor can be obtained
  63 one of following ways (depending upon the options passed upon configuration
  64 of the monitor):</p>
  65 <ul>
  66   <li>CORBA::Object_var obj = orb->string_to_object ("corbaloc:iiop:&lt;host&gt;:&lt;port&gt;/TAO_MonitorAndControl");</li>
  67   <li>CORBA::Object_var obj = orb->string_to_object ("corbaname:iiop:&lt;nshost&gt;:&lt;nsport&gt;#TAO_MonitorAndControl");</li>
  68   <li>CORBA::Object_var obj = orb->string_to_object ("file://&lt;path to IOR file&gt;");</li>
  69 </ul>
  70 <h3>Retrieving statistics from the Monitor</h3>
  71 <p>
  72 The IDL interface provides a set of methods to obtain statistic names as
  73 well as to obtain the statistics themselves.
  74 </p>
  75 <p>
  76 Numeric data is stored in a structure with the following definition:
  77 </p>
  78 <pre>
  79   struct Numeric
  80   {
  81     /// The number of samples currently taken into account
  82     unsigned long count;
  83
  84     /// The average of the accumulated samples.
  85     double average;
  86
  87     /// The sum of the squares of the samples.
  88     double sum_of_squares;
  89
  90     /// The minimum sample value recorded
  91     double minimum;
  92
  93     /// The maximum sample value recorded
  94     double maximum;
  95
  96     /// The last sample value recored
  97     double last;
  98   };
  99 </pre>
 100
 101 <p>Text lists are stored in a sequence of strings known as NameList.</p>
 102 <p>These types may be returned as part of a Union depending on the
 103 method.  The Data union has the following definition:</p>
 104 <pre>
 105   enum DataType { DATA_NUMERIC, DATA_TEXT };
 106   union Data switch (DataType) {
 107     case DATA_NUMERIC: Numeric num;
 108     case DATA_TEXT: NameList list;
 109   };
 110 </pre>
 111 <p>The <b>get_statistic_names()</b> method returns a <b>NameList</b> which
 112 contains the names that are currently known by the statistic monitor.
 113 This list will change over time.</p>
 114 <p>The <b>get_statistic(in string name)</b> returns a <b>Data</b> union which
 115 contains either a <b>Numeric</b> object or a <b>NameList</b>, depending upon
 116 the type of statistic associated with the provided name.  If the name does
 117 not correspond to a known statistic, the <b>InvalidName</b> exception will be
 118 thrown.
 119 </p>
 120 <p> The <b>get_statistics(in NameList names)</b> returns a
 121 <b>DataList</b>, which is a sequence of <b>Data</b>.  The order of the
 122 <b>DataList</b> is the same order as provided within the <b>NameList</b>.
 123 If any one name provided within the list does not correspond to a known
 124 statistic, the <b>InvalidName</b> exception will be thrown.
 125 </p>
 126 <p>The <b>clear_statistics(in NameList names)</b> method clears all
 127 accumulated statistic data for the provided names.  If any one name
 128 provided within the list does not correspond to a known statistic, the
 129 <b>InvalidName</b> exception will be thrown.
 130 </p>
 131 <p>The <b>get_and_clear_statistics(in NameList names)</b> method is a
 132 combination of <b>get_statistics()</b> and <b>clear_statistics()</b>.
 133 </p>
 134 <h3>Affecting the Notification Service with the Monitor</h3>
 135 <p>The <b>shutdown_event_channel(in string name)</b>.  If the name does
 136 not correspond to an event channel, the <b>InvalidName</b> exception will be
 137 thrown.
 138 </p>
 139
 140 <h3><a name="static">Special Procedures for Static Libraries</a></h3>
 141 If ACE and TAO are built as static libraries, follow the instructions above
 142 with these modifications:
 143 <ul>
 144 <li>On the mwc.pl command used to generate the build files, add the
 145 -features -features "notify_monitor_control=1" option.  For example
 146 to build for VC9, the mwc command would look like:
 147 <ul><li><pre>
 148 mwc.pl -type vc9 -static -features "notify_monitor_control=1" TAO_ACE.mwc
 149 </pre></li></ul>
 150 </li>
 151 <li>Replace the "dynamic" service configuration commands with a "static"
 152 commands.  <i>Note that these commands have different syntaxes.</i>
 153 <br/>For example if
 154 the service configuration commands for a dynamic build are (Lines wrapped
 155 for illustrative purposes.  In the service conf file the following should
 156 appear on two lines):
 157 <ul><li><pre>
 158   dynamic TAO_MonitorAndControl Service_Object *
 159     TAO_CosNotification_MC:_make_TAO_MonitorAndControl ()
 160     "-o monitor.ior
 161     -ORBArg \"-ORBInitRef -ORBArg NameService=corbaloc:iiop:localhost:10637/NameService\""
 162
 163   dynamic TAO_MC_Notify_Service Service_Object *
 164     TAO_CosNotification_MC_Ext:_make_TAO_MC_Notify_Service ()
 165     "-DispatchingThreads 1"
 166
 167 </pre></li></ul>  you should replace them with
 168 <ul><li><pre>
 169   static TAO_MonitorAndControl
 170     "-o monitor.ior
 171     -ORBArg -ORBInitRef
 172       -ORBArg NameService=corbaloc:iiop:localhost:10637/NameService"
 173
 174   static TAO_MC_Notify_Service "-DispatchingThreads 1"
 175 </pre></li></ul>
 176 Please note that the parser for the static service configuration directives
 177 does not honor escaped quotes, so the -ORBArg option must appear separately for
 178 each argument to the Notification Service MC's ORB.
 179 </li>
 180 </ul>
 181 </html>