1 module Database.RRDtool
18 , VariableShiftPredictOp(..)
19 , FixedShiftPredictOp(..)
21 , AggregativeUnaryOp(..)
28 import Data.Time.Clock
29 import Data.Time.Clock.POSIX
32 -- |A single RRD can accept input from several data sources (DS), for
33 -- example incoming and outgoing traffic on a specific communication
34 -- line. With the DS configuration option you must define some basic
35 -- properties of each data source you want to store in the RRD.
37 -- /NOTE on COUNTER vs DERIVE/
39 -- by Don Baarda <don.baarda@baesystems.com>
41 -- If you cannot tolerate ever mistaking the occasional counter reset
42 -- for a legitimate counter wrap, and would prefer \"Unknowns\" for
43 -- all legitimate counter wraps and resets, always use DERIVE with
44 -- @'dsMin' = 0@. Otherwise, using COUNTER with a suitable max will
45 -- return correct values for all legitimate counter wraps, mark some
46 -- counter resets as \"Unknown\", but can mistake some counter resets
47 -- for a legitimate counter wrap.
49 -- For a 5 minute step and 32-bit counter, the probability of
50 -- mistaking a counter reset for a legitimate wrap is arguably about
51 -- 0.8% per 1Mbps of maximum bandwidth. Note that this equates to 80%
52 -- for 100Mbps interfaces, so for high bandwidth interfaces and a
53 -- 32bit counter, DERIVE with @'dsMin' = 0@ is probably preferable. If
54 -- you are using a 64bit counter, just about any max setting will
55 -- eliminate the possibility of mistaking a reset for a counter wrap.
57 = -- |GAUGE is for things like temperatures or number of people in
58 -- a room or the value of a RedHat share.
60 -- |The name you will use to reference this particular data
61 -- source from an RRD. A ds-name must be 1 to 19 characters
62 -- long in the characters @[a-zA-Z0-9_]@.
64 -- |Defines the maximum number of seconds that may
65 -- pass between two updates of this data source before the
66 -- value of the data source is assumed to be @*UNKNOWN*@.
67 , dsHeartbeat :: !NominalDiffTime
68 -- |'dsMin' and 'dsMax' Define the expected range values for
69 -- data supplied by a data source. If 'dsMin' and\/or 'dsMax'
70 -- any value outside the defined range will be regarded as
71 -- @*UNKNOWN*@. If you do not know or care about 'dsMin' and
72 -- 'dsMax', set them to 'Nothing' for unknown. Note that
73 -- 'dsMin' and 'dsMax' always refer to the processed values of
74 -- the DS. For a traffic-'COUNTER' type DS this would be the
75 -- maximum and minimum data-rate expected from the device.
77 -- If information on minimal\/maximal expected values is
78 -- available, always set the min and\/or max properties. This
79 -- will help RRDtool in doing a simple sanity check on the
80 -- data supplied when running update.
81 , dsMin :: !(Maybe Double)
83 , dsMax :: !(Maybe Double)
85 -- |COUNTER is for continuous incrementing counters like the
86 -- ifInOctets counter in a router. The COUNTER data source assumes
87 -- that the counter never decreases, except when a counter
88 -- overflows. The update function takes the overflow into
89 -- account. The counter is stored as a per-second rate. When the
90 -- counter overflows, RRDtool checks if the overflow happened at
91 -- the 32bit or 64bit border and acts accordingly by adding an
92 -- appropriate value to the result.
95 , dsHeartbeat :: !NominalDiffTime
96 , dsMin :: !(Maybe Double)
97 , dsMax :: !(Maybe Double)
99 -- |DERIVE will store the derivative of the line going from the
100 -- last to the current value of the data source. This can be
101 -- useful for gauges, for example, to measure the rate of people
102 -- entering or leaving a room. Internally, derive works exactly
103 -- like COUNTER but without overflow checks. So if your counter
104 -- does not reset at 32 or 64 bit you might want to use DERIVE and
105 -- combine it with a 'dsMin' value of 0.
108 , dsHeartbeat :: !NominalDiffTime
109 , dsMin :: !(Maybe Double)
110 , dsMax :: !(Maybe Double)
112 -- |ABSOLUTE is for counters which get reset upon reading. This is
113 -- used for fast counters which tend to overflow. So instead of
114 -- reading them normally you reset them after every read to make
115 -- sure you have a maximum time available before the next
116 -- overflow. Another usage is for things you count like number of
117 -- messages since the last update.
120 , dsHeartbeat :: !NominalDiffTime
121 , dsMin :: !(Maybe Double)
122 , dsMax :: !(Maybe Double)
124 -- |COMPUTE is for storing the result of a formula applied to
125 -- other data sources in the RRD. This data source is not supplied
126 -- a value on update, but rather its Primary Data Points (PDPs)
127 -- are computed from the PDPs of the data sources according to the
128 -- rpn-expression that defines the formula. Consolidation
129 -- functions are then applied normally to the PDPs of the COMPUTE
130 -- data source (that is the rpn-expression is only applied to
131 -- generate PDPs). In database software, such data sets are
132 -- referred to as \"virtual\" or \"computed\" columns.
135 | forall a. CommonExpr a => COMPUTE {
137 -- |rpn-expression defines the formula used to compute the
138 -- PDPs of a COMPUTE data source from other data sources in
139 -- the same \<RRD\>. It is similar to defining a CDEF argument
140 -- for the graph command. For COMPUTE data sources, the
141 -- following RPN operations are not supported: COUNT, PREV,
142 -- TIME, and LTIME. In addition, in defining the RPN
143 -- expression, the COMPUTE data source may only refer to the
144 -- names of data source listed previously in the create
145 -- command. This is similar to the restriction that CDEFs must
146 -- refer only to DEFs and CDEFs previously defined in the same
156 -- , dsExpr = Previous :<: Const 100
157 -- , dsExpr = Var "foo" :<: Const 100
158 , dsExpr = Average (Const 100 .*. Const 200 .*. HNil)
161 class (Show e, Eq e) => Expr e
162 class Expr e => CommonExpr e
163 class Expr e => IterativeExpr e
164 class Expr e => AggregativeExpr e
165 instance CommonExpr e => IterativeExpr e
166 instance CommonExpr e => AggregativeExpr e
168 class (Show es, Eq es, HList es) => ExprSet es
169 instance ExprSet HNil
170 instance (Expr e, ExprSet es) => ExprSet (HCons e es)
172 class (Show es, Eq es, HList es) => CommonExprSet es
173 instance CommonExprSet es => ExprSet es
174 instance CommonExprSet HNil
175 instance (CommonExpr e, CommonExprSet es) => CommonExprSet (HCons e es)
178 -- Constants and variable names
181 deriving (Show, Eq, Ord)
182 instance Expr Constant
183 instance CommonExpr Constant
187 deriving (Show, Eq, Ord)
188 instance Expr Variable
189 instance CommonExpr Variable
207 | TrendNan !Variable !a
208 deriving (Show, Eq, Ord)
209 instance Expr a => Expr (CommonUnaryOp a)
210 instance CommonExpr a => CommonExpr (CommonUnaryOp a)
212 data CommonBinaryOp a b
228 deriving (Show, Eq, Ord)
229 instance (Expr a, Expr b)
230 => Expr (CommonBinaryOp a b)
231 instance (CommonExpr a, CommonExpr b)
232 => CommonExpr (CommonBinaryOp a b)
234 data CommonTrinaryOp a b c
237 deriving (Show, Eq, Ord)
238 instance (Expr a, Expr b, Expr c)
239 => Expr (CommonTrinaryOp a b c)
240 instance (CommonExpr a, CommonExpr b, CommonExpr c)
241 => CommonExpr (CommonTrinaryOp a b c)
243 -- SORT and REV can't be expressed in this way as they pushes possibly
244 -- multiple values onto the stack...
248 deriving (Show, Eq, Ord)
249 instance ExprSet es => Expr (CommonSetOp es)
250 instance CommonExprSet es => CommonExpr (CommonSetOp es)
252 data VariableShiftPredictOp ss w
253 = VariableShiftPredictAverage !ss !w !Variable
254 | VariableShiftPredictSigma !ss !w !Variable
255 deriving (Show, Eq, Ord)
256 instance (ExprSet ss, Expr w)
257 => Expr (VariableShiftPredictOp ss w)
258 instance (CommonExprSet ss, CommonExpr w)
259 => CommonExpr (VariableShiftPredictOp ss w)
261 data FixedShiftPredictOp sm w
262 = FixedShiftPredictAverage !sm !w !Variable
263 | FixedShiftPredictSigma !sm !w !Variable
264 deriving (Show, Eq, Ord)
265 instance (Expr sm, Expr w)
266 => Expr (FixedShiftPredictOp sm w)
267 instance (CommonExpr sm, CommonExpr w)
268 => CommonExpr (FixedShiftPredictOp sm w)
270 -- Iterative special values
273 deriving (Show, Eq, Ord)
274 instance Expr IterativeValue
275 instance IterativeExpr IterativeValue
277 -- Aggregative operators
278 data AggregativeUnaryOp a
280 deriving (Show, Eq, Ord)
281 instance Expr a => Expr (AggregativeUnaryOp a)
282 instance AggregativeExpr a => AggregativeExpr (AggregativeUnaryOp a)
284 -- |The 'createRRD' function lets you set up new Round Robin Database
285 -- (RRD) files. The file is created at its final, full size and filled
286 -- with @*UNKNOWN*@ data.
288 :: FilePath -- ^The name of the RRD you want to create. RRD files
289 -- should end with the extension @.rrd@. However,
290 -- RRDtool will accept any filename.
291 -> Bool -- ^Do not clobber an existing file of the same name.
292 -> Maybe POSIXTime -- ^Specifies the time in seconds since
293 -- @1970-01-01 UTC@ when the first value should
294 -- be added to the RRD. RRDtool will not accept
295 -- any data timed before or at the time
296 -- specified. (default: @now - 10s@)
297 -> Maybe NominalDiffTime -- ^Specifies the base interval in
298 -- seconds with which data will be fed
299 -- into the RRD. (default: 300 sec)
300 -> [DataSource] -- ^Data sources to accept input from.
302 createRRD = error "FIXME"