Include sum value for summary type as per OpenMetrics / Prometheus format

api/src/main/java/org/eclipse/microprofile/metrics/Histogram.java

@@ -28,7 +28,7 @@
  * @see <a href="http://www.johndcook.com/standard_deviation.html">Accurately computing running
  *      variance</a>
  */
-public interface Histogram extends Metric, Sampling, Counting {
+public interface Histogram extends Metric, Sampling, Counting, Summing {
 
     /**
      * Adds a recorded value.
@@ -52,6 +52,9 @@ public interface Histogram extends Metric, Sampling, Counting {
     @Override
     long getCount();
 
+    @Override
+    long getSum();
+
     @Override
     Snapshot getSnapshot();
 }

api/src/main/java/org/eclipse/microprofile/metrics/SimpleTimer.java

@@ -34,7 +34,7 @@
  *
  * The simple timer measures duration in nanoseconds.
  */
-public interface SimpleTimer extends Metric, Counting {
+public interface SimpleTimer extends Metric, Counting, Summing {
     /**
      * A timing context.
      *
@@ -98,6 +98,12 @@ interface Context extends Closeable {
 
     @Override
     long getCount();
+
+    @Override
+    /**
+     * @return returns the cumulative recorded time durations in nanoseconds
+     */
+    long getSum();
 
     /**
      * Get the maximum recorded time duration of the SimpleTimer for the previously completed full minute.

api/src/main/java/org/eclipse/microprofile/metrics/Summing.java

@@ -0,0 +1,38 @@
+/*
+ * ********************************************************************
+ *  Copyright (c) 2020 Contributors to the Eclipse Foundation
+ *
+ *  See the NOTICES file(s) distributed with this work for additional
+ *  information regarding copyright ownership.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  You may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ * ********************************************************************
+ *
+ */
+package org.eclipse.microprofile.metrics;
+
+/**
+ * An interface for metric types which have summable values.
+ */
+public interface Summing {
+
+    /**
+     * Returns the sum of values recorded
+     *
+     * @return the sum of values recorded
+     */
+    long getSum();
+
+}

api/src/main/java/org/eclipse/microprofile/metrics/Timer.java

@@ -36,7 +36,7 @@
  *
  * The timer measures duration in nanoseconds.
  */
-public interface Timer extends Metered, Sampling {
+public interface Timer extends Metered, Sampling, Summing {
     /**
      * A timing context.
      *
@@ -100,6 +100,12 @@ interface Context extends Closeable {
     @Override
     long getCount();
 
+    @Override
+    /**
+     * @return returns the cumulative recorded time durations in nanoseconds
+     */
+    long getSum();
+
     @Override
     double getFifteenMinuteRate();
 

spec/src/main/asciidoc/changelog.adoc

@@ -66,12 +66,18 @@
 *** Added `Timer.getElapsedTime()` which returns `java.time.Duration`
 ** Removed `MetadataBuilder.withOptional*` methods
 ** Global tags and `_app` tag are no longer handled automatically by the `MetricID` class, the implementation is expected to add them by itself, for example during metric export
+** Introduce the `Summable` interface that contains the `getSum()` method which returns long. This interface is extended by the `Timer`, `Histogram` and `SimpleTimer` interfaces. (https://github.com/eclipse/microprofile-metrics/issues/597[#597])
+*** Added the `Histogram.getSum()` 
+*** Added the `Timer.getSum()` which returns the duration in nanoseconds
+*** Added the `SimpleTimer.getSum()` which returns the duration in nanoseconds
 
 === Functional Changes
 ** Simple Timer metrics now track the highest and lowest recorded timing duration of the previous completed minute (https://github.com/eclipse/microprofile-metrics/issues/523[#523])
-** Timer now exposes total elapsed time duration as a metric value (https://github.com/eclipse/microprofile-metrics/issues/524[#524])
+** Timer now exposes total elapsed time duration as a metric value. (https://github.com/eclipse/microprofile-metrics/issues/524[#524])
+*** As of RC3 this value is exposed as a `sum` value in JSON format and is exposed as the `<metric_name>_<units>_sum`under the `summary` type in OpenMetrics format (https://github.com/eclipse/microprofile-metrics/issues/597[#597])
 ** Clarified that the existing REST metric `REST.request` will not monitor and track a REST request to a REST endpoint if an unmapped exception occurs.
 ** Introduced a new base REST metric `REST.request.unmappedException.total` that counts the occurrences of unmapped exceptions for each REST endpoint (https://github.com/eclipse/microprofile-metrics/issues/533[#533])
+** Histogram and Timer now exposes the total sum of recorded values as a `sum` value (https://github.com/eclipse/microprofile-metrics/issues/597[#597])
 
 === Specification Changes
 ** Removed the concept of reusability
@@ -81,6 +87,7 @@
 but the type is implied by the name of the registration method that is being called.
 ** Clarified that the existing REST metric `REST.request` will not monitor and track a REST request to a REST endpoint if an unmapped exception occurs
 ** Introduced a new base REST metric `REST.request.unmappedException.total` that counts the occurrences of unmapped exceptions for each REST endpoint (https://github.com/eclipse/microprofile-metrics/issues/533[#533])
+** Histogram and Timer now exposes the total sum of recorded values as a `sum` value (https://github.com/eclipse/microprofile-metrics/issues/597[#597])
 
 === TCK enhancement
 ** Improved TCK - Use newly introduced `MetricRegistry` methods to retrieve single metrics and avoid use of the `getMetrics()` and `getMetadata()` methods

spec/src/main/asciidoc/rest-endpoints.adoc

@@ -234,6 +234,7 @@ The JSON node is named `<metric-name>`. The JSON leafs are named `<key>[';'<tag-
 | JSON Key | Value (Equivalent Histogram method)
 
 | `count` | `getCount()`
+| `sum` | `getSum()`
 | `min` | `getSnapshot().getMin()`
 | `max` | `getSnapshot().getMax()`
 | `mean` | `getSnapshot().getMean()`
@@ -252,6 +253,7 @@ The JSON node is named `<metric-name>`. The JSON leafs are named `<key>[';'<tag-
 {
   "daily_value_changes": {
     "count": 2,
+    "sum": -1598,
     "min": -1624,
     "max": 26,
     "mean": -799.0,
@@ -263,6 +265,7 @@ The JSON node is named `<metric-name>`. The JSON leafs are named `<key>[';'<tag-
     "p99": 26.0,
     "p999": 26.0,
     "count;servlet=two": 2,
+    "sum;servlet=two": -1598,
     "min;servlet=two": -1624,
     "max;servlet=two": 26,
     "mean;servlet=two": -799.0,
@@ -289,7 +292,7 @@ The JSON node is named `<metric-name>`. The JSON leafs are named `<key>[';'<tag-
 | JSON Key | Value (Equivalent Timer method)
 
 | `count` | `getCount()`
-| `elapsedTime` | `getElapsedTime()`
+| `sum` | `getSum()`
 | `meanRate` | `getMeanRate()`
 | `oneMinRate` | `getOneMinuteRate()`
 | `fiveMinRate` | `getFiveMinuteRate()`
@@ -312,7 +315,7 @@ The JSON node is named `<metric-name>`. The JSON leafs are named `<key>[';'<tag-
 {
   "responseTime": {
     "count": 29382,
-    "elapsedTime": 25608694,
+    "sum": 25608694,
     "meanRate": 12.185627192860734,
     "oneMinRate": 12.563,
     "fiveMinRate": 12.364,
@@ -328,7 +331,7 @@ The JSON node is named `<metric-name>`. The JSON leafs are named `<key>[';'<tag-
     "p99": 5608694.0,
     "p999": 5608694.0,
     "count;servlet=two": 29382,
-    "elapsedTime;servlet=two": 25608694,
+    "sum;servlet=two": 25608694,
     "meanRate;servlet=two":12.185627192860734,
     "oneMinRate;servlet=two": 12.563,
     "fiveMinRate;servlet=two": 12.364,
@@ -667,6 +670,7 @@ The `quantile` OpenMetrics label is merged with the metric's tags.
 | `mean_<units>`                  | Gauge   | `getSnapshot().getMean()`           | <units>^1^
 | `stddev_<units>`                | Gauge   | `getSnapshot().getStdDev()`         | <units>^1^
 | `<units>_count`^2^              | Summary | `getCount()`                        | N/A
+| `<units>_sum`^2^                | Summary | `getSum()`                          | <units>^1^
 | `<units>{quantile="0.5"}`^2^    | Summary | `getSnapshot().getMedian()`         | <units>^1^
 | `<units>{quantile="0.75"}`^2^   | Summary | `getSnapshot().get75thPercentile()` | <units>^1^
 | `<units>{quantile="0.95"}`^2^   | Summary | `getSnapshot().get95thPercentile()` | <units>^1^
@@ -677,7 +681,7 @@ The `quantile` OpenMetrics label is merged with the metric's tags.
 
 ^1^ The implementation is expected to convert the result returned by the `Histogram` into the base unit (if known). The `<unit>` represents the base metric unit and is named according to  <<OpenMetrics_units>>.
 
-^2^ The `summary` type is a complex metric type for OpenMetrics which consists of the count and multiple quantile values.
+^2^ The `summary` type is a complex metric type for OpenMetrics which consists of the count, sum and multiple quantile values.
 
 .Example OpenMetrics text format for a Histogram with unit bytes.
 [source, ruby]
@@ -693,6 +697,7 @@ application_file_sizes_stddev_bytes 1054.7343037063602
 # TYPE application_file_sizes_bytes summary
 # HELP application_file_sizes_bytes Users file size
 application_file_sizes_bytes_count 2037
+application_file_sizes_bytes_sum 48123
 application_file_sizes_bytes{quantile="0.5"} 4201
 application_file_sizes_bytes{quantile="0.75"} 6175
 application_file_sizes_bytes{quantile="0.95"} 13560
@@ -719,12 +724,12 @@ The `quantile` OpenMetrics label is merged with the metric's tags.
 | `one_min_rate_per_second`       | Gauge   | `getOneMinuteRate()`                | PER_SECOND
 | `five_min_rate_per_second`      | Gauge   | `getFiveMinuteRate()`               | PER_SECOND
 | `fifteen_min_rate_per_second`   | Gauge   | `getFifteenMinuteRate()`            | PER_SECOND
-| `elapsedTime_seconds`           | Gauge   | `getElapsedTime()`                  | SECONDS^1^
 | `min_seconds`                   | Gauge   | `getSnapshot().getMin()`            | SECONDS^1^
 | `max_seconds`                   | Gauge   | `getSnapshot().getMax()`            | SECONDS^1^
 | `mean_seconds`                  | Gauge   | `getSnapshot().getMean()`           | SECONDS^1^
 | `stddev_seconds`                | Gauge   | `getSnapshot().getStdDev()`         | SECONDS^1^
 | `seconds_count`^2^              | Summary | `getCount()`                        | N/A
+| `seconds_sum`^2^                | Summary | `getSum()`                          | SECONDS^1^
 | `seconds{quantile="0.5"}`^2^    | Summary | `getSnapshot().getMedian()`         | SECONDS^1^
 | `seconds{quantile="0.75"}`^2^   | Summary | `getSnapshot().get75thPercentile()` | SECONDS^1^
 | `seconds{quantile="0.95"}`^2^   | Summary | `getSnapshot().get95thPercentile()` | SECONDS^1^
@@ -748,8 +753,6 @@ application_response_time_one_min_rate_per_second  2.794076465421066E-14
 application_response_time_five_min_rate_per_second  4.800392614619373E-4
 # TYPE application_response_time_fifteen_min_rate_per_second  gauge
 application_response_time_fifteen_min_rate_per_second  0.01063191047532505
-# TYPE application_response_time_elapsedTime_seconds gauge
-application_response_time_elapsedTime_seconds  0.023
 # TYPE application_response_time_mean_seconds gauge
 application_response_time_mean_seconds 0.000415041
 # TYPE application_response_time_max_seconds gauge
@@ -761,6 +764,7 @@ application_response_time_stddev_seconds 0.000652907
 # TYPE application_response_time_seconds summary
 # HELP application_response_time_seconds Server response time for /index.html
 application_response_time_seconds_count 80
+application_response_time_seconds_sum  0.023
 application_response_time_seconds{quantile="0.5"} 0.0002933240
 application_response_time_seconds{quantile="0.75"} 0.000344914
 application_response_time_seconds{quantile="0.95"} 0.000543647

tck/api/src/main/java/org/eclipse/microprofile/metrics/tck/metrics/HistogramFieldBeanTest.java

@@ -87,6 +87,7 @@ public void updateHistogramField() {
         long value = Math.round(Math.random() * Long.MAX_VALUE);
         bean.update(value);
         assertThat("Histogram count is incorrect", histogram.getCount(), is(equalTo(1L)));
+        assertThat("Histogram sum is incorrect", histogram.getSum(), is(equalTo(value)));
         assertThat("Histogram size is incorrect", histogram.getSnapshot().size(), is(equalTo(1)));
         assertThat("Histogram min value is incorrect", histogram.getSnapshot().getMin(), is(equalTo(value)));
         assertThat("Histogram max value is incorrect", histogram.getSnapshot().getMax(), is(equalTo(value)));

tck/api/src/main/java/org/eclipse/microprofile/metrics/tck/metrics/HistogramTest.java

@@ -123,6 +123,12 @@ public void testCount() throws Exception {
         Assert.assertEquals(200, histogramLong.getCount());
     }
 
+    @Test
+    public void testSum() throws Exception {
+        Assert.assertEquals(10127, histogramInt.getSum());
+        Assert.assertEquals(101270, histogramLong.getSum());
+    }
+
     @Test
     public void testSnapshotValues() throws Exception {
         Assert.assertArrayEquals(

tck/api/src/main/java/org/eclipse/microprofile/metrics/tck/metrics/SimplyTimedMethodBeanLookupTest.java

@@ -27,6 +27,7 @@
 import static org.hamcrest.Matchers.instanceOf;
 import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.notNullValue;
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertThat;
 import static org.junit.Assert.fail;
 
@@ -117,6 +118,8 @@ public void callSimplyTimedMethodOnce() throws InterruptedException {
         // Make sure that the simpleTimer has been called
         assertThat("SimplyTimed count is incorrect", simpleTimer.getCount(), is(equalTo(SIMPLE_TIMER_COUNT.incrementAndGet())));
         TestUtils.assertEqualsWithTolerance(2000000000L,  simpleTimer.getElapsedTime().toNanos());
+        assertEquals("The SimpleTimer's sum and elapsedTime values are supposed to be the same value", simpleTimer.getSum(),
+                simpleTimer.getElapsedTime().toNanos());
     }
 
     @Test

tck/api/src/main/java/org/eclipse/microprofile/metrics/tck/metrics/SimplyTimedMethodBeanTest.java

@@ -27,6 +27,7 @@
 import static org.hamcrest.Matchers.instanceOf;
 import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.notNullValue;
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertThat;
 import static org.junit.Assert.fail;
 
@@ -111,6 +112,8 @@ public void callSimplyTimedMethodOnce() throws InterruptedException {
         // Make sure that the simpleTimer has been called
         assertThat("SimpleTimer count is incorrect", simpleTimer.getCount(), is(equalTo(SIMPLE_TIMER_COUNT.incrementAndGet())));
         TestUtils.assertEqualsWithTolerance(2000000000L,  simpleTimer.getElapsedTime().toNanos());
+        assertEquals("The SimpleTimer's sum and elapsedTime values are supposed to be the same value", simpleTimer.getSum(),
+                simpleTimer.getElapsedTime().toNanos());
     }
 
     @Test

tck/api/src/main/java/org/eclipse/microprofile/metrics/tck/metrics/TimedMethodBeanLookupTest.java

@@ -19,6 +19,7 @@
 import static org.hamcrest.Matchers.instanceOf;
 import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.notNullValue;
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertThat;
 import static org.junit.Assert.fail;
 
@@ -109,6 +110,7 @@ public void callTimedMethodOnce() throws InterruptedException {
         // Make sure that the timer has been called
         assertThat("Timer count is incorrect", timer.getCount(), is(equalTo(TIMER_COUNT.incrementAndGet())));
         TestUtils.assertEqualsWithTolerance(2000000000L,  timer.getElapsedTime().toNanos());
+        assertEquals("The Timer's sum and elapsedTime values are supposed to be the same value", timer.getSum(), timer.getElapsedTime().toNanos());
     }
 
     @Test

tck/api/src/main/java/org/eclipse/microprofile/metrics/tck/metrics/TimedMethodBeanTest.java

@@ -19,6 +19,7 @@
 import static org.hamcrest.Matchers.instanceOf;
 import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.notNullValue;
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertThat;
 import static org.junit.Assert.fail;
 
@@ -102,6 +103,7 @@ public void callTimedMethodOnce() throws InterruptedException {
         // Make sure that the timer has been called
         assertThat("Timer count is incorrect", timer.getCount(), is(equalTo(TIMER_COUNT.incrementAndGet())));
         TestUtils.assertEqualsWithTolerance(2000000000L,  timer.getElapsedTime().toNanos());
+        assertEquals("The Timer's sum and elapsedTime values are supposed to be the same value", timer.getSum(), timer.getElapsedTime().toNanos());
     }
 
     @Test