README

   1  collection 4 - An efficient graphing front-end for collectd
   2 =============================================================
   3
   4 About
   5 -----
   6
   7   collection 4 (c4) is a web-based front-end to the RRD files updated by
   8   collectd. It is designed to be highly efficient and handle large
   9   installations - with 50,000 and more RRD files - well.
  10
  11
  12 Concepts
  13 --------
  14
  15   Graphs
  16   ------
  17   c4 lets you configure "graphs" in its config file. Each graph has a selector
  18   which determines which files will be used to draw the graph. The selector
  19   uses the host/plugin[-instance]/type[-instance] layout known from collectd.
  20   Each field of the selector may be one of two wildcard expressions:
  21
  22     * "/any/"
  23       The field may be any value. The files will be grouped by the values of
  24       all "/any/" fields. Think of the "GROUP BY" SQL expression. Each grouping
  25       is called an "instance" which can be identified by the graph selector and
  26       the value of the "/any/" fields.
  27
  28     * "/all/"
  29       As with the any-selector, the field may be any value. However, all files
  30       that only differ in the "/all/" field(s) will be printed in the same
  31       graph.
  32
  33   Upon startup, c4 will read the configuration and scan the directory
  34   containing the RRD files. Each file is added to all matching graphs, either
  35   by adding it to the appropriate instance or by creating a new instance. I.e.
  36   each file may be used in multiple graphs.
  37
  38   If a file does not match any graph, a "dynamic graph" matching only that file
  39   will be created. This allows the front-end to display all files even when
  40   there is no explicit graph definition for them.
  41
  42   Data providers
  43   --------------
  44   The idea is to encapsulate all the functions specific to one write plugin of
  45   collectd using an interface for querying data. This allows to program the
  46   rest of the front-end in a way that doesn't rely on one specific storage
  47   back-end.
  48
  49   Currently, the only data provider scans a directory for RRD files and uses
  50   the librrd to fetch data. The whole concept is still a bit of a work in
  51   progress and currently the code-base is still cluttered with "*_get_rrdargs"
  52   functions. The RRDtool generated graphs will likely be replaced by a graphing
  53   solution integrated in the C code (creating rendered graphics) and / or a
  54   JavaScript-based solution which renders graphs in the browser.
  55
  56
  57 License
  58 -------
  59
  60   collection 4 is licensed under the GNU Lesser General Public License (LGPL),
  61   version 2.1. The exact license terms are available in the file "COPYING" in
  62   the top source directory.
  63
  64
  65 Author
  66 ------
  67
  68   Florian "octo" Forster <ff at octo.it>
  69