src/include/core/store.h

   1 /*
   2  * SysDB - src/include/core/store.h
   3  * Copyright (C) 2012-2015 Sebastian 'tokkee' Harl <sh@tokkee.org>
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  * 2. Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  16  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
  19  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  20  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef SDB_CORE_STORE_H
  29 #define SDB_CORE_STORE_H 1
  30
  31 #include "sysdb.h"
  32 #include "core/object.h"
  33 #include "core/data.h"
  34 #include "core/time.h"
  35 #include "core/timeseries.h"
  36 #include "parser/ast.h"
  37 #include "utils/strbuf.h"
  38
  39 #include <stdio.h>
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 /*
  46  * Store object types.
  47  */
  48 enum {
  49         SDB_HOST = 1,
  50         SDB_SERVICE,
  51         SDB_METRIC,
  52
  53         SDB_ATTRIBUTE = 1 << 4,
  54         SDB_TIMESERIES = 1 << 6,
  55
  56         /*
  57          * Queryable fields of a stored object.
  58          */
  59         SDB_FIELD_NAME = 1 << 8, /* type: string */
  60         SDB_FIELD_LAST_UPDATE,   /* type: datetime */
  61         SDB_FIELD_AGE,           /* type: datetime */
  62         SDB_FIELD_INTERVAL,      /* type: datetime */
  63         SDB_FIELD_BACKEND,       /* type: array of strings */
  64         SDB_FIELD_VALUE,         /* attributes only;  type: type of the value */
  65         SDB_FIELD_TIMESERIES,    /* metrics only;  type: boolean */
  66 };
  67 #define SDB_STORE_TYPE_TO_NAME(t) \
  68         (((t) == SDB_HOST) ? "host" \
  69                 : ((t) == SDB_SERVICE) ? "service" \
  70                 : ((t) == SDB_METRIC) ? "metric" \
  71                 : ((t) == SDB_ATTRIBUTE) ? "attribute" \
  72                 : ((t) == (SDB_ATTRIBUTE | SDB_HOST)) ? "host attribute" \
  73                 : ((t) == (SDB_ATTRIBUTE | SDB_SERVICE)) ? "service attribute" \
  74                 : ((t) == (SDB_ATTRIBUTE | SDB_METRIC)) ? "metric attribute" \
  75                 : ((t) == SDB_TIMESERIES) ? "timeseries" \
  76                 : "unknown")
  77
  78 #define SDB_FIELD_TO_NAME(f) \
  79         (((f) == SDB_FIELD_NAME) ? "name" \
  80                 : ((f) == SDB_FIELD_LAST_UPDATE) ? "last-update" \
  81                 : ((f) == SDB_FIELD_AGE) ? "age" \
  82                 : ((f) == SDB_FIELD_INTERVAL) ? "interval" \
  83                 : ((f) == SDB_FIELD_BACKEND) ? "backend" \
  84                 : ((f) == SDB_FIELD_VALUE) ? "value" \
  85                 : ((f) == SDB_FIELD_TIMESERIES) ? "timeseries" \
  86                 : "unknown")
  87
  88 #define SDB_FIELD_TYPE(f) \
  89         (((f) == SDB_FIELD_NAME) ? SDB_TYPE_STRING \
  90                 : ((f) == SDB_FIELD_LAST_UPDATE) ? SDB_TYPE_DATETIME \
  91                 : ((f) == SDB_FIELD_AGE) ? SDB_TYPE_DATETIME \
  92                 : ((f) == SDB_FIELD_INTERVAL) ? SDB_TYPE_DATETIME \
  93                 : ((f) == SDB_FIELD_BACKEND) ? (SDB_TYPE_ARRAY | SDB_TYPE_STRING) \
  94                 : ((f) == SDB_FIELD_VALUE) ? -1 /* unknown */ \
  95                 : ((f) == SDB_FIELD_TIMESERIES) ? SDB_TYPE_BOOLEAN \
  96                 : -1)
  97
  98 /*
  99  * sdb_store_host_t represents the meta-data of a stored host object.
 100  */
 101 typedef struct {
 102         const char *name;
 103
 104         sdb_time_t last_update;
 105         sdb_time_t interval;
 106         const char * const *backends;
 107         size_t backends_num;
 108 } sdb_store_host_t;
 109 #define SDB_STORE_HOST_INIT { NULL, 0, 0, NULL, 0 }
 110
 111 /*
 112  * sdb_store_service_t represents the meta-data of a stored service object.
 113  */
 114 typedef struct {
 115         const char *hostname;
 116         const char *name;
 117
 118         sdb_time_t last_update;
 119         sdb_time_t interval;
 120         const char * const *backends;
 121         size_t backends_num;
 122 } sdb_store_service_t;
 123 #define SDB_STORE_SERVICE_INIT { NULL, NULL, 0, 0, NULL, 0 }
 124
 125 /*
 126  * sdb_metric_store_t specifies how to access a metric's data.
 127  */
 128 typedef struct {
 129         const char *type;
 130         const char *id;
 131         const sdb_timeseries_info_t *info;
 132         sdb_time_t last_update;
 133 } sdb_metric_store_t;
 134
 135 /*
 136  * sdb_store_metric_t represents the meta-data of a stored metric object.
 137  */
 138 typedef struct {
 139         const char *hostname;
 140         const char *name;
 141
 142         /* All data stores providing this metric. */
 143         const sdb_metric_store_t *stores;
 144         size_t stores_num;
 145
 146         sdb_time_t last_update;
 147         sdb_time_t interval;
 148         const char * const *backends;
 149         size_t backends_num;
 150 } sdb_store_metric_t;
 151 #define SDB_STORE_METRIC_INIT { NULL, NULL, NULL, 0, 0, 0, NULL, 0 }
 152
 153 /*
 154  * sdb_store_attribute_t represents a stored attribute.
 155  */
 156 typedef struct {
 157         const char *hostname; /* optional */
 158         int parent_type;
 159         const char *parent;
 160         const char *key;
 161         sdb_data_t value;
 162
 163         sdb_time_t last_update;
 164         sdb_time_t interval;
 165         const char * const *backends;
 166         size_t backends_num;
 167 } sdb_store_attribute_t;
 168 #define SDB_STORE_ATTRIBUTE_INIT { NULL, 0, NULL, NULL, SDB_DATA_INIT, 0, 0, NULL, 0 }
 169
 170 /*
 171  * A JSON formatter converts stored objects into the JSON format.
 172  * See http://www.ietf.org/rfc/rfc4627.txt
 173  *
 174  * A JSON formatter object inherits from sdb_object_t and, thus, may safely be
 175  * cast to a generic object.
 176  */
 177 struct sdb_store_json_formatter;
 178 typedef struct sdb_store_json_formatter sdb_store_json_formatter_t;
 179
 180 /*
 181  * A store writer describes the interface for plugins implementing a store.
 182  *
 183  * Any of the call-back functions shall return:
 184  *  - 0 on success
 185  *  - a positive value if the new entry is older than the currently stored
 186  *    entry (in this case, no update will happen)
 187  *  - a negative value on error
 188  */
 189 typedef struct {
 190         /*
 191          * store_host:
 192          * Add/update a host in the store. If the host, identified by its
 193          * canonicalized name, already exists, it will be updated according to the
 194          * specified name and timestamp. Else, a new entry will be created in the
 195          * store.
 196          */
 197         int (*store_host)(sdb_store_host_t *host, sdb_object_t *user_data);
 198
 199         /*
 200          * store_service:
 201          * Add/update a service in the store. If the service, identified by its
 202          * name, already exists for the specified host, it will be updated
 203          * according to the specified name and timestamp. If the referenced host
 204          * does not exist, an error will be reported. Else, a new entry will be
 205          * created in the store.
 206          */
 207         int (*store_service)(sdb_store_service_t *service, sdb_object_t *user_data);
 208
 209         /*
 210          * store_metric:
 211          * Add/update a metric in the store. If the metric, identified by its
 212          * name, already exists for the specified host, it will be updated
 213          * according to the specified attributes. If the referenced host does not
 214          * exist, an error will be reported. Else, a new entry will be created in
 215          * the store.
 216          */
 217         int (*store_metric)(sdb_store_metric_t *metric, sdb_object_t *user_data);
 218
 219         /*
 220          * store_attribute:
 221          * Add/update a host's attribute in the store. If the attribute,
 222          * identified by its key, already exists for the specified host, it will
 223          * be updated to the specified values. If the referenced host does not
 224          * exist, an error will be reported. Else, a new entry will be created in
 225          * the store.
 226          */
 227         int (*store_attribute)(sdb_store_attribute_t *attr, sdb_object_t *user_data);
 228 } sdb_store_writer_t;
 229
 230 /*
 231  * A store reader describes the interface to query a store implementation.
 232  */
 233 typedef struct {
 234         /*
 235          * prepare_query:
 236          * Prepare the query described by 'ast' for execution.
 237          */
 238         sdb_object_t *(*prepare_query)(sdb_ast_node_t *ast,
 239                         sdb_strbuf_t *errbuf, sdb_object_t *user_data);
 240
 241         /*
 242          * execute_query:
 243          * Execute a previously prepared query. The callback may expect that only
 244          * queries prepared by its respective prepare callback will be passed to
 245          * this function. The query result will be passed back via the specified
 246          * store writer.
 247          */
 248         int (*execute_query)(sdb_object_t *q,
 249                         sdb_store_writer_t *w, sdb_object_t *wd,
 250                         sdb_strbuf_t *errbuf, sdb_object_t *user_data);
 251 } sdb_store_reader_t;
 252
 253 /*
 254  * Flags for JSON formatting.
 255  */
 256 enum {
 257         SDB_WANT_ARRAY = 1 << 0,
 258 };
 259
 260 /*
 261  * sdb_store_json_formatter:
 262  * Create a JSON formatter for the specified object types writing to the
 263  * specified buffer.
 264  */
 265 sdb_store_json_formatter_t *
 266 sdb_store_json_formatter(sdb_strbuf_t *buf, int type, int flags);
 267
 268 /*
 269  * sdb_store_json_finish:
 270  * Finish the JSON output. This function has to be called once after emiting
 271  * all objects.
 272  */
 273 int
 274 sdb_store_json_finish(sdb_store_json_formatter_t *f);
 275
 276 /*
 277  * sdb_store_json_writer:
 278  * A store writer implementation that generates JSON output. It expects a
 279  * store JSON formatter as its user-data argument.
 280  */
 281 extern sdb_store_writer_t sdb_store_json_writer;
 282
 283 #ifdef __cplusplus
 284 } /* extern "C" */
 285 #endif
 286
 287 #endif /* ! SDB_CORE_STORE_H */
 288
 289 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
 290