Statistics
| Branch: | Revision:

napa-baselibs / include / mon.h @ a1a78de4

History | View | Annotate | Download (17 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 TX based measurement (mutually exclusive with RXONLY, TXRXUNI and TXRXBI) */
137
#define TXONLY         1
138
/** Used to advertise a RX based measurement (mutually exclusive with TXONLY, TXRXUNI and TXRXBI) */
139
#define RXONLY                2
140
/** Used to advertise a collaborative measurement unidirectional (mutually exclusive with RXONLY, TXONLY and TXRXBI) */
141
#define TXRXUNI        4
142
/** Used to advertise a collaborative measurement bidirectional (mutually exclusive with RXONLY, TXONLY and TXRXUNI) */
143
#define TXRXBI                8
144

    
145
/** Used to advertise a In-Band measurement (mutually exclusive with OUT_OF_BAND)*/
146
#define IN_BAND                 16
147
/** Used to advertise a Out-Of-Band measurement (mutually exclusive with IN_BAND)*/
148
#define OUT_OF_BAND         32
149
/** Used to advertise a Timer-based measurements (mutually exclusive with above two)*/
150
#define TIMER_BASED         64
151

    
152
/** Used to advertise a packet level measurement */
153
#define PACKET         128
154
/** Used to advertise a chunk level measurement */
155
#define DATA                 256
156

    
157

    
158
/** The following defines are for internal use only */
159
/** Used to advertise a local TX based level measurement (internal use only)*/
160
#define TXLOC                512
161
/** Used to advertise a local RX based level measurement (internal use only)*/
162
#define RXLOC                1024
163
/** Used to advertise a remote TX based level measurement (internal use only)*/
164
#define TXREM                2048
165
/** Used to advertise a remote RX based level measurement (internal use only)*/
166
#define RXREM                4096
167
/** Defines if this is the local (0) or remote (1) part of a measurement (internal use only)*/
168
#define REMOTE                8192
169

    
170
#endif
171

    
172

    
173
#pragma pack(push)  /* push current alignment to stack */
174
#pragma pack(1)     /* set alignment to 1 byte boundary */
175
/** The monitoring layer packet header */
176
struct MonPacketHeader {
177
        uint32_t seq_num;
178
        uint32_t ts_sec;
179
        uint32_t ts_usec;
180
        uint32_t ans_ts_sec;
181
        uint32_t ans_ts_usec;
182
        uint8_t initial_ttl;
183
/** Fields TBD */
184
};
185
#pragma pack(pop)   /* restore original alignment from stack */
186
/** Constant indicating the size of the monitoring layer header for packets */
187
#define MON_PACKET_HEADER_SIZE 21
188

    
189

    
190
#pragma pack(push)  /* push current alignment to stack */
191
#pragma pack(1)     /* set alignment to 1 byte boundary */
192
/** The monitoring layer data header */
193
struct MonDataHeader {
194
        int32_t seq_num;
195
        uint32_t ts_sec;
196
        uint32_t ts_usec;
197
        uint32_t ans_ts_sec;
198
        uint32_t ans_ts_usec;
199
/** Fields TBD */
200
};
201
#pragma pack(pop)   /* restore original alignment from stack */
202
/** Constant indicating the size of the monitoring layer header for data */
203
#define MON_DATA_HEADER_SIZE 20
204

    
205

    
206

    
207
#ifndef MonParameterType
208
/** Parameter type  */
209
typedef int32_t MonParameterType;
210
#endif
211

    
212
#ifndef MonParameterValue
213
/** Type for measurement Paramters */
214
typedef double MonParameterValue;
215
#endif
216

    
217

    
218
/** Structure describing a measurement parameter */
219
struct MeasurementParameter {
220
        /** Parameter handler for the parameter (valid for a specific measurment instance only) */
221
        MonParameterType ph;
222

    
223
        /** Textual name of the parameter */
224
        char *name;
225

    
226
        /** Textual parameter description  */
227
        char *desc;
228

    
229
        /** Default value */
230
        MonParameterValue dval;
231
};
232

    
233
/** Structure describing a measurement */
234
struct MeasurementPlugin {
235
        /** MeasurementName the plugin implements */
236
        MeasurementName name;
237

    
238
        /** The numerical Id of measurement */
239
   MeasurementId id;
240

    
241
        /** MeasurementDescription of the measurement the plugin implements */
242
        char *desc;
243

    
244
        /** Array of possible dependencies of this plugin (numerical ids)*/
245
   MeasurementId* deps_id;
246

    
247
        /** The length of the deps array */
248
        int deps_length;
249

    
250
        /** Array of parameters of this plugin */
251
        struct MeasurementParameter* params;
252

    
253
        /** Number of possible dependencies of this plugin (length of array)*/
254
        int params_length;
255

    
256
        /** Bitmask of available capabilities for this plugin.
257
        (i.e. the measurement can be performed on packets or on chunks or both.)
258
        */
259
        MeasurementCapabilities caps;
260
};
261

    
262
/** Short status code for a measurement plugin */
263

    
264
typedef enum {
265
UNKNOWN,
266
/* Stopped: created but not running */
267
STOPPED,
268
/* all is ok and we are collecting samples */
269
RUNNING,
270
/* a local error occured while activating the measure */
271
FAILED,
272
/* a remote error occured while activating the measure */
273
RFAILED,
274
/* you called monActivateMeasure with wrong paramters */
275
ERROR,
276
/* the measure is beeing set up */
277
INITIALISING,
278
/* the measure is beeing stopped */
279
STOPPING
280
} MeasurementStatus;
281

    
282

    
283
#ifdef __cplusplus
284
extern "C" {
285
#endif
286

    
287

    
288
/**
289
   List of available measurements (registered plugins)
290

291
  This function returns an array of MeasurementPlugin each one being a structure describing an available measurement.
292
  The parameter is used to pass the length of the array.
293

294
   @param[out] length pointer to an int to be filled with the array length
295
   @return Array of struct MeasurementPlugin
296
*/
297
struct MeasurementPlugin *monListMeasures (int *length);
298

    
299
/**
300
   Creates a new instance of a measurement by MeasurementId
301

302
        This creates a measurement instance using the measurement id (faster)
303
   @param[in] id the numerical identifier of the measurement to be created
304
   @param[in] mc the capabilities which this specific instance of the measure should implement
305
        (must be a subset of the capabilities advertised by the plugin in struct MeasurementPlugin)
306
        Must respect some mutual exclusion rules: IN_BAND and OUT_OF_BAND are mutually exclusive,
307
        TXONLY, RXONLY and TXRX are mutually exclusive.
308
   @return the handler of the newly created measurement instance (negative value indicates failure)
309
   @see monCreateMeasureName
310
*/
311
MonHandler monCreateMeasure (MeasurementId id, MeasurementCapabilities mc);
312

    
313
/**
314
   Creates a new instance of a measurement by MeasurementName
315

316
        This creates a measurement instance using the measurement name
317
   @param[in] name the textual name of the measurement to be created
318
   @param[in] mc the capabilities which this specific instance of the measure should implement
319
        (must be a subset of the capabilities advertised by the plugin in struct MeasurementPlugin)
320
        Must respect some mutual exclusion rules: IN_BAND and OUT_OF_BAND are mutually exclusive,
321
        TXONLY, RXONLY and TXRX are mutually exclusive.
322
   @return the handler of the newly created measurement instance (negative value indicates failure)
323
   @see monCreateMeasure
324
*/
325
MonHandler monCreateMeasureName (const MeasurementName name, MeasurementCapabilities mc);
326

    
327
/**
328
   Frees a measurement instance created by mon_create_measure()
329

330
   If the instance is currently in use it will be deactivated before being freed.
331

332
   @param[in] mh the handler of the measurement to be freed
333
        @return 0 on success, negative value on error
334
*/
335
int monDestroyMeasure (MonHandler mh);
336

    
337
/**
338
   Lists all parameters of a measurement (by id)
339

340
   @param[in] mid Id of the measurement
341
   @param[out] length pointer to an int to be filled with the array length
342
   @return Array of struct MeasurementParameter or NULL on error
343
*/
344
struct MeasurementParameter *monListParametersById (MeasurementId mid, int *length);
345

    
346

    
347
/**
348
   Lists all parameters of a measurement (by handler)
349

350
   @param[in] mh handler of the measurement instance
351
   @param[out] length pointer to an int to be filled with the array length
352
   @return Array of struct MeasurementParameter or NULL on error
353
*/
354
struct MeasurementParameter *monListParametersByHandler (MonHandler mh, int *length);
355

    
356
/**
357
   Set a new value for a parameter of a measurement
358

359
   @param[in] mh handler of the measurement instance
360
   @param[in] ph handler of the parameter
361
   @param[in] p new value
362
   @return 0 on success, negative value on failure (ie. the value is not within the admissible range)
363
*/
364
int monSetParameter (MonHandler mh, MonParameterType ph, MonParameterValue p);
365

    
366
/**
367
   Get current value of a parameter of a measurement
368

369
   @param[in] mh handler of the measurement instance
370
   @param[in] ph handler of the parameter
371
   @return current value (NAN on error)
372
*/
373
MonParameterValue monGetParameter (MonHandler mh, MonParameterType ph);
374

    
375
/**
376
   Activate measure
377

378
   Used to start a specific instance of a measurement. It puts the instance on the correct execution list of the monitoring layer.
379
   If necesasry,  the remote party will also be set up using control messages of the monitoring layer.
380
   The function is always non-blocking and the information of the measurement status can be gathered calling the monGetStatus function.
381

382
   @param[in] mh handler of the measurement instance
383
   @param[in] dst an identifier for the Id of the remote peer
384
   @param[in] mt the message type filter if set to MSGTYPE_ANY, accept all (only considered for in_band)
385
   @return 0 on success, negative value on failure
386
*/
387

    
388
int monActivateMeasure (MonHandler mh, SocketId dst, MsgType mt);
389

    
390
/**
391
   Publish results
392

393
   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.
394

395
   @param[in] mh handler of the measurement instance
396
   @param[in] publishing_name the name used to publish the results if NULL the default name from the measurment plugin is used
397
   @param[in] mh channel name to use
398
   @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
399
        @param[in] length the length of the st array. If 0 nothing is pubblished.
400
        @param[in] repo_client a valid repoclient HANLDE or NULL to use the default one specifed in MonInit()
401
   @return 0 on success, negative value on failure
402
*/
403

    
404
int monPublishStatisticalType(MonHandler mh, const char *publishing_name, const char *channel, enum stat_types st[], int length, void  *repo_client);
405

    
406
/**
407
  Retrieve results
408

409
   Used to retreive a result shortcuting the repository.
410

411
   @param[in] mh handler of the measurement instance
412
   @param[in] st statistal type to be retrieved (i.e. average value) enum defined in monl/ids.h
413
   @return the value on success, NAN on failure
414
*/
415

    
416
result monRetrieveResult(MonHandler mh, enum stat_types st);
417

    
418
/**
419
  Retrieve results
420

421
   Used to retreive a result shortcuting the repository.
422

423
   @param[in] mh handler of the measurement instance
424
   @param[in] st statistal type to be retrieved (i.e. average value) enum defined in monl/ids.h
425
   @return the value on success, NAN on failure
426
*/
427

    
428

    
429
/**
430
  Save arbitrary samples
431

432
   Used to supply smaples to the generic module
433

434
   @param[in] mh handler of the measurement instance
435
   @return 0 on success, != 0 on failure
436
*/
437
int monNewSample(MonHandler mh, result r);
438

    
439
/**
440
  Set peer's publish name
441

442
   This name will be used as originator in all subsequent
443
   publish operations.
444

445
   @param[in] name the name
446
   @return 0 on success, != 0 on failure
447
*/
448
int monSetPeerName(const char *name);
449

    
450
/**
451
   Deactivate measure
452

453
   Removes an instance from the excution lists and therefore stops any measurements performed by this
454
   instance. The instance can be reused putting it on a different execution list calling the
455
   monActivateMeasure() function.
456

457
   @param[in] mh handler of the measurement instance
458
   @return 0 on success, negative value on failure
459
*/
460
int monDeactivateMeasure (MonHandler mh);
461

    
462

    
463
/**
464
  Get the status code for a measurement instance
465

466
  @param[in] mh measurement instance handler
467
  @return status code
468
*/
469
MeasurementStatus monGetStatus(MonHandler mh);
470

    
471
/** Config file parsing instructions for mon */
472
// Not yet used
473
//extern cfg_opt_t MONConfig[];
474

    
475
/**
476
  Initialize the Monitoring Layer.
477

478
  Needs to be called to bootstrap the Monitoring Layer.
479

480
  @param[in] event_base pointer to the event base of libevent
481
  @param[in] repo_client pointer to a default repository client to use to publish or NULL
482
  @param[in] cfg_mon Structure holding the parsed MonL section of the configuration file (not used as of now)
483
  @return 0 on success, negative value on failure
484
*/
485
/* as of now it not uses the config file yet */
486
//int monInit(cfg_opt_t *cfg_mon);
487
int monInit(void *event_base, void *repo_client);
488
#ifdef __cplusplus
489
}
490
#endif
491

    
492
#endif