diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md index 3124790b7..46007434a 100644 --- a/docs/specs/om/open_metrics_spec_2_0.md +++ b/docs/specs/om/open_metrics_spec_2_0.md @@ -215,6 +215,8 @@ A gauge MAY be used to encode an enum where the enum has many states and changes Counters measure discrete events. Common examples are the number of HTTP requests received, CPU seconds spent, or bytes sent. For counters how quickly they are increasing over time is what is of interest to a user. +The MetricFamily name for Counters SHOULD end in `_total`. Be aware that exposing metrics without `_total` being a suffix of the MetricFamily name directly to end-users may reduce the usability due to confusion about what the metric's type is. + A MetricPoint in a Metric with the type Counter MUST have one value called Total. A Total is a non-NaN and MUST be monotonically non-decreasing over time, starting from 0. A MetricPoint in a Metric with the type Counter SHOULD have a Timestamp value called Start Timestamp. This can help ingestors discern between new metrics and long-running ones it did not see before. @@ -859,35 +861,33 @@ foo 18.0 456 ##### Counter -The MetricPoint's Total Value Sample MetricName SHOULD have the suffix `_total`. 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 exemplar is present, the Start Timestamp MUST be added before it. - -Be aware that exposing metrics without `_total` being a suffix of the MetricFamily name directly to end-users may reduce the usability due to confusion about what the metric's type is. +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 exemplar is present, the Start Timestamp MUST be added before it. An example with a Metric with no labels, and a MetricPoint with no timestamp and no Start Timestamp: ```openmetrics-add-eof -# TYPE foo counter +# TYPE foo_total counter foo_total 17.0 ``` An example with a Metric with no labels, and a MetricPoint with a timestamp and no Start Timestamp: ```openmetrics-add-eof -# TYPE foo counter +# TYPE foo_total counter foo_total 17.0 1520879607.789 ``` An example with a Metric with no labels, and a MetricPoint with no timestamp and a Start Timestamp: ```openmetrics-add-eof -# TYPE foo counter +# TYPE foo_total counter foo_total 17.0 st@1520430000.123 ``` An example with a Metric with no labels, and a MetricPoint with a timestamp and a Start Timestamp: ```openmetrics-add-eof -# TYPE foo counter +# TYPE foo_total counter foo_total 17.0 1520879607.789 st@1520430000.123 ``` @@ -898,12 +898,14 @@ An example with a Metric with no labels, and a MetricPoint without the `_total` foo 17.0 1520879607.789 st@1520879607.789 ``` +Be aware that exposing metrics without `_total` being a suffix of the MetricFamily name directly to end-users may reduce the usability due to confusion about what the metric's type is. + Exemplars MAY be attached to the MetricPoint's Total sample. An example with a Metric with no labels, and a MetricPoint with a timestamp and a Start Timestamp and an exemplar: ```openmetrics-add-eof -# TYPE foo counter +# TYPE foo_total counter foo_total 17.0 1520879607.789 st@1520430000.123 # {trace_id="KOO5S4vxi0o"} 0.67 1520879606.1 ```