From 0288de1f23f1c56d4327055d1eef2866845bc4d4 Mon Sep 17 00:00:00 2001
From: Florian Forster <octo@collectd.org>
Date: Sun, 20 Nov 2016 22:53:34 +0100
Subject: [PATCH] collectd.conf(5): Rename DSType from Latency to Distribution.

---
 src/collectd.conf.in  | 23 +++++++++---------
 src/collectd.conf.pod | 67 ++++++++++++++++++++++++++++++++-------------------
 2 files changed, 53 insertions(+), 37 deletions(-)

diff --git a/src/collectd.conf.in b/src/collectd.conf.in
index 4d1190ec..4165aeaf 100644
--- a/src/collectd.conf.in
+++ b/src/collectd.conf.in
@@ -1260,18 +1260,17 @@
 #    Instance "apache"
 #    <Match>
 #      Regex "^\\S+ \"([0-9.]+)\""
-#      DSType "Latency"
-#      Type "response_time"
-#      #LatencyPercentileType "percentile"
-#      LatencyPercentile 5
-#      LatencyPercentile 30
-#      LatencyPercentile 50
-#      LatencyPercentile 70
-#      LatencyPercentile 95
-#      LatencyRateType "requests"
-#      LatencyRate 0     0.100
-#      LatencyRate 0.100 0.200
-#      LatencyRate 0.200 0
+#      DSType "Distribution"
+#      Type "latency"
+#      Percentile 80    # -> latency-foo-80
+#      Percentile 95    # -> latency-foo-95
+#      Percentile 99    # -> latency-foo-99
+#      Bucket 0   0.1   # -> bucket-latency-foo-0_0.1
+#      Bucket 0.1 0.2   # -> bucket-latency-foo-0.1_0.2
+#      Bucket 0.2 0.5   # -> bucket-latency-foo-0.2_0.5
+#      Bucket 0.5 1.0   # -> bucket-latency-foo-0.5_1
+#      Bucket 1.0 2.0   # -> bucket-latency-foo-1_2
+#      Bucket 2.0 0     # -> bucket-latency-foo-2_inf
 #    </Match>
 #  </File>
 #</Plugin>
diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index d9c4aac2..c54ec317 100644
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
@@ -6957,6 +6957,20 @@ user using (extended) regular expressions, as described in L<regex(7)>.
         Type "counter"
         Instance "local_user"
       </Match>
+      <Match>
+        Regex "l=([0-9]*\\.[0-9]*)"
+        DSType "Distribution"
+        Type "latency"
+        Instance "foo"
+        Percentile 80    # -> latency-foo-80
+        Percentile 95    # -> latency-foo-95
+        Percentile 99    # -> latency-foo-99
+        Bucket 0   0.1   # -> bucket-latency-foo-0_0.1
+        Bucket 0.1 0.2   # -> bucket-latency-foo-0.1_0.2
+        Bucket 0.2 0.5   # -> bucket-latency-foo-0.2_0.5
+        Bucket 0.5 1.0   # -> bucket-latency-foo-0.5_1
+        Bucket 1.0 2.0   # -> bucket-latency-foo-1_2
+        Bucket 2.0 0     # -> bucket-latency-foo-2_inf
     </File>
   </Plugin>
 
@@ -7048,13 +7062,17 @@ Increase the internal counter by one. These B<DSType> are the only ones that do
 not use the matched subexpression, but simply count the number of matched
 lines. Thus, you may use a regular expression without submatch in this case.
 
-=item B<Latency>
+=item B<Distribution>
 
-Special type to handle latency values from logfiles. The matched value must be
-latency in seconds, floating point numbers are supported.
-Should be used with B<LatencyPercentile> or B<LatencyRate> options.
+Type to do calculations based on the distribution of values, primarily
+calculating percentiles. This is primarily geared towards latency, but can be
+used for ther metrics as well. The range of values tracked with this setting
+must be in the range (0–2^34) and can be fractional. Please note that neither
+zero nor 2^34 are inclusive bounds, i.e. zero I<cannot> be handled by a
+distribution.
 
-The B<Instance> option cannot be used together with B<DSType> B<Latency>.
+This option must be used together with the B<Percentile> option and/or the
+B<Bucket> option.
 
 =back
 
@@ -7074,33 +7092,32 @@ their configuration can be found in L<types.db(5)>.
 
 This optional setting sets the type instance to use.
 
-=item B<LatencyPercentile> I<Percent>
-
-Calculate and dispatch the configured percentile, i.e. compute the latency, so
-that I<Percent> of all matched latency values are smaller than or equal to the
-computed latency.
-
-Different percentiles can be calculated by setting this option several times.
+=item B<Percentile> I<Percent>
 
-=item B<LatencyPercentileType> I<Type>
+Calculate and dispatch the configured percentile, i.e. compute the value, so
+that I<Percent> of all matched values are smaller than or equal to the computed
+latency.
 
-Sets the type used to dispatch B<LatencyPercentile> values.
+Metrics are reported with the I<type> B<Type> (the value of the above option)
+and the I<type instance> C<[E<lt>InstanceE<gt>-]E<lt>PercentE<gt>>.
 
-=item B<LatencyRate> I<lower_latency> I<upper_latency>
+This option must be used with C<DSType Distribution>.
+It may be repeated to calculate more than one percentile.
 
-Calculate and dispatch rate of latency values fall within requested interval.
-Both, I<lower_latency> and I<upper_latency> is a duration in seconds and can be
-a fractional number, such as B<0.5>. The settings specify the interval
-C<(I<lower_latency>, I<upper_latency>]>, i.e. the range I<excludes> the lower
-bound and I<includes> the upper bound. I<lower_latency> and I<upper_latency>
-can be zero, meaning no lower/upper bound.
+=item B<Bucket> I<lower_bound> I<upper_bound>
 
-Rates for different intervals can be calculated by setting this option several
-times.
+Export the number of values (a C<DERIVE>) falling within the given range.
+Both, I<lower_bound> and I<upper_bound> must be greater than or equal to zero
+and may be a fractional number, such as B<0.5>. The setting specifies the
+interval C<(I<lower_bound>, I<upper_bound>]>, i.e. the range I<excludes> the
+lower bound and I<includes> the upper bound. I<lower_bound> and I<upper_bound>
+may be zero, meaning no lower/upper bound.
 
-=item B<LatencyRateType> I<Type>
+Metrics are reported with the I<type> C<bucket> and the I<type instance>
+C<E<lt>TypeE<gt>[-E<lt>InstanceE<gt>]-E<lt>lower_boundE<gt>_E<lt>upper_boundE<gt>>.
 
-Sets the type used to dispatch B<LatencyRate> values.
+This option must be used with C<DSType Distribution>.
+It may be repeated to calculate more than one rate.
 
 =back
 
-- 
2.11.0