store.h: Reuse the sdb_metric_store_t type for a metric's store field.
[sysdb.git] / ReleaseNotes
1                              SysDB Release Notes
2                             =====================
4   The release notes contain noteworthy changes in each System DataBase (SysDB)
5   release, with a summary of the most important changes at the top. A complete
6   and very detailed list of changes can be obtained from the Git logs for each
7   release.
9  Compatibility Note:
10  ~~~~~~~~~~~~~~~~~~~
11   All pre 1.0 development snapshots are not considered stable yet. That is,
12   all interfaces, including the plugin API, the network protocol, or the query
13   language, may change in an incompatible way at any time. All changes are
14   documented here.
16  About SysDB:
17  ~~~~~~~~~~~~
18   “System DataBase” (SysDB) is a multi-backend system management and inventory
19   collection service. It stores system and inventory information about
20   hardware and software systems. This information is (continuously) collected
21   from various configurable backends (inventory services, monitoring services,
22   etc.) and stored in a graph-like hierarchy of generic objects. The store may
23   be queried through a generic interface independent of the active backends.
24   Object names are canonicalized before they are added to the store to ensure
25   a consistent view of your infrastructure.
27   <>
29 Version 0.8.0, Release Date: 2016-02-25
30 ---------------------------------------
32   This release focuses on a generic and much more powerful store (query)
33   interface and modular store implementations via plugins. The in-memory store
34   has been moved into a plugin on top of that. Various fixes and improvements,
35   mostly related to iterators, have been applied to the parser and query
36   language.
38    * build system:
39      - Fix VPATH (out of tree) builds.
40      - Fixed a build issue (configure failure) when using RRDtool 1.5.
41      - Enable silent build rules by default (if supported).
42      - Fix build issues with GCC 5.
43    * parser:
44      - Add a new, standalone parser module based on a generic (public) AST
45        (abstract syntax tree). This replaces the (internal) parser of the
46        frontend module.
47      - Improved error reporting for syntactic and semantic errors by
48        propagating error messages in the parser and analyzer.
49    * core / store:
50      - Fully support array access and comparison (all element types).
51      - Service/metric parent host names are now available via the "hostname"
52        attribute (populated automatically).
53      - Rebase the store query interface on top of the new parser: store
54        implementations prepare actual queries from an AST, thus, allowing
55        multiple implementations of store readers.
56      - Querying the store (through the new interface) will emit data to an
57        arbitrary writer implementation allowing for more flexible post-
58        processing.
59      - Fixed a memory leak in the TIMESERIES implementation.
60      - data: Added support for boolean values; this is a backward incompatible
61        change which breaks the network encoding.
62      - Include nano-second fraction of datatime values (if any) in the string
63        format (including JSON query results).
64      - Add new callback type for store-readers (query plugins) based on the
65        new generic query interface.
66      - memstore: Refactor the in-memory store implementation into a separate
67        data-type. It implements the writer and query/reader APIs.
68      - The main, in-memory store is no longer enabled by default (see
69        store::memory plugin). Instead, all updates go through the plugin API
70        and are distributed to all registered writers.
71      - Handle hostname canonicalization in the generic plugin module instead
72        of requiring each writer plugin to do so.
73      - Do not canonicalize hostnames when fetching time-series.
74      - Determine an object's backends and update interval in the generic
75        plugin module and pass it on to writer plugins which are expected to
76        merge it with existing entries.
77      - Let the JSON formatter implement the writer API to make it more
78        flexible and uncouple it from the memstore module; let it support
79        arbitrary top-level objects (besides hosts).
80      - FETCH (in the core) now supports all object types and child objects as
81        well as fetching the base object without children / siblings.
82    * frontend:
83      - Added the SERVER_VERSION command; this allows clients to check for
84        supported servers.
85      - Fixed a memory leak in failed FETCH commands.
86      - Switch to the new, pluggable query interface: use registered plugins to
87        write to or query the SysDB store.
88      - Move protocol-specific (query) logic out of the core and into the
89        frontend (based on the new query API).
90      - A generic TIMESERIES implementation based on the query API replaces the
91        in-core implementation.
92    * query language:
93      - Check types of comparison operands and arithmetic expression and treat
94        mismatches as errors; previously those comparisons would fail silently.
95      - Added the 'NOT IN' operator.
96      - Support iterators (ANY/ALL) of arbitrary array expressions.
97      - Change child-object iterator syntax to 'ANY/ALL <type>.name', that is,
98        require the field name and add support for accessing arbitrary fields.
99      - Added new field "value" for attribute values.
100      - Added new field "timeseries" (boolean) for metrics indicating whether
101        a time-series store is known to SysDB.
102      - Support attribute and backend iterators in FILTER expressions.
103      - Enforce that TIMESERIES end times are greater than start times.
104      - Added unary 'IS TRUE' / 'IS FALSE' operators.
105      - Iterator expressions may now reference a chain of sibling objects as
106        long as only one such reference is an iterator. For example,
107        `LOOKUP services MATCHING ANY host.backend =~ 'foo'`.
108    * testing:
109      - Use check "loop" tests; this will run all test-cases even if there are
110        failures.
111      - Create separate binaries for each test; this allows to run more in
112        parallel.
113      - Make it possible to run unit and integration tests separately; see
114        README.
116   Stores:
117    * store::memory: Added a store-writer/store-reader plugin providing an
118      in-memory store replacing the previous, always-enabled store. It is based
119      on the 'memstore' module.
121 Version 0.7.0, Release Date: 2015-02-21
122 ---------------------------------------
124   This release introduces various features related to running SysDB as an
125   agent. Objects may now also be submitted by arbitrary applications using the
126   network protocol. Two new plugins are available to collect local facter fact
127   values and to mirror all store operations to another instance. Various fixes
128   and improvements have been applied to the client program (sysdb).
130    * build system:
131      - Added support for C++.
132    * sysdb:
133      - Fixed terminal resets on exit.
134      - Don't exit if the server closed the connection; instead reconnect
135        automatically on the next user input.
136      - Fixed string parsing: previously, quoted strings were not handled at
137        all and might have been terminated by an embedded semicolon.
138      - Also store failed commands in the history to enable history editing in
139        such cases.
140      - Improved program output: don't mix log messages with prompts after
141        sending a command; print log messages to the standard error channel.
142      - Fixed lookup of the .sysdb_history file for cases where the SysDB user
143        does not match the current operating system user.
144    * sysdbd:
145      - SSL options can be specified inside a <Listen> block.
146      - Unload all plugins on exit to ensure a clean shutdown.
147    * client:
148      - Simplified RPC handling by providing a helper function.
149      - Added support for TCP connections using SSL/TLS and supporting, both,
150        IPv4 and IPv6. Remote peer verification is required for any such
151        connection.
152      - New command line flags -K, -C, and -A to specify the SSL private key,
153        client certificate, and CA certificates file names.
154    * core:
155      - Fully support arrays of all types.
156      - Fixed (implemented) reloading of time-series fetcher plugins.
157      - Added new callback type for "store-writers", making that part of the
158        store pluggable (queries are not supported).
159    * store:
160      - Added support for querying an object's siblings.
161      - Send all stored objects to store-writer plugins in addition to storing
162        them in the in-memory store.
163    * frontend:
164      - Fixed parsing of time values.
165      - Add support for storing hosts, services, metrics, and attributes using
166        the new 'STORE' command.
167      - Fixed handling of subsequent requests on the same connection by
168        avoiding unnecessary pauses of up to one second, thus, greatly speeding
169        up request handling.
170      - Added support for TCP connections supporting, both, IPv4 and IPv6.
171        SSL/TLS is enforced for any such connection.
172      - Added support for and require actual client authentication:
173        UNIX socket connections require peer authentication.
174        TCP connections require client SSL certificate authentication.
175    * query language:
176      - Added support for expressions accessing an object's siblings by using
177        the '<object_type>.<sibling_type>' syntax.
178    * JSON format:
179      - Fixed handling of special characters which are now being escaped.
180      - Include a flag indicating whether time-series data are available for a
181        metric.
182    * utils:
183      - os: This utility module provides some Operating System related helper
184        functions: access user information (current user, homedir), manage
185        directories (create, delete, resolve), I/O helpers (select, read,
186        write), networking helpers (DNS resolution).
187      - proto: Added support for marshaling and unmarshaling messages encoding
188        a datum of any type, hosts, services, metrics, and attributes.
189      - ssl: This new module provides convenience functions for SSL/TLS
190        servers, clients, and sessions using OpenSSL.
192   Backends:
193    * facter: Added a plugin collecting local facter fact values using
194      libcfacter (C++).
196   Stores:
197    * store::network: Added a store-writer plugin sending all data to another
198      SysDB instance using the client library and low-level STORE commands.
200   Plugins:
201    * syslog: The log-level is now configurable using the "LogLevel" option.
203 Version 0.6.0, Release Date: 2014-11-17
204 ---------------------------------------
206   This release focuses on a clearer query language. The underlying
207   architecture has been refactored to allow for more powerful and generic
208   expressions.
210    * core:
211      - Added support for arrays. Elements may be of any other supported
212        data-type but only integers, decimals, and strings are fully supported.
213    * store:
214      - Refactored matchers: all matchers now operate on one or two expressions
215        or other matchers, replacing the old and less flexible conditional
216        matchers.
217      - Attribute values may now be used anywhere in an expression.
218      - On data-type mismatch when comparing attribute values, the values will
219        be cast to string (previously only done for regex matches).
220      - Added support for querying an object's backends (array of strings).
221      - Added support for iterating child objects and array values.
222      - All matchers now return false if any operand is NULL (except for IS
223        NULL).
224      - All operations now return NULL if any operand is NULL.
225      - Fixed behavior of not-operators (!=, !~) and let them not match if any
226        of the operands is NULL.
227      - Add support for looking up all object types (hosts, services, metrics).
228      - Refactored the JSON formatter to be more flexible and powerful.
229      - Record parent objects for each stored object.
230    * frontend:
231      - Added a separate parser mode for expressions.
232      - Added a new queryable field 'name' to be used in place of the rather
233        magical keyword 'host' when looking up hosts.
234      - Improved error reporting in the parser and the (newly introduced)
235        analyzer.
236      - Apply filters to hosts in the FETCH command.
237    * query language:
238      - All operators may now be used in all places if the involved data-types
239        support the respective operation. For example, regular expressions may
240        be used to match any value. Non-string values are cast to strings for
241        that purpose. IS NULL / IS NOT NULL may be applied to arbitrary
242        expressions.
243      - Introduced the 'IN' operator to check if a value or an array of values
244        is included in an array.
245      - Added support for arrays: [<elem1>,<elem2>,...]
246      - Added support for string and array concatenation using the '||'
247        operator.
248      - Attribute names have to be strings instead of identifiers now.
249      - Access object fields using '<field>' rather than '.<field>'.
250      - Let the LOOKUP and FETCH commands support services and metrics.
251      - Introduced 'FETCH service|metric <host>.<name' for fetching services
252        and metrics.
253      - Added support for 'ANY' and 'ALL' operators which apply a matcher to
254        each value emitted by an iterator (a host's services and metrics or
255        arrays). 'MATCHING ANY service|metric|attribute <cmp> <expr>' replaces
256        'MATCHING service|metric|attribute <cmp> <value>' expressions.
258 Version 0.5.0, Release Date: 2014-10-06
259 ---------------------------------------
261   This release focuses on simplifications and more flexibility in the frontend
262   and the query language. Most of those changes are not backward-compatible
263   but easy client implementations.
265    * sysdb:
266      - Include priority when printing log messages.
267      - Fixed handling of empty queries.
268    * store:
269      - When serializing the entire store (LIST command), return an array of
270        host objects (rather than wrapping it into another object).
271      - Fixed JSON format of time-series data.
272      - Fixed error checks of invalid compare expressions and reject them.
273      - Fixed lookups by back-end name.
274      - Added support for comparing attributes with different types by
275        comparing their string values.
276    * frontend:
277      - Clarified details about asynchronous messages and authentication
278        options and made client implementation more robust.
279      - Introduced a new message type encoding the JSON serialized response of
280        a query and its data type.
281      - Include the priority in log messages.
282      - Include object types in FETCH, LIST, and LOOKUP messages.
283      - Added support for including services and metrics in LIST responses and
284        skip hosts without the respective children.
285    * query language:
286      - Added support for services and metrics to LIST command.
287      - Changed syntax for attribute lookup to 'attributes[<name>]'.
288      - Changed syntax for accessing queryable fields to '.<field>'.
289    * utils:
290      - strbuf: Improved memory management.
292 Version 0.4.0, Release Date: 2014-09-01
293 ---------------------------------------
295   This release features support for metrics and transparent access to a
296   backend's time-series data. Some backward-incompatible changes were applied
297   to some query commands for more consistency.
299    * build system:
300      - Added checks for format strings and arguments.
301      - Changed configure option for collectd::unixsock to
302        --enable-collectd-unixsock.
303    * core:
304      - Added support for “metric” objects which may be assigned to a host.
305      - Introduced support for handling time-series data: added new data
306        structures describing time-series data and a new type of plugins called
307        “time-series fetchers” which are used to access time-series
308        information.
309    * store:
310      - Fixed a memory leak.
311      - Apply (very) simple optimizations to lookup expressions.
312      - Added support for metrics and their “data-stores” (describing how to
313        access the actual data referenced by a metric).
314      - Added support for querying time-series data through the newly
315        introduced “time-series fetcher” plugins.
316    * frontend:
317      - Fixed a bug that might have caused reading too much data from the
318        connection buffer in certain situations.
319    * query language:
320      - The ‘MATCHING’ clause is now optional in ‘LOOKUP’ queries.
321      - The ‘LIST’ and ‘FETCH’ commands support ‘FILTER’ clauses as well.
322      - ‘LIST’ / ‘FETCH’ were changed to ‘LIST hosts’ / ‘FETCH host’.
323      - Added the ‘TIMESERIES’ command to query arbitrary time-series which
324        fetches time-series data from a backend's data-store for a given period
325        of time.
326      - Added support for date/time values.
327      - Added support for single quotes in string values: two adjacent single
328        quotes may be used to specify a single quote.
329    * documentation:
330      - Documented the frontend protocol in frontend/proto.h.
331      - Documented changes to the query language and new / updated plugins.
332      - Documented all supported data types.
334   Backends:
335    * collectd::unixsock:
336      - The plugin now uses metrics in place of services.
337      - New config options ‘TimeseriesBackend’ and ‘TimeseriesBaseURL’ to
338        specify access to time-series, currently limited to ‘rrdtool’ and
339        ‘rrdcached’ access.
341   Plugins:
342    * timeseries::rrdtool:
343      - New plugin adding support to fetch time-series from local RRD files.
344      - Supports flushing of values in RRDCacheD.
346 Version 0.3.0, Release Date: 2014-08-01
347 ---------------------------------------
349   This release includes major enhancements and new features in the SysDB store
350   which is the core of the database. Most notably, complex expressions are now
351   supported when looking up information and filters may be used to preselect
352   the information to be returned. Some backward-incompatible changes were
353   introduced in the query language to avoid potentially confusing semantics.
355    * sysdb: Fixed non-interactive mode when using libedit.
356    * core:
357      - Fixed weird behavior when collector callbacks were registered without
358        any plugin context information (as it would, e.g., happen when using
359        LoadPlugin instead of LoadBackend in sysdbd).
360    * store:
361      - Introduced service attributes -- similar to host attributes but
362        assigned to a service object.
363      - Don't log “value too old” messages if an updated object uses the same
364        timestamp as the old object.
365      - Switched from linked-lists to AVL trees for storing all object types to
366        reduce lookup times from O(n) to O(log n).
367      - Added infrastructure for handling and evaluating arithmetic
368        expressions and filters (see also the changes to the query language
369        below).
370      - Export various fields describing base attributes of all stored object
371        types: last_update, age, interval, and backend. These fields may be
372        used when querying the store.
373    * frontend: Include new service attributes in JSON output.
374    * query language:
375      - Added support for ‘IS NULL’ attribute checks matching on non-existent
376        attributes.
377      - Changed ‘LOOKUP ... WHERE’ queries to ‘LOOKUP ... MATCHING’ to avoid
378        confusion with SQL semantics.
379      - Switched from ‘<obj>.name’ to ‘<obj>’ in MATCHING clauses, thus, no
380        longer shadowing attributes called “name”.
381      - Added support for arithmetic expressions in places that used simple
382        data values before. Arithmetic expressions support addition,
383        subtraction, multiplication, division, modulo, and concatenation
384        operations. The expressions may be based on constant values or
385        queryable fields of the stored objects (specified as ‘:last_update’,
386        ‘:age’, ‘:interval’, and ‘:backend’).
387      - Added ‘FILTER’ support to ‘LOOKUP’ queries. Filters are conditional
388        expressions which may optionally be used to limit the query and the
389        result to object (of any type) matching the filter condition.
390      - Added support to specify date and time values.
391    * utils:
392      - avltree: Added an AVL tree (self-balancing binary tree) implementation.
393    * documentation: Added documentation for the new query language features.
394    * testing: Run all unit tests through valgrind by default (if available).
396   Backends:
397    * collectd::unixsock:
398      - Added support for spaces in identifiers.
399      - Store plugin identifier (host, plugin, plugin_instance, type,
400        type_instance) as service attributes.
402 Version 0.2.0, Release Date: 2014-07-02
403 ---------------------------------------
405   This is another development snapshot of SysDB. The main focus of this
406   release is on stabilizing existing features and extending the query
407   infrastructure to support all attribute types and further operators.
409    * build system: Fixed linking of sysdbd to include *all* necessary object
410      files. This bug caused some plugins to be un-loadable.
411    * sysdbd: Fixed shutdown process in case of errors.
412    * sysdb: Fixed a bug causing some server replies to be ignored when exiting
413      from the client.
414    * core:
415      - Always log to the standard output stream if no user-provided logging
416        callbacks had been specified. Previously this was disabled after
417        enabling logging to clients in the frontend.
418      - Simplified plugin naming information and determine configuration
419        callback names automatically to ensure better consistency.
420    * store:
421      - Simplified internal data management.
422      - Store the list of backends along with each stored object which provide
423        the respective object.
424    * frontend:
425      - Simplified and improved the internal architecture matching / looking up
426        objects.
427      - Fixed parser to correctly reject invalid object types.
428      - Automatically create the base directory of a listening UNIX socket.
429    * query language: Added support for numeric constants and added operators
430      for less and greater than or equal attribute comparison.
431    * documentation: Added missing files to the distribution tarball.
433   Plugins:
434    * syslog: Don't log debug messages to syslog.
436 Version 0.1.0, Release Date: 2014-06-01
437 ---------------------------------------
439   This is the initial release of SysDB. It provides the following core
440   features:
442    * sysdb: A terminal-based, interactive client program. Supports
443      line-editing and history based on libreadline or libedit and uses an
444      asynchronous, event-driven architecture to handle user input and server
445      replies simultaneously.
446    * sysdbd: The database backend service configurable through a configuration
447      file. The daemon supports online reconfiguration.
448    * core: Flexible, multi-threaded core architecture providing a configurable
449      plugin infrastructure for querying external data-sources and extending
450      core functionality. The following plugin types are supported:
451      - data collection
452      - hostname canonicalization
453      - logging
454    * store: Central, in-memory object store managing host and service objects
455      and their attributes. Host names may be canonicalized through respective
456      plugins. Each object is automatically attributed with last update and
457      interval information using nano-seconds resolution. Attributes may have
458      various types (integer, decimal, string, date-time, binary).
459    * frontend: The frontend handling client connections uses a multi-threaded,
460      asynchronous, event-driven architecture capable of handling multiple
461      listen addresses.
462    * query language: The store may be queried using the ‘LIST’, ‘LOOKUP’, and
463      ‘FETCH’ commands returning JSON formatted objects.
464    * utils: A rich set of abstract data-types and utility functions for
465      internal use:
466      - generic channels for asynchronous, multi-threaded I/O
467      - DBI wrapper to ease common database access operations
468      - thread-aware error handling and reporting
469      - doubly linked-lists
470      - dynamic sized memory buffers supporting formatted strings and binary
471        data
472      - UNIX socket client implementation
473    * documentation: Full documentation for the tools, all plugins, and the
474      query language provided as manpages and HTML pages.
475    * testing: Unit and integration tests exist for most parts except plugins
476      covering 77% of all functions. Valgrind and Clang's address sanitzer are
477      used to detect memory leaks and programming errors.
479   The following plugins are shipped with this version of SysDB:
481   Backends:
482    * collectd::unixsock: Query collectd through its ‘unixsock’ interface
483    * mk-livestatus: Query arbitrary (monitoring) systems using the Check_MK
484      Livestatus interface.
485    * puppet::store-configs: Query Puppet through its “stored configuration”
486      database.
488   Plugins:
489    * cname::dns: Canonicalize hostnames by querying DNS information.
490    * syslog: Send log messages to the system log service.