sensorconfig.h 14.1 KB
Newer Older
1
2
//================================================================================
// Name        : sensorconfig.h
3
// Author      : Axel Auweter, Daniele Tafani
Micha Müller's avatar
Micha Müller committed
4
// Contact     : info@dcdb.it
5
// Copyright   : Leibniz Supercomputing Centre
Michael Ott's avatar
Michael Ott committed
6
// Description : C++ API for configuring libdcdb public sensors.
7
8
9
10
//================================================================================

//================================================================================
// This file is part of DCDB (DataCenter DataBase)
11
// Copyright (C) 2011-2019 Leibniz Supercomputing Centre
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
//================================================================================

Axel Auweter's avatar
Axel Auweter committed
28
29

/**
30
 * @file sensorconfig.h
Axel Auweter's avatar
Axel Auweter committed
31
 * @brief This file contains parts of the public API for the
Michael Ott's avatar
Michael Ott committed
32
 * libdcdb library.
Axel Auweter's avatar
Axel Auweter committed
33
34
 * It contains the class definition of the SensorConfig class,
 * that handles sensor configuration and initialization.
35
36
 *
 * @ingroup libdcdb
Axel Auweter's avatar
Axel Auweter committed
37
38
39
40
 */

#include <string>
#include <list>
41
#include <set>
42
43
#include <fstream>
#include <fcntl.h>
Axel Auweter's avatar
Axel Auweter committed
44
45

#include "connection.h"
Axel Auweter's avatar
Axel Auweter committed
46
47
#include "timestamp.h"
#include "sensorid.h"
48
#include "metadatastore.h"
Axel Auweter's avatar
Axel Auweter committed
49

Axel Auweter's avatar
Axel Auweter committed
50
51
#include "cassandra.h"

52
53
54
#ifndef DCDB_SENSORCONFIG_H
#define DCDB_SENSORCONFIG_H

55
56
#define MAX_PATTERN_LENGTH 64

57
58
#define SENSOR_CACHE_FILENAME "dcdb_sensor_cache_"

59
namespace DCDB {
Axel Auweter's avatar
Axel Auweter committed
60

61
/* Forward-declaration of the implementation-internal classes */
Axel Auweter's avatar
Axel Auweter committed
62
63
class SensorConfigImpl;

64
65
66
/**
 * This class is a container for the information DCDB keeps about public sensors.
 */
67
class PublicSensor
Axel Auweter's avatar
Axel Auweter committed
68
69
{
public:
70
71
72
73
74
  std::string name;                       /**< The public sensor's (public) name. */
  bool        is_virtual;                 /**< Denotes whether the sensor is a virtual sensor. */
  std::string pattern;                    /**< For non-virtual sensors, this holds a pattern describing the (internal) sensor IDs to which this public sensor matches. */
  double      scaling_factor;             /**< Scaling factor for every sensor reading */
  std::string unit;                       /**< Describes the unit of the sensor. See unitconv.h for known units. */
75
  uint64_t    sensor_mask;                /**< Determines the properties of the sensor. Currently defined are: integrable, monotonic, delta. */
76
77
78
79
80
81
  std::string expression;                 /**< For virtual sensors, this field holds the expression through which the virtual sensor's value is calculated. */
  std::string v_sensorid;                 /**< For virtual sensors, this field holds a SensorID used for storing cached values in the database. (FIXME: Cache to be implemented) */
  uint64_t    t_zero;                     /**< For virtual sensors, this field holds the first point in time at which the sensor carries a value. */
  uint64_t    interval;                   /**< This field holds the interval at which the sensor evaluates (in nanoseconds). */
  std::set<std::string> operations;       /**< Defines the operations on the sensor, e.g. avg, std deviation, etc. */
  uint64_t    ttl;                        /**< Defines the time to live (in nanoseconds) for the readings of this sensor. */
82
    
83
84
  PublicSensor();
  PublicSensor(const PublicSensor &copy);
85
86
    
  inline bool operator <  (const PublicSensor& rhs) const {return name <  rhs.name;}
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

  /**
  * @brief               Converts a SensorMetadata object to a DCDB::PublicSensor one.
  * 
  * @param s             SensorMetadata object to be converted
  * @return              Output PublicSensor object
  */
  static PublicSensor metadataToPublicSensor(const SensorMetadata& s);

  /**
  * @brief               Converts a DCDB::PublicSensor object to its SensorMetadata representation.
  * 
  * @param ps            The PublicSensor object to be converted
  * @return              Output SensorMetadata object
  */
  static SensorMetadata publicSensorToMetadata(const PublicSensor& ps);
Axel Auweter's avatar
Axel Auweter committed
103
104
};

105
106
107
/**
 * Enum type for representing the outcome of a DCDB SensorConfig API operation.
 */
Axel Auweter's avatar
Axel Auweter committed
108
typedef enum {
109
110
111
112
113
114
115
116
117
  SC_OK,                /**< Everything went fine. */
  SC_INVALIDSESSION,    /**< The session / database connection is invalid */
  SC_INVALIDPATTERN,    /**< The supplied SensorID pattern is invalid */
  SC_INVALIDPUBLICNAME, /**< The specified public name is invalid */
  SC_INVALIDEXPRESSION, /**< The specified virtual sensor expression is invalid */
  SC_EXPRESSIONSELFREF, /**< The specified virtual sensor references itself in the expression */
  SC_INVALIDVSENSORID,  /**< The virtual SensorID is invalid */
  SC_WRONGTYPE,         /**< You requested an operation for virtual sensors on a physical sensor or vice versa */
  SC_UNKNOWNSENSOR,     /**< The specified sensor is not known */
118
119
120
  SC_OBSOLETECACHE,     /**< Sensor cache is no longer valid */
  SC_CACHEERROR,        /**< Some error while reading the sensor cache occurred */
  SC_PATHERROR,         /**< Path-related error, likely due to permissions */
121
  SC_UNKNOWNERROR       /**< An unknown error occurred */
Axel Auweter's avatar
Axel Auweter committed
122
123
} SCError;

124
125
#define INTEGRABLE 1
#define MONOTONIC  2
126
127
#define DELTA      4

128
129
130
/**
 * This class holds all functions to create/delete/modify the configuration of (virtual and non-virtual) public sensors in DCDB.
 */
Axel Auweter's avatar
Axel Auweter committed
131
132
133
134
135
136
class SensorConfig
{
protected:
  SensorConfigImpl* impl;

public:
137
138
139
140
141
142
143
  /**
   * @brief Load all published sensors into cache.
   *
   * @return               See SCError.
   */
  SCError loadCache();

144
145
146
147
148
149
150
  /**
   * @brief Makes a physical sensor public.
   *
   * @param publicName     Name under which the sensor becomes publicly available
   * @param sensorPattern  Pattern which describes the SensorIDs to which this sensor matches
   * @return               See SCError.
   */
Axel Auweter's avatar
Axel Auweter committed
151
  SCError publishSensor(const char* publicName, const char* sensorPattern);
152

153
154
155
156
157
158
159
160
   /**
   * @brief Makes a physical sensor public, and publish its metadata as well.
   *
   * @param sensor         Sensor to be published.
   * @return               See SCError.
   */
    SCError publishSensor(const PublicSensor& sensor);

161
162
163
164
165
166
167
168
169
170
171
172

    /**
    * @brief Makes a physical sensor public, and publish its metadata as well.
    *
    *                       This variant of the method takes as input a SensorMetadata object. All fields which are not
    *                       set (null) will not be published.
    * 
    * @param sensor         SensorMetadata object containing metadata to be published.
    * @return               See SCError.
    */
    SCError publishSensor(const SensorMetadata& sensor);

173
174
175
  /**
   * @brief Creates a new virtual sensor.
   *
176
   * @param publicName          Name under which the sensor becomes publicly available.
177
178
179
   * @param vSensorExpression   Arithmetic expression describing how to evaluate the virtual sensor.
   * @param vSensorId           SensorID under which previously evaluated values may be cached (FIXME: cache to be implemented).
   * @param tZero               Point in time at which the sensor evaluates for the first time.
180
   * @param interval           Interval at which the sensor will evaluate (starting from tZero) in nanoseconds.
181
182
   * @return                    See SCError.
   */
183
  SCError publishVirtualSensor(const char* publicName, const char* vSensorExpression, const char * vSensorId, TimeStamp tZero, uint64_t interval);
184
185
186
187
188
189
190

  /**
   * @brief Removes a (virtual or non-virtual) sensor from the list of public sensors.
   *
   * @param publicName          Name under which the sensor becomes publicly available
   * @return                    See SCError.
   */
191
  SCError unPublishSensor(const char* publicName);
192

193
194
195
196
197
198
199
200
  /**
   * @brief Removes one or more sensors from the list of public sensors using a wildcard.
   *
   * @param wildcard            Wildcard used to identify the sensors to be removed
   * @return                    See SCError.
   */
  SCError unPublishSensorsByWildcard(const char* wildcard);

201
202
203
204
205
206
  /**
   * @brief Get the entire list of (virtual or non-virtual) public sensors.
   *
   * @param publicSensors       Reference to a list of strings that will be populated with the sensor names.
   * @return                    See SCError.
   */
207
  SCError getPublicSensorNames(std::list<std::string>& publicSensors);
208
209
210
211
212
213
214

  /**
   * @brief Get the entire list of (virtual and non-virtual) public sensors including their definition.
   *
   * @param publicSensors       Reference to a list of PublicSensor that will be populated with the sensors' definition.
   * @return                    See SCError.
   */
215
  SCError getPublicSensorsVerbose(std::list<PublicSensor>& publicSensors);
216

217
  /**
218
   * @brief Retrieve a public sensor by name.
219
220
221
222
223
   *
   * @param sensor              Reference to a PublicSensor object that will be populated with the sensor's definition.
   * @param publicName          Name of the sensor whose information should be retrieved.
   * @return                    See SCError.
   */
224
  SCError getPublicSensorByName(PublicSensor& sensor, const char* publicName);
225
226
227
228
229
230
231
232
233
    
  /**
   * @brief Retrieve a list of public sensors that match a wildcard.
   *
   * @param sensors             Reference to a list of PublicSensor that will be populated with the sensors' definition.
   * @param wildcard            Wildcard to search for in the list of public sensors.
   * @return                    See SCError.
   */
  SCError getPublicSensorsByWildcard(std::list<PublicSensor>& sensors, const char* wildcard);
Axel Auweter's avatar
Axel Auweter committed
234

235
236
237
238
239
240
241
  /**
   * @brief Determine whether a given sensor is a virtual sensor.
   *
   * @param isVirtual           Reference to a bool which holds the result.
   * @param publicName          Name of the sensor whose information should be retrieved.
   * @return                    See SCError.
   */
242
243
  SCError isVirtual(bool& isVirtual, std::string publicName);

244
245
246
247
248
249
250
  /**
   * @brief Set the scaling factor for a public sensor. (FIXME: Scaling factors system is not in use!)
   *
   * @param publicName          Name of the sensor.
   * @param scalingFactor       New scaling factor for the sensor.
   * @return                    See SCError.
   */
251
  SCError setSensorScalingFactor(std::string publicName, double scalingFactor);
252
253
254
255
256
257
258
259

  /**
   * @brief Set the unit for a public sensor.
   *
   * @param publicName          Name of the sensor.
   * @param unit                New unis for the sensor. See unitconv.h for a list of supported units.
   * @return                    See SCError.
   */
260
  SCError setSensorUnit(std::string publicName, std::string unit);
261
262

  /**
263
   * @brief Set a sensor property with a mask. Currently implemented properties are "integrable" and "monotonic".
264
265
   *
   * @param publicName          Name of the sensor.
266
   * @param mask                New bit mask for the sensor properties.
267
268
   * @return                    See SCError.
   */
269
  SCError setSensorMask(std::string publicName, uint64_t mask);
270

271
272
273
274
   /**
    * @brief Set an operation for the sensor.
    *
    * @param publicName          Name of the sensor.
275
    * @param operation           Set of operations for the sensor.
276
277
    * @return                    See SCError.
    */
278
    SCError setOperations(std::string publicName, std::set<std::string> operations);
279

280
281
282
283
284
285
286
287
    /**
    * @brief Removes all operations of the sensor.
    *
    * @param publicName          Name of the sensor.
    * @return                    See SCError.
    */
    SCError clearOperations(std::string publicName);

288
289
290
291
292
293
294
295
    /**
    * @brief Removes all operations of all sensors matching a given wildcard.
    *
    * @param wildcard            Wildcard to identify sensors whose operations must be cleared.
    * @return                    See SCError.
    */
    SCError clearOperationsByWildcard(std::string wildcard);

296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
    /**
    * @brief Set a new sensor expression for a virtual sensor.
    *
    * @param publicName          Name of the sensor.
    * @param ttl                 Time to live value in nanoseconds.
    * @return                    See SCError.
    */
    SCError setTimeToLive(std::string publicName, uint64_t ttl);

    /**
   * @brief Set the evaluation interval for a sensor.
   *
   * @param publicName          Name of the sensor.
   * @param interval            New evaluation interval for the sensor in nanoseconds.
   * @return                    See SCError.
   */
    SCError setSensorInterval(std::string publicName, uint64_t interval);
    
314
315
316
317
318
319
320
  /**
   * @brief Set a new sensor expression for a virtual sensor.
   *
   * @param publicName          Name of the sensor.
   * @param expression          New virtual sensor expression.
   * @return                    See SCError.
   */
321
  SCError setVirtualSensorExpression(std::string publicName, std::string expression);
322
  
323
324
325
326
327
328
329
  /**
   * @brief Set the t0 for a virtual sensor.
   *
   * @param publicName          Name of the sensor.
   * @param tZero               New tZero for the sensor.
   * @return                    See SCError.
   */
330
  SCError setVirtualSensorTZero(std::string publicName, TimeStamp tZero);
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346

  /**
   * @brief Get the timestamp of the most recent update to the publishedsensors table.
   *
   * @param ts                  Unsigned 64-bit integer where to store the result.
   * @return                    See SCError.
   */
  SCError getPublishedSensorsWritetime(uint64_t &ts);

  /**
   * @brief Update the timestamp of the most recent update to the publishedsensors table.
   *
   * @param ts                  New timestamp to insert.
   * @return                    See SCError.
   */
  SCError setPublishedSensorsWritetime(const uint64_t &ts);
347
  
348
349
350
351
352
  /**
   * @brief Constructor for the SensorConfig class.
   *
   * @param conn                Connection object of the current connection into the DCDB data store.
   */
353
  SensorConfig(Connection* conn);
Axel Auweter's avatar
Axel Auweter committed
354
355
356
  virtual ~SensorConfig();
};

357
} /* End of namespace DCDB */
Axel Auweter's avatar
Axel Auweter committed
358

359
#endif /* DCDB_SENSORCONFIG_H */