From 62b4421763e3f98300c42fc145e805d9e076cbd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gy=C3=B6rgy=20Krajcsovits?= Date: Thu, 26 Mar 2026 09:15:34 +0100 Subject: [PATCH 1/5] feat(om2): clarify Timestamp and Start Timestamp semantics MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add paragraph to Timestamps section distinguishing explicit Timestamp from Start Timestamp and clarifying naming conventions - Expand Sample section to explain what Timestamp and Start Timestamp represent, and how Start Timestamp helps detect counter resets - Remove redundant Start Timestamp explanations from Counter and Histogram sections since they are now covered in Sample - Fix "timestamp of the reset" -> "approximate reset time" in Counter Signed-off-by: György Krajcsovits Coded with Claude Sonnet 4.6. --- docs/specs/om/open_metrics_spec_2_0.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md index 8456bdcb3..f90c7e8b0 100644 --- a/docs/specs/om/open_metrics_spec_2_0.md +++ b/docs/specs/om/open_metrics_spec_2_0.md @@ -150,6 +150,8 @@ Other MetricFamily Types MUST use Numbers. Timestamps MUST be Unix Epoch in seconds. Timestamps SHOULD be floating point to represent sub-second precision, for example milliseconds or microseconds. Negative timestamps MAY be used. +There are two kinds of Timestamps: explicit Timestamp and Start Timestamp, both described in the [Sample](#sample) section. In this standard, explicit Timestamp is simply called Timestamp, while Start Timestamp is always fully written out. + #### Strings Strings MUST only consist of valid UTF-8 characters and MAY be zero length. NULL (ASCII 0x0) MUST be supported. @@ -184,9 +186,11 @@ Ingestors MAY truncate the Exemplar's LabelSet or discard Exemplars. When trunca #### Sample -A Sample is a single data point within a Metric. It MUST have a Value, MAY have a Timestamp. It MAY include Exemplars and MAY have a start timestamp, depending on the MetricFamily Type. +A Sample is a single data point within a Metric. It MUST have a Value, MAY have a Timestamp. It MAY include Exemplars and MAY have a Start Timestamp, depending on the MetricFamily Type. + +Samples SHOULD NOT have Timestamps. If present, a Sample's Timestamp specifies when the value was observed. -Samples SHOULD NOT have explicit timestamps. +If present, a Sample's Start Timestamp specifies when the measurement period started. This can help ingestors discern between new metrics and long-running ones it did not see before and detect counter resets even when the counter value has not decreased between ingestions. #### Metric @@ -260,9 +264,9 @@ Counters measure discrete events. Common examples are the number of HTTP request The MetricFamily name for Counters SHOULD end in `_total`. Exposing metrics without a `_total` suffix may reduce the usability due to confusion about what the metric's Type is. -A Sample 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. +A Sample in a Metric with the Type Counter SHOULD have a Start Timestamp. -A Sample in a Metric with the Type Counter MUST have a Number value which is non-NaN. The value MUST be monotonically non-decreasing over time, unless it is reset to 0, and start from 0. The value MAY reset its value to 0. If present, the corresponding Start Timestamp MUST also be set to the timestamp of the reset. +A Sample in a Metric with the Type Counter MUST have a Number value which is non-NaN. The value MUST be monotonically non-decreasing over time, unless it is reset to 0, and start from 0. The value MAY reset its value to 0. If present, the corresponding Start Timestamp MUST also be set to the approximate reset time. A Sample in a Metric with the type Counter MAY have exemplars. @@ -312,7 +316,7 @@ A Histogram SHOULD NOT include NaN measurements as including NaN in the Sum will If a Histogram includes +Inf or -Inf measurement, then +Inf or -Inf MUST be counted in Count and MUST be added to the Sum, potentially resulting in +Inf, -Inf or NaN in the Sum, the latter for example in case of adding +Inf to -Inf. Note that in this case the Sum of finite measurements is masked until the next reset of the Histogram. -A Histogram Sample SHOULD have a Start Timestamp. This can help ingestors discern between new metrics and long-running ones it did not see before. +A Histogram Sample SHOULD have a Start Timestamp. If the Histogram Metric has Samples with Classic Buckets, the Histogram's Metric's LabelSet MUST NOT have a "le" label name, because in case the Samples are stored as classic histogram series with the `_bucket` suffix, then the "le" label in the Histogram will conflict with the "le" label generated from the bucket thresholds. From 382682579382ffaf3acaae47f5a47df4e2446f9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gy=C3=B6rgy=20Krajcsovits?= Date: Thu, 26 Mar 2026 09:21:00 +0100 Subject: [PATCH 2/5] feat(om2): strengthen Start Timestamp normative language MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - "specifies" -> "SHOULD specify" to allow edge cases where exact measurement start is not known - "is equivalent to" -> "MUST be treated as equivalent to" to make zero Start Timestamp handling a normative requirement on ingestors Signed-off-by: György Krajcsovits Coded with Claude Sonnet 4.6. --- docs/specs/om/open_metrics_spec_2_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md index f90c7e8b0..6f2ce32d4 100644 --- a/docs/specs/om/open_metrics_spec_2_0.md +++ b/docs/specs/om/open_metrics_spec_2_0.md @@ -190,7 +190,7 @@ A Sample is a single data point within a Metric. It MUST have a Value, MAY have Samples SHOULD NOT have Timestamps. If present, a Sample's Timestamp specifies when the value was observed. -If present, a Sample's Start Timestamp specifies when the measurement period started. This can help ingestors discern between new metrics and long-running ones it did not see before and detect counter resets even when the counter value has not decreased between ingestions. +If present, a Sample's Start Timestamp SHOULD specify when the measurement period started. This can help ingestors discern between new metrics and long-running ones it did not see before and detect counter resets even when the counter value has not decreased between ingestions. A zero Start Timestamp MUST be treated as equivalent to the Start Timestamp not being present. #### Metric From 68f4429912b5bc79328d790ff5a2ecfd2c97f2c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gy=C3=B6rgy=20Krajcsovits?= Date: Thu, 26 Mar 2026 10:18:33 +0100 Subject: [PATCH 3/5] fix(om2): remove redundant wording from Summary Start Timestamp MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align with Counter and Histogram sections by using "SHOULD have a Start Timestamp" consistently. Signed-off-by: György Krajcsovits Coded with Claude Sonnet 4.6. --- docs/specs/om/open_metrics_spec_2_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md index 6f2ce32d4..5a1e31045 100644 --- a/docs/specs/om/open_metrics_spec_2_0.md +++ b/docs/specs/om/open_metrics_spec_2_0.md @@ -418,7 +418,7 @@ A Summary Sample MUST contain a Count, Sum and a set of quantiles. Semantically, Count and Sum values are counters so MUST NOT be NaN or negative. Count MUST be an integer. -A Summary 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. +A Summary SHOULD have a Start Timestamp. Start Timestamp MUST NOT be based on the collection period of quantile values. From 65af2e4985cddd4cd4314e729bdaecc69e8551de Mon Sep 17 00:00:00 2001 From: George Krajcsovits Date: Mon, 30 Mar 2026 08:55:28 +0200 Subject: [PATCH 4/5] Apply suggestion from @dashpole Co-authored-by: David Ashpole Signed-off-by: George Krajcsovits --- docs/specs/om/open_metrics_spec_2_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md index 5a1e31045..623c72fb6 100644 --- a/docs/specs/om/open_metrics_spec_2_0.md +++ b/docs/specs/om/open_metrics_spec_2_0.md @@ -188,7 +188,7 @@ Ingestors MAY truncate the Exemplar's LabelSet or discard Exemplars. When trunca A Sample is a single data point within a Metric. It MUST have a Value, MAY have a Timestamp. It MAY include Exemplars and MAY have a Start Timestamp, depending on the MetricFamily Type. -Samples SHOULD NOT have Timestamps. If present, a Sample's Timestamp specifies when the value was observed. +Samples SHOULD NOT have Timestamps. See [Exposing Timestamps](#exposing-timestamps) for why this is not recommended. If present, a Sample's Timestamp specifies when the value was observed. If present, a Sample's Start Timestamp SHOULD specify when the measurement period started. This can help ingestors discern between new metrics and long-running ones it did not see before and detect counter resets even when the counter value has not decreased between ingestions. A zero Start Timestamp MUST be treated as equivalent to the Start Timestamp not being present. From cb59a5de6ca8528454095da50b83b3f6d1df337d Mon Sep 17 00:00:00 2001 From: Bartlomiej Plotka Date: Mon, 30 Mar 2026 14:26:24 +0100 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Bartlomiej Plotka Signed-off-by: Bartlomiej Plotka --- docs/specs/om/open_metrics_spec_2_0.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md index 623c72fb6..e2cdef3cc 100644 --- a/docs/specs/om/open_metrics_spec_2_0.md +++ b/docs/specs/om/open_metrics_spec_2_0.md @@ -150,7 +150,11 @@ Other MetricFamily Types MUST use Numbers. Timestamps MUST be Unix Epoch in seconds. Timestamps SHOULD be floating point to represent sub-second precision, for example milliseconds or microseconds. Negative timestamps MAY be used. -There are two kinds of Timestamps: explicit Timestamp and Start Timestamp, both described in the [Sample](#sample) section. In this standard, explicit Timestamp is simply called Timestamp, while Start Timestamp is always fully written out. +There are few places in this standard that use Timestamps: + +* Exemplar's Timestamp +* Sample's Timestamp +* Sample's Start Timestamp #### Strings @@ -190,7 +194,7 @@ A Sample is a single data point within a Metric. It MUST have a Value, MAY have Samples SHOULD NOT have Timestamps. See [Exposing Timestamps](#exposing-timestamps) for why this is not recommended. If present, a Sample's Timestamp specifies when the value was observed. -If present, a Sample's Start Timestamp SHOULD specify when the measurement period started. This can help ingestors discern between new metrics and long-running ones it did not see before and detect counter resets even when the counter value has not decreased between ingestions. A zero Start Timestamp MUST be treated as equivalent to the Start Timestamp not being present. +If present, a Sample's Start Timestamp SHOULD specify when the measurement period started. This can help ingestors discern between new metrics and long-running ones it did not see before and detect counter resets even when the counter value has not decreased between ingestions. #### Metric