Skip to content

Commit 4d91df6

Browse files
committed
fix(consistency): attempt to implement new multi exemplars wow
Signed-off-by: György Krajcsovits <gyorgy.krajcsovits@grafana.com>
1 parent 90d8345 commit 4d91df6

File tree

1 file changed

+18
-13
lines changed

1 file changed

+18
-13
lines changed

docs/specs/om/open_metrics_spec_2_0.md

Lines changed: 18 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,10 @@ If the Histogram Metric has MetricPoints with Classic Buckets, the Histogram's M
283283

284284
The Histogram type is cumulative over time, but MAY be reset. When a Histogram is reset, the Sum, Count, Classic Buckets and Native Buckets MUST be reset to their zero state, and if the Start Timestamp is present then it MUST be set to the approximate reset time. Histogram resets can be useful for limiting the number of Native Buckets used by Histograms.
285285

286+
A Histogram MetricPoint MAY have exemplars. The values of exemplars in a Histogram MetricPoint
287+
SHOULD be evenly distributed, such as by keeping one exemplar for each Classic Bucket if Classic
288+
Buckets are included.
289+
286290
##### Classic Buckets
287291

288292
Every Classic Bucket MUST have a threshold. Classic Bucket thresholds within a MetricPoint MUST be unique. Classic Bucket thresholds MAY be negative.
@@ -297,8 +301,6 @@ Exposed Classic Bucket thresholds SHOULD stay constant over time and between tar
297301

298302
If the NaN value is allowed, it MUST be counted in the +Inf bucket, and MUST NOT be counted in any other bucket. The rationale is that NaN does not belong to any bucket mathematically, however instrumentation libraries traditionally put it into the +Inf bucket.
299303

300-
A Histogram MetricPoint MAY have exemplars. The values of exemplars in a Histogram MetricPoint SHOULD be evenly distributed, such as by keeping one exemplar for each Classic Bucket.
301-
302304
##### Native Buckets
303305

304306
Histogram MetricPoints with Native Buckets MUST have a Schema value. The Schema MUST be an 8 bit signed integer between -4 and 8 (inclusive), these are called Standard (exponential) schemas.
@@ -342,10 +344,6 @@ If the NaN value is not allowed, then the Count value MUST be equal to the sum o
342344

343345
If the NaN value is allowed, it MUST NOT be counted in any Native Bucket, and MUST be counted towards the Count. The difference between the Count and the sum of the negative, positive and zero Native Buckets MUST BE the number of NaN observations. The rationale is that NaN does not belong to any bucket mathematically.
344346

345-
A Histogram MetricPoint with Native Buckets MAY contain exemplars.
346-
347-
The values of exemplars in a Histogram MetricPoint with Native Buckets SHOULD be evenly distributed to avoid only representing the bucket with the highest value and therefore most common case.
348-
349347
#### GaugeHistogram
350348

351349
GaugeHistograms measure current distributions. Common examples are how long items have been waiting in a queue, or size of the requests in a queue.
@@ -1055,29 +1053,36 @@ The order ensures that implementations can easily skip the Classic Buckets if th
10551053
acme_http_request_seconds{path="/api/v1",method="GET"} {count:2,sum:1.2e2,schema:0,zero_threshold:1e-4,zero_count:0,positive_spans:[1:2],positive_buckets:[1,1],bucket:[0.5:1,1:2,+Inf:2]}
10561054
```
10571055

1058-
###### Exemplars
1056+
###### Exemplars and Start Timestamp
1057+
1058+
Exemplars MAY be attached to the Histogram MetricPoint.
1059+
1060+
When present, all Exemplars of the Histogram MetricPoint SHOULD be attached.
1061+
In practice this means that if the exposer is keeping a separate set of exemplars for Classic and Native Buckets, then
1062+
the exposer MAY attach only one set for performance and backwards compatibility reasons and that set SHOULD be the
1063+
exemplars associated with Classic Buckets.
1064+
1065+
If present, the MetricPoint's Start Timestamp MUST be inlined with the Metric point with a `st@` prefix. If the value's timestamp is present, the Start Timestamp MUST be added right after it. If exemplars are present, the Start Timestamp MUST be added before it.
10591066

10601067
Exemplars without Labels MUST represent an empty LabelSet as {}.
10611068

1062-
In case of a Histogram with both Classic and Native Buckets, only the exemplars belonging to the Classic Buckets MUST be
1063-
included, the exemplars related to the Native Buckets MUST be excluded.
1069+
Exemplars of a MetricPoint SHOULD have the same Label names to have a consistent style.
10641070

1065-
An example of a Histogram with Native Buckets that has multiple Exemplars:
1071+
An example of a Histogram with Native Buckets and Start Timestamp that has multiple Exemplars:
10661072

10671073
```openmetrics-add-eof
10681074
# TYPE foo histogram
10691075
foo {count:17,sum:324789.3,schema:0,zero_threshold:1e-4,zero_count:0,positive_spans:[0:2],positive_buckets:[5,12]} st@1520430000.123 # {trace_id="shaZ8oxi"} 0.67 1520879607.789 # {trace_id="ookahn0M"} 1.2 1520879608.589
10701076
```
10711077

1072-
An example of a Histogram with Classic Buckets where the "0.01" bucket has no Exemplar. The 0.1 bucket has an Exemplar with no Labels. The 1 bucket has an Exemplar with one Label. The 10 bucket has an Exemplar with a Label and a timestamp. In practice all buckets SHOULD have the same style of Exemplars.
1078+
An example of a Histogram with Classic Buckets and Start Timestamp where no exemplar falls within the "0.01" bucket and the "+Inf" bucket. An exemplar without Labels falls within the "0.1" bucket. An exemplar with one Label falls within the "1" bucket and another in the "10" bucket.
10731079

10741080
```openmetrics-add-eof
10751081
# TYPE foo histogram
10761082
foo {count:17,sum:324789.3,bucket:[0.01:0,0.1:8,1.0:11,10.0:17,+Inf:17]} st@1520430000.123 # {} 0.054 1520879607.7 # {trace_id="KOO5S4vxi0o"} 1.67 1520879602.890 # {trace_id="oHg5SJYRHA0"} 9.8 1520879607.789
10771083
```
10781084

1079-
An example of a Histogram with both Classic and Native Buckets, where the exemplars of only the Classic Buckets are
1080-
included:
1085+
An example of a Histogram with both Classic and Native Buckets and Start Timestamp.
10811086

10821087
```openmetrics-add-eof
10831088
# TYPE foo histogram

0 commit comments

Comments
 (0)