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