← Back to branch summary

~graphite-dev/graphite/1.1

« back to all changes in this revision

Viewing changes to docs/config-carbon.rst

  • Committer: Chris Davis
  • Date: 2011-08-08 03:42:23 UTC
  • mfrom: (337.5.162 graphite)
  • Revision ID: chrismd@gmail.com-20110808034223-lrvejc3tfmyn6o9g
cherrypicking trunk revs 500-507

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/config-carbon.rst
15
15
--------------------
16
16
This file defines how much data to store, and at what precision.
17
17
Important notes before continuing:
 
18
 
18
19
* There can be many sections in this file.
19
20
* Each section must have a header in square brackets, a pattern and a retentions line.
20
 
* The sections are applied in order from the top (first) and bottom (last). 
 
21
* The sections are applied in order from the top (first) and bottom (last).
21
22
* The patterns are regular expressions, as opposed to the wildcards used in the URL API.
22
23
* The first pattern that matches the metric name is used.
23
 
* These are set at the time the first metric is sent. 
24
 
* Changing this file will not affect .wsp files already created on disk. Use whisper-resize.py to change those. 
 
24
* These are set at the time the first metric is sent.
 
25
* Changing this file will not affect .wsp files already created on disk. Use whisper-resize.py to change those.
25
26
* There are two very different ways to specify retentions. We will show the new, easier way first, and the old, more difficult way second for historical purposes second.
26
27
 
27
28
Here's an example:
28
29
 
29
30
.. code-block:: none
30
 
  
 
31
 
31
32
 [garbage_collection]
32
33
 pattern = garbageCollections$
33
34
 retentions = 10s:14d
41
42
Here's a more complicated example with multiple retention rates:
42
43
 
43
44
.. code-block:: none
44
 
  
 
45
 
45
46
 [apache_busyWorkers]
46
47
 pattern = servers\.www.*\.workers\.busyWorkers$
47
48
 retentions = 15s:7d,1min:21d,15min:5y
48
49
 
49
50
The pattern matches server names that start with 'www', followed by anything, that end in '.workers.busyWorkers'.  This way not all metrics associated with your webservers need this type of retention.  
50
51
 
51
 
As you can see there are multiple retentions.  Each is used in the order that it is provided.  As a general rule, they should be in most-precise:shortest-length to least-precise:longest-time.  Retentions are merely a way to save you disk space an decrease I/O for graphs that span a long period of time. When data moves from a higher precision to a lower precision, it is **averaged**.  This way, you can still find the **total** for a particular time period if you know the original precision.  
 
52
As you can see there are multiple retentions.  Each is used in the order that it is provided.  As a general rule, they should be in most-precise:shortest-length to least-precise:longest-time.  Retentions are merely a way to save you disk space and decrease I/O for graphs that span a long period of time. When data moves from a higher precision to a lower precision, it is **averaged**.  This way, you can still find the **total** for a particular time period if you know the original precision.  
52
53
 
53
54
Example: You store the number of sales per minute for 1 year, and the sales per hour for 5 years after that.  You need to know the total sales for January 1st of the year before.  You can query whisper for the raw data, and you'll get 24 datapoints, one for each hour.  They will most likely be floating point numbers.  You can take each datapoint, multiply by 60 (the ratio of high-precision to low-precision datapoints) and still get the total sales per hour.  
54
55
 
55
56
 
56
57
The old retentions was done as follows:
57
58
 
58
 
.. code-block:: none 
 
59
.. code-block:: none
59
60
 
60
61
  retentions = 60:1440
61
62
 
94
95
'output_template' filling in any captured fields from 'input_pattern'.
95
96
 
96
97
For example, if you're metric naming scheme is:
 
98
 
97
99
.. code-block:: none
98
100
 
99
101
  <env>.applications.<app>.<server>.<metric>
119
121
aggregate metric 'prod.applications.apache.all.requests' would be calculated
120
122
by summing their values.
121
123
 
122