X-Git-Url: https://git.tokkee.org/?p=sysdb.git;a=blobdiff_plain;f=doc%2Fsysdb.7.txt;h=383784855281edd1b8372edcb460b62106b6f287;hp=9f217b314d127bc5271b8bba2d4bf3ca3d8756e1;hb=0a3dd5b9b97e25156412a95bcecf25f8d75c72fc;hpb=125e7cfb1cfb48c9d6654766abfae3dfea1030fe diff --git a/doc/sysdb.7.txt b/doc/sysdb.7.txt index 9f217b3..3837848 100644 --- a/doc/sysdb.7.txt +++ b/doc/sysdb.7.txt @@ -38,10 +38,70 @@ For details about the SysDB client, see its manual page manpage:sysdb[1]. For details about how to query the database, see the specification of the SysDB query language in manpage:sysdbql[7]. +CONCEPTS +-------- +SysDB's features are build around a set of concepts which are explained in +this section. + +Object Store +~~~~~~~~~~~~ +The central part of SysDB's database is the object store which stores all +objects (hosts, services) known to SysDB. The implementation is provided by a +"store" plugin and may be backed by arbitrary data-stores. At least one store +plugin has to be loaded to let the daemon do its work. + +Hosts and Services +~~~~~~~~~~~~~~~~~~ +The basic building block of SysDB's store are host and service objects +representing physical and logical resources. Each host is identified by a +unique name and each service is identified by a unique pair of a hostname and +a service name. All services are assigned to the respective host which is +usually interpreted as the service running on that host. In addition, hosts +and services may have a list of attributes assigned to them. These are +arbitrary key-value pairs providing additional information about the +respective object and they may be used to further categorize and identify an +object. For example, the *mk-livestatus* and *puppet::store-configs* backend +plugins provide a list of all hosts and services known to the monitoring +system queried through the Check_MK livestatus interface and all hosts will be +attributed with all "fact" values known to Puppet. This allows to query hosts +based on facts like architecture or LSB information using query commands like +*LOOKUP* (see manpage:sysdbql[7]). + +Host and service objects are provided and updated by backend plugins and +queried from other systems, like inventory databases or monitoring systems. + +Hostname Canonicalization +~~~~~~~~~~~~~~~~~~~~~~~~~ +Before storing an object in SysDB's store, any hostname used to identify the +object is canonicalized. This is done by so called "cname" plugins and may be +based on arbitrary information derived from the original hostname. This way, +hosts provided by different backends may be mapped to the same host in SysDB +even if, for example, one backend uses short hostnames while another uses +fully qualified domain names (FQDNs). For example, the *cname::dns* plugin +uses reverse DNS queries to resolve a name to its canonical hostname as +provided by DNS. + +Metrics and Time-Series +~~~~~~~~~~~~~~~~~~~~~~~ +A metric identifies performance data about a host. SysDB does not collect or +store the actual data but collects information about which metrics are +available from backends. It then provides a generic way to fetch time-series +data directly from a backend's data-store. In some cases, this requires +additional configuration. For example, the *collectd::unixsock* plugin +provides information about which metrics are available from a collectd +instance. Using the *TimeseriesBackend* and *TimeseriesBaseURL* configuration +options (see manpage:sysdbd-collectd-unixsock[5]), SysDB may be told where to +fetch time-series data from. The details are automatically managed by the +plugin and the *timeseries::rrdtool* plugin may be used to fetch the data from +RRD files managed by collectd. Fetching the data may be done using the +*TIMESERIES* query command (see manpage:sysdbql[7]). + SEE ALSO -------- manpage:sysdb[1], manpage:sysdbd[1], manpage:sysdbql[7] +The SysDB homepage: https://sysdb.io/ + AUTHOR ------ SysDB was written by Sebastian "tokkee" Harl .