Statistics
| Branch: | Revision:

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