X-Git-Url: https://git.octo.it/?p=collection4.git;a=blobdiff_plain;f=README;h=ba153697efcab51d923228633224eb707a0e2b43;hp=e69de29bb2d1d6434b8b29ae775ad8c2e48c5391;hb=e3fb09073a64cc051c11c4a1bdcec493f937b764;hpb=0ab3085f89e64eecd67d3179ea87f0463e918a10

diff --git a/README b/README
index e69de29..ba15369 100644
--- a/README
+++ b/README
@@ -0,0 +1,124 @@
+ collection 4 - An efficient graphing front-end for collectd
+=============================================================
+<http://octo.it/c4/>
+
+About
+-----
+
+  collection 4 (c4) is a web-based front-end to the RRD files updated by
+  collectd. It is designed to be highly efficient and handle large
+  installations - with 50,000 and more RRD files - well.
+
+
+Concepts
+--------
+
+  Graphs
+  ------
+  c4 lets you configure "graphs" in its config file. Each graph has a selector
+  which determines which files will be used to draw the graph. The selector
+  uses the host/plugin[-instance]/type[-instance] layout known from collectd.
+  Each field of the selector may be one of two wildcard expressions:
+
+    * "/any/"
+      The field may be any value. The files will be grouped by the values of
+      all "/any/" fields. Think of the "GROUP BY" SQL expression. Each grouping
+      is called an "instance" which can be identified by the graph selector and
+      the value of the "/any/" fields.
+
+    * "/all/"
+      As with the any-selector, the field may be any value. However, all files
+      that only differ in the "/all/" field(s) will be printed in the same
+      graph.
+
+  Upon startup, c4 will read the configuration and scan the directory
+  containing the RRD files. Each file is added to all matching graphs, either
+  by adding it to the appropriate instance or by creating a new instance. I.e.
+  each file may be used in multiple graphs.
+
+  If a file does not match any graph, a "dynamic graph" matching only that file
+  will be created. This allows the front-end to display all files even when
+  there is no explicit graph definition for them.
+
+  Data providers
+  --------------
+  The idea is to encapsulate all the functions specific to one write plugin of
+  collectd using an interface for querying data. This allows to program the
+  rest of the front-end in a way that doesn't rely on one specific storage
+  back-end.
+
+  Currently, the only data provider scans a directory for RRD files and uses
+  the librrd to fetch data. The whole concept is still a bit of a work in
+  progress and currently the code-base is still cluttered with "*_get_rrdargs"
+  functions. The RRDtool generated graphs will likely be replaced by a graphing
+  solution integrated in the C code (creating rendered graphics) and / or a
+  JavaScript-based solution which renders graphs in the browser.
+
+  In the future it shall be possible to use multiple data providers in
+  parallel. The vision is to have multiple servers running RRDCacheD. Data is
+  distributed to those servers using the "Hashed" match of collectd and then a
+  unified interface is provided via c4.
+
+
+Dependencies
+------------
+
+  c4 currently requires the following libraries:
+
+  * libfcgi
+    <http://www.fastcgi.com/>
+
+  * librrd_th (thread-safe version of librrd)
+    <http://oss.oetiker.ch/rrdtool/>
+
+  * libyajl
+    <http://lloyd.github.com/yajl/>
+
+  The "configure" script is currently kept minimal. It may therefore be
+  necessary to set the CPP- and LD-flags manually. In case of libyajl, which is
+  not built with libtool, you may need to set the rpath, too.
+
+  When building from the Git repository, you'll need to have flex and bison (or
+  possibly lex and yacc) installed. These two programs are used to generate the
+  code for parsing the config file. If you are building from a tarball, the
+  generated .c and .h files are included and you don't need to have these
+  programs installed.
+
+
+Bugs
+----
+
+  * Sending a FLUSH command to the collectd process is not yet possible.
+  * "*_get_rrdargs" functions and other RRDtool specific cruft is still all
+    over the code-base.
+  * The JSON-based interface is unstable.
+  * Currently it's not possible to display more than one graph at a time.
+    (With a very limited and undocumented exception.)
+  * Speaking of which: There is no documentation.
+  * ... (to be added)
+
+
+License
+-------
+
+  collection 4 is licensed under the GNU Lesser General Public License (LGPL),
+  version 2.1. The exact license terms are available in the file "COPYING" in
+  the top source directory.
+
+  c4 includes the JavaScript library "jQuery" which is dual-licensed under the
+  MIT license and the GPL. The file "share/jquery-1.4.2.min.js" includes a
+  license header which points you to more detailed information.
+
+  c4 includes the JavaScript library "Highcharts" which is licensed under the
+  Creative Commons Attribution-NonCommercial 3.0 License (CC-by-nc 3.0). This
+  means that the library is free of charge for non-commercial use. The file
+  "share/highcharts.js" includes a license header which points you to more
+  detailed information. More information on Highcharts and licensing options is
+  available from <http://www.highcharts.com/>.
+
+
+Author
+------
+
+  Florian "octo" Forster <ff at octo.it>
+