Update aggregation operator docs (#6240)

Update the aggregation operator documentation.
* Include before expression style syntax as valid.
* Update examples to show before style.

Signed-off-by: Ben Kochie <superq@gmail.com>

docs/querying/examples.md

@@ -59,7 +59,9 @@ Assuming that the `http_requests_total` time series all have the labels `job`
 want to sum over the rate of all instances, so we get fewer output time series,
 but still preserve the `job` dimension:
 
-    sum(rate(http_requests_total[5m])) by (job)
+    sum by (job) (
+      rate(http_requests_total[5m])
+    )
 
 If we have two different metrics with the same dimensional labels, we can apply
 binary operators to them and elements on both sides with the same label set
@@ -71,9 +73,9 @@ scheduler exposing these metrics about the instances it runs):
 
 The same expression, but summed by application, could be written like this:
 
-    sum(
+    sum by (app, proc) (
       instance_memory_limit_bytes - instance_memory_usage_bytes
-    ) by (app, proc) / 1024 / 1024
+    ) / 1024 / 1024
 
 If the same fictional cluster scheduler exposed CPU usage metrics like the
 following for every instance:
@@ -87,9 +89,9 @@ following for every instance:
 ...we could get the top 3 CPU users grouped by application (`app`) and process
 type (`proc`) like this:
 
-    topk(3, sum(rate(instance_cpu_time_ns[5m])) by (app, proc))
+    topk(3, sum by (app, proc) (rate(instance_cpu_time_ns[5m])))
 
 Assuming this metric contains one time series per running instance, you could
 count the number of running instances per application like this:
 
-    count(instance_cpu_time_ns) by (app)
+    count by (app) (instance_cpu_time_ns)

docs/querying/operators.md

@@ -196,7 +196,12 @@ vector of fewer elements with aggregated values:
 * `quantile` (calculate φ-quantile (0 ≤ φ ≤ 1) over dimensions)
 
 These operators can either be used to aggregate over **all** label dimensions
-or preserve distinct dimensions by including a `without` or `by` clause.
+or preserve distinct dimensions by including a `without` or `by` clause. These
+clauses may be used before or after the expression.
+
+    <aggr-op> [without|by (<label list>)] ([parameter,] <vector expression>)
+
+or
 
     <aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]
 
@@ -221,11 +226,11 @@ If the metric `http_requests_total` had time series that fan out by
 `application`, `instance`, and `group` labels, we could calculate the total
 number of seen HTTP requests per application and group over all instances via:
 
-    sum(http_requests_total) without (instance)
+    sum without (instance) (http_requests_total)
 
 Which is equivalent to:
 
-     sum(http_requests_total) by (application, group)
+     sum by (application, group) (http_requests_total)
 
 If we are just interested in the total of HTTP requests we have seen in **all**
 applications, we could simply write: