2nd round of code reviews after major rework.

Author: beorn7

content/docs/practices/histograms.md

@@ -18,13 +18,7 @@ First of all, check the library support for
 both currently only exists in the Go client library. Many libraries
 support only one of the two types, or they support summaries only in a
 limited fashion (lacking [quantile
-calculation](#quantiles)). [Contributions are welcome](/community/),
-of course. In general, we expect histograms to be more urgently needed
-than summaries. Histograms are also easier to implement in a client
-library, so we recommend to implement histograms first, if in
-doubt. The reason why some libraries offer summaries but not
-histograms (Ruby, the legacy Java client) is that histograms are a
-more recent feature of Prometheus.
+calculation](#quantiles)).
 
 ## Count and sum of observations
 
@@ -35,20 +29,20 @@ durations or response sizes. They track the number of observations
 (showing up in Prometheus as a time series with a `_count` suffix) is
 inherently a counter (as described above, it only goes up). The sum of
 observations (showing up as a time series with a `_sum` suffix)
-behaves like a counter, too, as long as all observations are
-positive. Obviously, request durations or response sizes are always
-positive. In principle, however, you can use summaries and histograms
-to observe negative values (e.g. temperatures in centigrade). In that
-case, the sum of observations can go down, so you cannot apply
-`rate()` to it anymore.
+behaves like a counter, too, as long as there are no negative
+observations. Obviously, request durations or response sizes are
+never negative. In principle, however, you can use summaries and
+histograms to observe negative values (e.g. temperatures in
+centigrade). In that case, the sum of observations can go down, so you
+cannot apply `rate()` to it anymore.
 
 To calculate the average request duration during the last 5 minutes
 from a histogram or summary called `http_request_duration_second`, use
 the following expression:
 
-    rate(http_request_duration_seconds_sum[5m])
-      /
-    rate(http_request_duration_seconds_count[5m])
+      rate(http_request_duration_seconds_sum[5m])
+    /
+      rate(http_request_duration_seconds_count[5m])
 
 ## Apdex score
 
@@ -64,9 +58,9 @@ requests served within 300ms and easily alert if the value drops below
 served in the last 5 minutes. The request durations were collected with
 a histogram called `http_request_duration_seconds`.
 
-    sum(rate(http_request_duration_seconds_bucket{le="0.3"}[5m])) by (job)
-      /
-    sum(rate(http_request_duration_seconds_count[5m])) by (job)
+      sum(rate(http_request_duration_seconds_bucket{le="0.3"}[5m])) by (job)
+    /
+      sum(rate(http_request_duration_seconds_count[5m])) by (job)
 
 
 You can calculate the well-known [Apdex
@@ -75,13 +69,13 @@ a bucket with the target request duration as upper bound and another
 bucket with the tolerated request duration (usually 4 times the target
 request duration) as upper bound. Example: The target request duration
 is 300ms. The tolerable request duration is 1.2s. The following
-expression yields the Apdex score over the last 5 minutes:
+expression yields the Apdex score for each job over the last 5 minutes:
 
     (
-      rate(http_request_duration_seconds_bucket{le="0.3"}[5m])
-        +
-      rate(http_request_duration_seconds_bucket{le="1.2"}[5m])
-    ) / 2 / rate(http_request_duration_seconds_count[5m])
+      sum(rate(http_request_duration_seconds_bucket{le="0.3"}[5m])) by (job)
+    +
+      sum(rate(http_request_duration_seconds_bucket{le="1.2"}[5m])) by (job)
+    ) / 2 / sum(rate(http_request_duration_seconds_count[5m])) by (job)
 
 ## Quantiles
 
@@ -213,8 +207,18 @@ Two rules of thumb:
 
   1. If you need to aggregate, choose histograms.
 
-  2. Otherwise, choose a histogram if you need accuracy in the
-     dimension of the observed values and you have an idea in which
-     ranges of observed values you are interested in. Choose a summary
-     if you need accuracy in the dimension of φ, no matter in which
-     ranges of observed values the quantile will end up.
+  2. Otherwise, choose a histogram if you have an idea of the range
+     and distribution of values that will be observed. Choose a
+     summary if you need an accurate quantile, no matter what the
+     range and distribution of the values is.
+
+
+## What can I do if my client library does not support the metric type I need?
+
+Implement it! [Code contributions are welcome](/community/). In
+general, we expect histograms to be more urgently needed than
+summaries. Histograms are also easier to implement in a client
+library, so we recommend to implement histograms first, if in
+doubt. The reason why some libraries offer summaries but not
+histograms (Ruby, the legacy Java client) is that histograms are a
+more recent feature of Prometheus.