Merge pull request #2204 from wridgers/willr--percentile-aggregation-…

…methods

Percentile aggregation documentation

docs/config-carbon.rst

@@ -161,13 +161,20 @@ The form of each line in this file should be as follows:
 
   output_template (frequency) = method input_pattern
 
-This will capture any received metrics that match 'input_pattern'
+This will capture any received metrics that match ``input_pattern``
 for calculating an aggregate metric. The calculation will occur
-every 'frequency' seconds and the 'method' can specify 'sum' or
-'avg'. The name of the aggregate metric will be derived from
-'output_template' filling in any captured fields from 'input_pattern'.
-Any metric that will arrive to ``carbon-aggregator`` will proceed to its
-output untouched unless it is overridden by some rule.
+every ``frequency`` seconds using a valid ``method``. The name of the aggregate
+metric will be derived from ``output_template`` filling in any captured
+fields from ``input_pattern``. Any metric that will arrive to
+``carbon-aggregator`` will proceed to its output untouched unless it
+is overridden by some rule.
+
+Available aggregation methods are: ``sum``, ``avg``, ``min``, ``max``, ``p50``, ``p75``, ``p80``, ``p90``, ``p95``, ``p99``, ``p999``, and ``count`` - where ``p50`` means 50th percentile and ``p999`` means 99.9th percentile, etc.
+
+Care should be taken when using percentile aggregation methods because re-aggregation does not work the way you might_ expect_. The utility of percentile aggregation however means they are provided if you wish to use them.
+
+.. _might: https://www.vividcortex.com/blog/why-percentiles-dont-work-the-way-you-think
+.. _expect: https://grafana.com/blog/2016/03/03/25-graphite-grafana-and-statsd-gotchas/#aggregating.percentiles
 
 For example, if your metric naming scheme is: