README

   1  collection 4 - An efficient graphing front-end for collectd
   2 =============================================================
   3 <http://octo.it/c4/>
   4
   5 About
   6 -----
   7
   8   collection 4 (c4) is a web-based front-end to the RRD files updated by
   9   collectd. It is designed to be highly efficient and handle large
  10   installations - with 50,000 and more RRD files - well.
  11
  12
  13 Concepts
  14 --------
  15
  16   Graphs
  17   ------
  18   c4 lets you configure "graphs" in its config file. Each graph has a selector
  19   which determines which files will be used to draw the graph. The selector
  20   uses the host/plugin[-instance]/type[-instance] layout known from collectd.
  21   Each field of the selector may be one of two wildcard expressions:
  22
  23     * "/any/"
  24       The field may be any value. The files will be grouped by the values of
  25       all "/any/" fields. Think of the "GROUP BY" SQL expression. Each grouping
  26       is called an "instance" which can be identified by the graph selector and
  27       the value of the "/any/" fields.
  28
  29     * "/all/"
  30       As with the any-selector, the field may be any value. However, all files
  31       that only differ in the "/all/" field(s) will be printed in the same
  32       graph.
  33
  34   Upon startup, c4 will read the configuration and scan the directory
  35   containing the RRD files. Each file is added to all matching graphs, either
  36   by adding it to the appropriate instance or by creating a new instance. I.e.
  37   each file may be used in multiple graphs.
  38
  39   If a file does not match any graph, a "dynamic graph" matching only that file
  40   will be created. This allows the front-end to display all files even when
  41   there is no explicit graph definition for them.
  42
  43   Data providers
  44   --------------
  45   The idea is to encapsulate all the functions specific to one write plugin of
  46   collectd using an interface for querying data. This allows to program the
  47   rest of the front-end in a way that doesn't rely on one specific storage
  48   back-end.
  49
  50   Currently, the only data provider scans a directory for RRD files and uses
  51   the librrd to fetch data. The whole concept is still a bit of a work in
  52   progress and currently the code-base is still cluttered with "*_get_rrdargs"
  53   functions. The RRDtool generated graphs will likely be replaced by a graphing
  54   solution integrated in the C code (creating rendered graphics) and / or a
  55   JavaScript-based solution which renders graphs in the browser.
  56
  57   In the future it shall be possible to use multiple data providers in
  58   parallel. The vision is to have multiple servers running RRDCacheD. Data is
  59   distributed to those servers using the "Hashed" match of collectd and then a
  60   unified interface is provided via c4.
  61
  62
  63 Dependencies
  64 ------------
  65
  66   c4 currently requires the following libraries:
  67
  68   * libfcgi
  69     <http://www.fastcgi.com/>
  70
  71   * librrd_th (thread-safe version of librrd)
  72     <http://oss.oetiker.ch/rrdtool/>
  73
  74   * libyajl
  75     <http://lloyd.github.com/yajl/>
  76
  77   The "configure" script is currently kept minimal. It may therefore be
  78   necessary to set the CPP- and LD-flags manually. In case of libyajl, which is
  79   not built with libtool, you may need to set the rpath, too.
  80
  81   When building from the Git repository, you'll need to have flex and bison (or
  82   possibly lex and yacc) installed. These two programs are used to generate the
  83   code for parsing the config file. If you are building from a tarball, the
  84   generated .c and .h files are included and you don't need to have these
  85   programs installed.
  86
  87
  88 Bugs
  89 ----
  90
  91   * Sending a FLUSH command to the collectd process is not yet possible.
  92   * "*_get_rrdargs" functions and other RRDtool specific cruft is still all
  93     over the code-base.
  94   * The JSON-based interface is unstable.
  95   * Currently it's not possible to display more than one graph at a time.
  96     (With a very limited and undocumented exception.)
  97   * Speaking of which: There is no documentation.
  98   * ... (to be added)
  99
 100
 101 License
 102 -------
 103
 104   collection 4 is licensed under the GNU Lesser General Public License (LGPL),
 105   version 2.1. The exact license terms are available in the file "COPYING" in
 106   the top source directory.
 107
 108   c4 includes the JavaScript library "jQuery" which is dual-licensed under the
 109   MIT license and the GPL. The file "share/jquery-1.4.2.min.js" includes a
 110   license header which points you to more detailed information.
 111
 112   c4 includes the JavaScript libraries "Raphaël" and "gRaphaël" which are
 113   licensed under the MIT license. The files "share/raphael-min.js",
 114   "share/g.raphael-min.js", and "share/g.line-min.js" each include a license
 115   header which points you to more detailed information.
 116
 117
 118 Author
 119 ------
 120
 121   Florian "octo" Forster <ff at octo.it>
 122