napa-baselibs / include / mon.h @ 5f3adef4
History | View | Annotate | Download (17.1 KB)
1 |
/***************************************************************************
|
---|---|
2 |
* Copyright (C) 2009 by Robert Birke
|
3 |
* robert.birke@polito.it
|
4 |
*
|
5 |
* This library is free software; you can redistribute it and/or
|
6 |
* modify it under the terms of the GNU Lesser General Public
|
7 |
* License as published by the Free Software Foundation; either
|
8 |
* version 2.1 of the License, or (at your option) any later version.
|
9 |
|
10 |
* This library is distributed in the hope that it will be useful,
|
11 |
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
12 |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
13 |
* Lesser General Public License for more details.
|
14 |
|
15 |
* You should have received a copy of the GNU Lesser General Public
|
16 |
* License along with this library; if not, write to the Free Software
|
17 |
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
18 |
***********************************************************************/
|
19 |
|
20 |
#ifndef _MON_H
|
21 |
#define _MON_H
|
22 |
|
23 |
/** @file mon.h
|
24 |
*
|
25 |
* <b>Definitions for the Monitoring Layer (MonL) API v0.9</b>
|
26 |
*
|
27 |
* <b>Architecture</b>: The Monitoring Box is a management layer which governs the execution of
|
28 |
* <i>Monitoring Plugins</i>.
|
29 |
* Each plugin implements one specific measurement type. Plugins are either scheduled on hook events
|
30 |
* (in-band measurements) or based on time (out-of-band measurements). Scheduling and triggering (both event and
|
31 |
* periodic ones) of plugins is done by the Monitoring Layer, and the plugins MUST NOT rely on any external
|
32 |
* scheduler service in order to protect control flow.
|
33 |
* The MonL is responsible for the registration and setting up OS and framework-dependent timing and triggering
|
34 |
* services (i.e. communication callback hooks and timeouts).
|
35 |
*
|
36 |
* The typical sequence to start a measurement should be:
|
37 |
* -# (optional) <i>monListMeasures()</i> to get a list of available measurements and their capabilities
|
38 |
* -# <i>mh = monCreateMeasure(t,c)</i> to create an instance of a measurement of type <i>t</i> and capabilities <i>c</i>. A <i>handler</i> is returned, which can be used to interact with this instance.
|
39 |
* -# (optional) get list of parameters using <i>monListParameters()</i>
|
40 |
* -# (optional) check current values of parameters with <i>monGetParameter()</i>
|
41 |
* -# (optional) adjust values of parameters with <i>monSetParameter()</i>
|
42 |
* -# Schedule the measurement instance for execution specifying which messages should be analysed
|
43 |
* (remote peer and message type) using <i>monActivateMeasure()</i>
|
44 |
* -# (optional) check status of measurement instance with <i>monGetStatus()</i>
|
45 |
*
|
46 |
* The typical sequence to stop a measurement should be:
|
47 |
* -# (optional) remove an instance from the execution list using <i>monDeactivateMeasure()</i>
|
48 |
* -# free resources using the <i>monDestroyMeasure()</i>
|
49 |
*
|
50 |
* The usage of separate instances for separate peer pairs/message types allows maximum flexibility.
|
51 |
*
|
52 |
* <b>Requirements:</b>
|
53 |
* This specification assumes that the data transfer (Messaging) layer, used in the P2P application has the
|
54 |
* notion of PeerID for identifying nodes (peers). The data transfer layer must support a datagram-like service
|
55 |
* (modeled after the UDP protocol), and must provide certain <i>callback</i> notifications (detailed below)
|
56 |
* upon datagram reception/sending.
|
57 |
* The Messaging Layer must also support the notion of MessageTypes and subscription services for messages of the
|
58 |
* specified types.
|
59 |
*
|
60 |
* Although these requirements may seem to be restrictive, we must note that such functionality can usually be
|
61 |
* easily implemented as a lighweight "wrapper" functionality around existing datagram transfer libraries.
|
62 |
*
|
63 |
* <b>Planned extensions:</b>
|
64 |
*
|
65 |
* A version of mon_activate_measure with arrays of NodeID/MsgType could be envisaged (or add/remove peer functions).
|
66 |
*
|
67 |
* @author Robert Birke
|
68 |
*
|
69 |
* @date 12/28/2009
|
70 |
*/
|
71 |
|
72 |
#include <stdint.h> |
73 |
#include <stdlib.h> |
74 |
#include <sys/time.h> |
75 |
|
76 |
#include "../monl/ids.h" |
77 |
#include "msg_types.h" |
78 |
|
79 |
//TODO: not very clean ....
|
80 |
#ifndef _socket_ID
|
81 |
struct _socket_ID;
|
82 |
#endif
|
83 |
|
84 |
typedef struct _socket_ID *SocketId; |
85 |
|
86 |
typedef uint8_t MsgType;
|
87 |
|
88 |
#ifndef MeasurementName
|
89 |
/** Default name for a measurement */
|
90 |
typedef char *MeasurementName; |
91 |
#endif
|
92 |
|
93 |
#ifndef MeasurementId
|
94 |
/** Identifier (numerical) for a measurement */
|
95 |
typedef int32_t MeasurementId;
|
96 |
#endif
|
97 |
|
98 |
#ifndef MonHandler
|
99 |
/** Identifier for a measurement */
|
100 |
typedef int32_t MonHandler;
|
101 |
#endif
|
102 |
|
103 |
/** Type for numerical results */
|
104 |
typedef double result; |
105 |
|
106 |
|
107 |
/** A MeasurementRecord holds measurement values computed by Monitoring plugins (defined in mon.h).
|
108 |
MeasurementRecords are published to the Repository. */
|
109 |
typedef struct { |
110 |
/** The originator (source) of this record
|
111 |
(e.g. "ALTOxyz" or a PeerID/SocketId converted to string) */
|
112 |
char *originator;
|
113 |
/** "Primary" target PeerID/SocketId */
|
114 |
char *targetA;
|
115 |
/** "Secondary" target PeerID/SocketId */
|
116 |
char *targetB;
|
117 |
/** The corresponding MeasurementName. */
|
118 |
const char* published_name; |
119 |
/** Measurement numerical value. NAN if not valid */
|
120 |
double value;
|
121 |
/** Measurement string value. "" if not valid */
|
122 |
char *string_value;
|
123 |
/** Timestamp of the measurement result */
|
124 |
struct timeval timestamp;
|
125 |
/** Name of channel (if relevant) */
|
126 |
const char *channel; |
127 |
} MeasurementRecord; |
128 |
|
129 |
|
130 |
#ifndef MeasurementCapabilities
|
131 |
/** Capabilities implemented by plugin */
|
132 |
typedef int32_t MeasurementCapabilities;
|
133 |
|
134 |
/* Codes for plugin capabilities */
|
135 |
|
136 |
/** Used to advertise a In-Band measurement (mutually exclusive with OUT_OF_BAND)*/
|
137 |
#define IN_BAND 1 |
138 |
/** Used to advertise a Out-Of-Band measurement (mutually exclusive with IN_BAND)*/
|
139 |
#define OUT_OF_BAND 2 |
140 |
/** Used to advertise a Timer-based measurements (mutually exclusive with above two)*/
|
141 |
#define TIMER_BASED 4 |
142 |
|
143 |
/** Used to advertise a packet level measurement */
|
144 |
#define PACKET 8 |
145 |
/** Used to advertise a chunk level measurement */
|
146 |
#define DATA 16 |
147 |
|
148 |
|
149 |
/** The following defines are for internal use only */
|
150 |
/** Used to advertise a local TX based level measurement (internal use only)*/
|
151 |
#define TXLOC 32 |
152 |
/** Used to advertise a local RX based level measurement (internal use only)*/
|
153 |
#define RXLOC 64 |
154 |
/** Used to advertise a remote TX based level measurement (internal use only)*/
|
155 |
#define TXREM 128 |
156 |
/** Used to advertise a remote RX based level measurement (internal use only)*/
|
157 |
#define RXREM 256 |
158 |
/** Defines if this is the local (0) or remote (1) part of a measurement (internal use only)*/
|
159 |
#define REMOTE 512 |
160 |
|
161 |
/** Used to advertise a TX based measurement (mutually exclusive with RXONLY, TXRXUNI and TXRXBI) */
|
162 |
#define TXONLY TXLOC
|
163 |
/** Used to advertise a RX based measurement (mutually exclusive with TXONLY, TXRXUNI and TXRXBI) */
|
164 |
#define RXONLY RXLOC
|
165 |
/** Used to advertise a collaborative measurement unidirectional (mutually exclusive with RXONLY, TXONLY and TXRXBI) */
|
166 |
#define TXRXUNI (TXLOC | RXREM)
|
167 |
/** Used to advertise a collaborative measurement bidirectional (mutually exclusive with RXONLY, TXONLY and TXRXUNI) */
|
168 |
#define TXRXBI (TXLOC | RXREM | TXREM | RXLOC)
|
169 |
|
170 |
|
171 |
#endif
|
172 |
|
173 |
|
174 |
#pragma pack(push) /* push current alignment to stack */ |
175 |
#pragma pack(1) /* set alignment to 1 byte boundary */ |
176 |
/** The monitoring layer packet header */
|
177 |
struct MonPacketHeader {
|
178 |
uint32_t seq_num; |
179 |
uint32_t ts_sec; |
180 |
uint32_t ts_usec; |
181 |
uint32_t ans_ts_sec; |
182 |
uint32_t ans_ts_usec; |
183 |
uint8_t initial_ttl; |
184 |
/** Fields TBD */
|
185 |
}; |
186 |
#pragma pack(pop) /* restore original alignment from stack */ |
187 |
/** Constant indicating the size of the monitoring layer header for packets */
|
188 |
#define MON_PACKET_HEADER_SIZE 21 |
189 |
|
190 |
|
191 |
#pragma pack(push) /* push current alignment to stack */ |
192 |
#pragma pack(1) /* set alignment to 1 byte boundary */ |
193 |
/** The monitoring layer data header */
|
194 |
struct MonDataHeader {
|
195 |
int32_t seq_num; |
196 |
uint32_t ts_sec; |
197 |
uint32_t ts_usec; |
198 |
uint32_t ans_ts_sec; |
199 |
uint32_t ans_ts_usec; |
200 |
/** Fields TBD */
|
201 |
}; |
202 |
#pragma pack(pop) /* restore original alignment from stack */ |
203 |
/** Constant indicating the size of the monitoring layer header for data */
|
204 |
#define MON_DATA_HEADER_SIZE 20 |
205 |
|
206 |
|
207 |
|
208 |
#ifndef MonParameterType
|
209 |
/** Parameter type */
|
210 |
typedef int32_t MonParameterType;
|
211 |
#endif
|
212 |
|
213 |
#ifndef MonParameterValue
|
214 |
/** Type for measurement Paramters */
|
215 |
typedef double MonParameterValue; |
216 |
#endif
|
217 |
|
218 |
|
219 |
/** Structure describing a measurement parameter */
|
220 |
struct MeasurementParameter {
|
221 |
/** Parameter handler for the parameter (valid for a specific measurment instance only) */
|
222 |
MonParameterType ph; |
223 |
|
224 |
/** Textual name of the parameter */
|
225 |
char *name;
|
226 |
|
227 |
/** Textual parameter description */
|
228 |
char *desc;
|
229 |
|
230 |
/** Default value */
|
231 |
MonParameterValue dval; |
232 |
}; |
233 |
|
234 |
/** Structure describing a measurement */
|
235 |
struct MeasurementPlugin {
|
236 |
/** MeasurementName the plugin implements */
|
237 |
MeasurementName name; |
238 |
|
239 |
/** The numerical Id of measurement */
|
240 |
MeasurementId id; |
241 |
|
242 |
/** MeasurementDescription of the measurement the plugin implements */
|
243 |
char *desc;
|
244 |
|
245 |
/** Array of possible dependencies of this plugin (numerical ids)*/
|
246 |
MeasurementId* deps_id; |
247 |
|
248 |
/** The length of the deps array */
|
249 |
int deps_length;
|
250 |
|
251 |
/** Array of parameters of this plugin */
|
252 |
struct MeasurementParameter* params;
|
253 |
|
254 |
/** Number of possible dependencies of this plugin (length of array)*/
|
255 |
int params_length;
|
256 |
|
257 |
/** Bitmask of available capabilities for this plugin.
|
258 |
(i.e. the measurement can be performed on packets or on chunks or both.)
|
259 |
*/
|
260 |
MeasurementCapabilities caps; |
261 |
}; |
262 |
|
263 |
/** Short status code for a measurement plugin */
|
264 |
|
265 |
typedef enum { |
266 |
UNKNOWN, |
267 |
/* Stopped: created but not running */
|
268 |
STOPPED, |
269 |
/* all is ok and we are collecting samples */
|
270 |
RUNNING, |
271 |
/* a local error occured while activating the measure */
|
272 |
FAILED, |
273 |
/* a remote error occured while activating the measure */
|
274 |
RFAILED, |
275 |
/* you called monActivateMeasure with wrong paramters */
|
276 |
ERROR, |
277 |
/* the measure is beeing set up */
|
278 |
INITIALISING, |
279 |
/* the measure is beeing stopped */
|
280 |
STOPPING |
281 |
} MeasurementStatus; |
282 |
|
283 |
|
284 |
#ifdef __cplusplus
|
285 |
extern "C" { |
286 |
#endif
|
287 |
|
288 |
|
289 |
/**
|
290 |
List of available measurements (registered plugins)
|
291 |
|
292 |
This function returns an array of MeasurementPlugin each one being a structure describing an available measurement.
|
293 |
The parameter is used to pass the length of the array.
|
294 |
|
295 |
@param[out] length pointer to an int to be filled with the array length
|
296 |
@return Array of struct MeasurementPlugin
|
297 |
*/
|
298 |
struct MeasurementPlugin *monListMeasures (int *length); |
299 |
|
300 |
/**
|
301 |
Creates a new instance of a measurement by MeasurementId
|
302 |
|
303 |
This creates a measurement instance using the measurement id (faster)
|
304 |
@param[in] id the numerical identifier of the measurement to be created
|
305 |
@param[in] mc the capabilities which this specific instance of the measure should implement
|
306 |
(must be a subset of the capabilities advertised by the plugin in struct MeasurementPlugin)
|
307 |
Must respect some mutual exclusion rules: IN_BAND and OUT_OF_BAND are mutually exclusive,
|
308 |
TXONLY, RXONLY and TXRX are mutually exclusive.
|
309 |
@return the handler of the newly created measurement instance (negative value indicates failure)
|
310 |
@see monCreateMeasureName
|
311 |
*/
|
312 |
MonHandler monCreateMeasure (MeasurementId id, MeasurementCapabilities mc); |
313 |
|
314 |
/**
|
315 |
Creates a new instance of a measurement by MeasurementName
|
316 |
|
317 |
This creates a measurement instance using the measurement name
|
318 |
@param[in] name the textual name of the measurement to be created
|
319 |
@param[in] mc the capabilities which this specific instance of the measure should implement
|
320 |
(must be a subset of the capabilities advertised by the plugin in struct MeasurementPlugin)
|
321 |
Must respect some mutual exclusion rules: IN_BAND and OUT_OF_BAND are mutually exclusive,
|
322 |
TXONLY, RXONLY and TXRX are mutually exclusive.
|
323 |
@return the handler of the newly created measurement instance (negative value indicates failure)
|
324 |
@see monCreateMeasure
|
325 |
*/
|
326 |
MonHandler monCreateMeasureName (const MeasurementName name, MeasurementCapabilities mc);
|
327 |
|
328 |
/**
|
329 |
Frees a measurement instance created by mon_create_measure()
|
330 |
|
331 |
If the instance is currently in use it will be deactivated before being freed.
|
332 |
|
333 |
@param[in] mh the handler of the measurement to be freed
|
334 |
@return 0 on success, negative value on error
|
335 |
*/
|
336 |
int monDestroyMeasure (MonHandler mh);
|
337 |
|
338 |
/**
|
339 |
Lists all parameters of a measurement (by id)
|
340 |
|
341 |
@param[in] mid Id of the measurement
|
342 |
@param[out] length pointer to an int to be filled with the array length
|
343 |
@return Array of struct MeasurementParameter or NULL on error
|
344 |
*/
|
345 |
struct MeasurementParameter *monListParametersById (MeasurementId mid, int *length); |
346 |
|
347 |
|
348 |
/**
|
349 |
Lists all parameters of a measurement (by handler)
|
350 |
|
351 |
@param[in] mh handler of the measurement instance
|
352 |
@param[out] length pointer to an int to be filled with the array length
|
353 |
@return Array of struct MeasurementParameter or NULL on error
|
354 |
*/
|
355 |
struct MeasurementParameter *monListParametersByHandler (MonHandler mh, int *length); |
356 |
|
357 |
/**
|
358 |
Set a new value for a parameter of a measurement
|
359 |
|
360 |
@param[in] mh handler of the measurement instance
|
361 |
@param[in] ph handler of the parameter
|
362 |
@param[in] p new value
|
363 |
@return 0 on success, negative value on failure (ie. the value is not within the admissible range)
|
364 |
*/
|
365 |
int monSetParameter (MonHandler mh, MonParameterType ph, MonParameterValue p);
|
366 |
|
367 |
/**
|
368 |
Get current value of a parameter of a measurement
|
369 |
|
370 |
@param[in] mh handler of the measurement instance
|
371 |
@param[in] ph handler of the parameter
|
372 |
@return current value (NAN on error)
|
373 |
*/
|
374 |
MonParameterValue monGetParameter (MonHandler mh, MonParameterType ph); |
375 |
|
376 |
/**
|
377 |
Activate measure
|
378 |
|
379 |
Used to start a specific instance of a measurement. It puts the instance on the correct execution list of the monitoring layer.
|
380 |
If necesasry, the remote party will also be set up using control messages of the monitoring layer.
|
381 |
The function is always non-blocking and the information of the measurement status can be gathered calling the monGetStatus function.
|
382 |
|
383 |
@param[in] mh handler of the measurement instance
|
384 |
@param[in] dst an identifier for the Id of the remote peer
|
385 |
@param[in] mt the message type filter if set to MSGTYPE_ANY, accept all (only considered for in_band)
|
386 |
@return 0 on success, negative value on failure
|
387 |
*/
|
388 |
|
389 |
int monActivateMeasure (MonHandler mh, SocketId dst, MsgType mt);
|
390 |
|
391 |
/**
|
392 |
Publish results
|
393 |
|
394 |
Used to tell the monitoring layer to publish the results into the repositry. By defualt (As of now) nothing is pubblished. The function needs a working rep client HANDLER to use.
|
395 |
|
396 |
@param[in] mh handler of the measurement instance
|
397 |
@param[in] publishing_name the name used to publish the results if NULL the default name from the measurment plugin is used
|
398 |
@param[in] mh channel name to use
|
399 |
@param[in] st an array of statistal types to be pubblished (i.e. average value) for each one of these is published adding a suffix to the publishing_name. both are defined in monl/ids.h
|
400 |
@param[in] length the length of the st array. If 0 nothing is pubblished.
|
401 |
@param[in] repo_client a valid repoclient HANLDE or NULL to use the default one specifed in MonInit()
|
402 |
@return 0 on success, negative value on failure
|
403 |
*/
|
404 |
|
405 |
int monPublishStatisticalType(MonHandler mh, const char *publishing_name, const char *channel, enum stat_types st[], int length, void *repo_client); |
406 |
|
407 |
/**
|
408 |
Retrieve results
|
409 |
|
410 |
Used to retreive a result shortcuting the repository.
|
411 |
|
412 |
@param[in] mh handler of the measurement instance
|
413 |
@param[in] st statistal type to be retrieved (i.e. average value) enum defined in monl/ids.h
|
414 |
@return the value on success, NAN on failure
|
415 |
*/
|
416 |
|
417 |
result monRetrieveResult(MonHandler mh, enum stat_types st);
|
418 |
|
419 |
/**
|
420 |
Retrieve results
|
421 |
|
422 |
Used to retreive a result shortcuting the repository.
|
423 |
|
424 |
@param[in] mh handler of the measurement instance
|
425 |
@param[in] st statistal type to be retrieved (i.e. average value) enum defined in monl/ids.h
|
426 |
@return the value on success, NAN on failure
|
427 |
*/
|
428 |
|
429 |
|
430 |
/**
|
431 |
Save arbitrary samples
|
432 |
|
433 |
Used to supply smaples to the generic module
|
434 |
|
435 |
@param[in] mh handler of the measurement instance
|
436 |
@return 0 on success, != 0 on failure
|
437 |
*/
|
438 |
int monNewSample(MonHandler mh, result r);
|
439 |
|
440 |
/**
|
441 |
Set peer's publish name
|
442 |
|
443 |
This name will be used as originator in all subsequent
|
444 |
publish operations.
|
445 |
|
446 |
@param[in] name the name
|
447 |
@return 0 on success, != 0 on failure
|
448 |
*/
|
449 |
int monSetPeerName(const char *name); |
450 |
|
451 |
/**
|
452 |
Deactivate measure
|
453 |
|
454 |
Removes an instance from the excution lists and therefore stops any measurements performed by this
|
455 |
instance. The instance can be reused putting it on a different execution list calling the
|
456 |
monActivateMeasure() function.
|
457 |
|
458 |
@param[in] mh handler of the measurement instance
|
459 |
@return 0 on success, negative value on failure
|
460 |
*/
|
461 |
int monDeactivateMeasure (MonHandler mh);
|
462 |
|
463 |
|
464 |
/**
|
465 |
Get the status code for a measurement instance
|
466 |
|
467 |
@param[in] mh measurement instance handler
|
468 |
@return status code
|
469 |
*/
|
470 |
MeasurementStatus monGetStatus(MonHandler mh); |
471 |
|
472 |
/** Config file parsing instructions for mon */
|
473 |
// Not yet used
|
474 |
//extern cfg_opt_t MONConfig[];
|
475 |
|
476 |
/**
|
477 |
Initialize the Monitoring Layer.
|
478 |
|
479 |
Needs to be called to bootstrap the Monitoring Layer.
|
480 |
|
481 |
@param[in] event_base pointer to the event base of libevent
|
482 |
@param[in] repo_client pointer to a default repository client to use to publish or NULL
|
483 |
@param[in] cfg_mon Structure holding the parsed MonL section of the configuration file (not used as of now)
|
484 |
@return 0 on success, negative value on failure
|
485 |
*/
|
486 |
/* as of now it not uses the config file yet */
|
487 |
//int monInit(cfg_opt_t *cfg_mon);
|
488 |
int monInit(void *event_base, void *repo_client); |
489 |
#ifdef __cplusplus
|
490 |
} |
491 |
#endif
|
492 |
|
493 |
#endif
|