Database/RRDtool.hs

   1 module Database.RRDtool
   2     ( DataSource(..)
   3     , Expr(..)
   4     , createRRD
   5     )
   6     where
   7
   8 import Data.Time.Clock
   9 import Data.Time.Clock.POSIX
  10
  11
  12 -- |A single RRD can accept input from several data sources (DS), for
  13 -- example incoming and outgoing traffic on a specific communication
  14 -- line. With the DS configuration option you must define some basic
  15 -- properties of each data source you want to store in the RRD.
  16 --
  17 -- /NOTE on COUNTER vs DERIVE/
  18 --
  19 -- by Don Baarda <don.baarda@baesystems.com>
  20 --
  21 -- If you cannot tolerate ever mistaking the occasional counter reset
  22 -- for a legitimate counter wrap, and would prefer \"Unknowns\" for
  23 -- all legitimate counter wraps and resets, always use DERIVE with
  24 -- @'dsMin' = 0@. Otherwise, using COUNTER with a suitable max will
  25 -- return correct values for all legitimate counter wraps, mark some
  26 -- counter resets as \"Unknown\", but can mistake some counter resets
  27 -- for a legitimate counter wrap.
  28 --
  29 -- For a 5 minute step and 32-bit counter, the probability of
  30 -- mistaking a counter reset for a legitimate wrap is arguably about
  31 -- 0.8% per 1Mbps of maximum bandwidth. Note that this equates to 80%
  32 -- for 100Mbps interfaces, so for high bandwidth interfaces and a
  33 -- 32bit counter, DERIVE with @'dsMin' = 0@ is probably preferable. If
  34 -- you are using a 64bit counter, just about any max setting will
  35 -- eliminate the possibility of mistaking a reset for a counter wrap.
  36 data DataSource
  37     = -- |GAUGE is for things like temperatures or number of people in
  38       -- a room or the value of a RedHat share.
  39       GAUGE {
  40         -- |The name you will use to reference this particular data
  41         -- source from an RRD. A ds-name must be 1 to 19 characters
  42         -- long in the characters @[a-zA-Z0-9_]@.
  43         dsName :: !String
  44         -- |Defines the maximum number of seconds that may
  45         -- pass between two updates of this data source before the
  46         -- value of the data source is assumed to be @*UNKNOWN*@.
  47       , dsHeartbeat :: !NominalDiffTime
  48         -- |'dsMin' and 'dsMax' Define the expected range values for
  49         -- data supplied by a data source. If 'dsMin' and\/or 'dsMax'
  50         -- any value outside the defined range will be regarded as
  51         -- @*UNKNOWN*@. If you do not know or care about 'dsMin' and
  52         -- 'dsMax', set them to 'Nothing' for unknown. Note that
  53         -- 'dsMin' and 'dsMax' always refer to the processed values of
  54         -- the DS. For a traffic-'COUNTER' type DS this would be the
  55         -- maximum and minimum data-rate expected from the device.
  56         --
  57         -- If information on minimal\/maximal expected values is
  58         -- available, always set the min and\/or max properties. This
  59         -- will help RRDtool in doing a simple sanity check on the
  60         -- data supplied when running update.
  61       , dsMin :: !(Maybe Double)
  62         -- |See 'dsMin'.
  63       , dsMax :: !(Maybe Double)
  64       }
  65       -- |COUNTER is for continuous incrementing counters like the
  66       -- ifInOctets counter in a router. The COUNTER data source
  67       -- assumes that the counter never decreases, except when a
  68       -- counter overflows. The update function takes the overflow
  69       -- into account. The counter is stored as a per-second
  70       -- rate. When the counter overflows, RRDtool checks if the
  71       -- overflow happened at the 32bit or 64bit border and acts
  72       -- accordingly by adding an appropriate value to the result.
  73     | COUNTER {
  74         dsName      :: !String
  75       , dsHeartbeat :: !NominalDiffTime
  76       , dsMin       :: !(Maybe Double)
  77       , dsMax       :: !(Maybe Double)
  78       }
  79       -- |DERIVE will store the derivative of the line going from the
  80       -- last to the current value of the data source. This can be
  81       -- useful for gauges, for example, to measure the rate of people
  82       -- entering or leaving a room. Internally, derive works exactly
  83       -- like COUNTER but without overflow checks. So if your counter
  84       -- does not reset at 32 or 64 bit you might want to use DERIVE
  85       -- and combine it with a 'dsMin' value of 0.
  86     | DERIVE {
  87         dsName      :: !String
  88       , dsHeartbeat :: !NominalDiffTime
  89       , dsMin       :: !(Maybe Double)
  90       , dsMax       :: !(Maybe Double)
  91       }
  92       -- |ABSOLUTE is for counters which get reset upon reading. This
  93       -- is used for fast counters which tend to overflow. So instead
  94       -- of reading them normally you reset them after every read to
  95       -- make sure you have a maximum time available before the next
  96       -- overflow. Another usage is for things you count like number
  97       -- of messages since the last update.
  98     | ABSOLUTE {
  99         dsName      :: !String
 100       , dsHeartbeat :: !NominalDiffTime
 101       , dsMin       :: !(Maybe Double)
 102       , dsMax       :: !(Maybe Double)
 103       }
 104       -- |COMPUTE is for storing the result of a formula applied to
 105       -- other data sources in the RRD. This data source is not
 106       -- supplied a value on update, but rather its Primary Data
 107       -- Points (PDPs) are computed from the PDPs of the data sources
 108       -- according to the rpn-expression that defines the
 109       -- formula. Consolidation functions are then applied normally to
 110       -- the PDPs of the COMPUTE data source (that is the
 111       -- rpn-expression is only applied to generate PDPs). In database
 112       -- software, such data sets are referred to as \"virtual\" or
 113       -- \"computed\" columns.
 114       --
 115       -- FIXME: doc links
 116     | COMPUTE {
 117         dsName :: !String
 118       -- |rpn-expression defines the formula used to compute the PDPs
 119       -- of a COMPUTE data source from other data sources in the same
 120       -- \<RRD\>. It is similar to defining a CDEF argument for the
 121       -- graph command.  For COMPUTE data sources, the following RPN
 122       -- operations are not supported: COUNT, PREV, TIME, and
 123       -- LTIME. In addition, in defining the RPN expression, the
 124       -- COMPUTE data source may only refer to the names of data
 125       -- source listed previously in the create command. This is
 126       -- similar to the restriction that CDEFs must refer only to DEFs
 127       -- and CDEFs previously defined in the same graph command.
 128       --
 129       -- FIXME: doc links
 130       , dsExpr :: !Expr
 131       }
 132     deriving (Eq, Ord, Show)
 133
 134 data Expr
 135     = UNK
 136     deriving (Show, Eq, Ord)
 137
 138 -- |The 'createRRD' function lets you set up new Round Robin Database
 139 -- (RRD) files. The file is created at its final, full size and filled
 140 -- with @*UNKNOWN*@ data.
 141 createRRD
 142     :: FilePath -- ^The name of the RRD you want to create. RRD files
 143                 -- should end with the extension @.rrd@. However,
 144                 -- RRDtool will accept any filename.
 145     -> Bool -- ^Do not clobber an existing file of the same name.
 146     -> Maybe POSIXTime -- ^Specifies the time in seconds since
 147                        -- @1970-01-01 UTC@ when the first value should
 148                        -- be added to the RRD. RRDtool will not accept
 149                        -- any data timed before or at the time
 150                        -- specified. (default: @now - 10s@)
 151     -> Maybe NominalDiffTime -- ^Specifies the base interval in
 152                              -- seconds with which data will be fed
 153                              -- into the RRD. (default: 300 sec)
 154     -> [DataSource] -- ^Data sources to accept input from.
 155     -> IO ()
 156 createRRD = error "FIXME"