Classic histogram and summary as complex types

Ref: prometheus/OpenMetrics#283

Signed-off-by: György Krajcsovits <[email protected]>

Author: krajorama

docs/specs/om/open_metrics_spec_2_0.md

@@ -62,7 +62,15 @@ This section MUST be read together with the ABNF section. In case of disagreemen
 
 #### Values
 
-Metric values in OpenMetrics MUST be either floating points or integers. Note that ingestors of the format MAY only support float64. The non-real values NaN, +Inf and -Inf MUST be supported. NaN MUST NOT be considered a missing value, but it MAY be used to signal a division by zero.
+Metric values in OpenMetrics MUST be either numbers or complex data types.
+
+Numbers MUST be either floating points or integers. Note that ingestors of the format MAY only support float64. The non-real values NaN, +Inf and -Inf MUST be supported. NaN MUST NOT be considered a missing value, but it MAY be used to signal a division by zero.
+
+Complex data types MUST contain all information necessary to recreate a sample of a Metric Type, with the exception of Created Value and Exemplars.
+
+List of complex data types:
+ - Integer counter classic histogram for the Metric Type Histogram.
+ - Classic summary for the Metric Type Summary.
 
 ##### Booleans
 
@@ -322,8 +330,11 @@ metric-type = counter / gauge / histogram / gaugehistogram / stateset
 metric-type =/ info / summary / unknown
 
 sample = metricname [labels] SP number [SP timestamp] [exemplar] LF
+sample =/ metricname [labels] SP "{" complextype "}" [SP timestamp] *exemplar-ts LF
 
-exemplar = SP HASH SP labels SP number [SP timestamp]
+exemplar = exemplar-base [SP timestamp]
+exemplar-ts = exemplar-base SP timestamp
+exemplar-base = SP HASH SP labels SP number
 
 labels = "{" [label *(COMMA label)] "}"
 
@@ -383,6 +394,35 @@ escaped-char =/ BS normal-char
 
 ; Any unicode character, except newline, double quote, and backslash
 normal-char = %x00-09 / %x0B-21 / %x23-5B / %x5D-D7FF / %xE000-10FFFF
+
+; Complex types
+complextype = classic-histogram / classic-summary
+
+; count:12.0,sum:100.0,bucket:[0.1:3.0,05:12.0,+Inf:12.0]
+classic-histogram = ch-count "," ch-sum "," ch-bucket
+
+; count:x where x is a real number, not +-Inf or NaN
+ch-count = %d99.111.117.110.116 ":" realnumber
+; sum:x where x is a real number or +-Inf or NaN
+ch-sum = %d115.117.109 ":" number
+; bucket:[...]
+ch-bucket = %d98.117.99.107.101.116 ":" "[" ch-le-counts "]"
+ch-le-counts = ch-pos-inf-bucket / (ch-neg-inf-bucket / ch-bucket) *("," ch-bucket) "," ch-pos-inf-bucket
+ch-pos-inf-bucket = "+" %d73.110.102 ":" realnumber
+ch-neg-inf-bucket = "-" %d73.110.102 ":" realnumber
+ch-bucket = realnumber ":" realnumber
+
+; count:12.0,sum:100.0,quantile:[0.9:2.0,0.95:3.0,0.99:20.0]
+classic-summary = cs-count "," cs-sum "," cs-quantile
+
+; count:x where x is a real number, not +-Inf or NaN
+cs-count = %d99.111.117.110.116 ":" realnumber
+; sum:x where x is a real number or +-Inf or NaN
+cs-sum = %d115.117.109 ":" number
+; quantile:[...]
+cs-quantile = %d113.117.97.110.116.105.108.101 ":" "[" cs-q-counts "]"
+cs-q-counts = *cs-q-count
+cs-q-count = realnumber ":" realnumber
 ```
 
 #### Overall Structure
@@ -400,15 +440,16 @@ Line endings MUST be signalled with line feed (\n) and MUST NOT contain carriage
 An example of a complete exposition:
 
 ```openmetrics
+# TYPE acme_http_server_request_seconds histogram
+# UNIT acme_http_server_request_seconds seconds
+# HELP acme_http_server_request_seconds Latency though all of ACME's HTTP request service.
+acme_http_router_request_seconds{path="/api/v1",method="GET"} {count:10.0,sum:100.0,bucket:[0.1:2.0,0.5:50.0,+Inf:10.0]}
+acme_http_router_request_seconds{path="/api/v2",method="GET"} {count:1.0,sum:10.0,bucket:[0.1:1.0,0.5:1.0,+Inf:1.0]}
 # TYPE acme_http_router_request_seconds summary
 # UNIT acme_http_router_request_seconds seconds
 # HELP acme_http_router_request_seconds Latency though all of ACME's HTTP request router.
-acme_http_router_request_seconds_sum{path="/api/v1",method="GET"} 9036.32
-acme_http_router_request_seconds_count{path="/api/v1",method="GET"} 807283.0
-acme_http_router_request_seconds_created{path="/api/v1",method="GET"} 1605281325.0
-acme_http_router_request_seconds_sum{path="/api/v2",method="POST"} 479.3
-acme_http_router_request_seconds_count{path="/api/v2",method="POST"} 34.0
-acme_http_router_request_seconds_created{path="/api/v2",method="POST"} 1605281325.0
+acme_http_router_request_seconds{path="/api/v1",method="GET"} {count:10.0,sum:100.0,quantile:[0.95:2.0,0.99:20.0]}
+acme_http_router_request_seconds{path="/api/v2",method="GET"} {count:1.0,sum:10.0,quantile:[0.95:2.0,0.99:2.0]}
 # TYPE go_goroutines gauge
 # HELP go_goroutines Number of goroutines that currently exist.
 go_goroutines 69