feat(om2): clarify Timestamp and Start Timestamp semantics (#2929)

* feat(om2): clarify Timestamp and Start Timestamp semantics

- 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 <gyorgy.krajcsovits@grafana.com>
Coded with Claude Sonnet 4.6.

* feat(om2): strengthen Start Timestamp normative language

- "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 <gyorgy.krajcsovits@grafana.com>
Coded with Claude Sonnet 4.6.

* fix(om2): remove redundant wording from Summary Start Timestamp

Align with Counter and Histogram sections by using "SHOULD have a
Start Timestamp" consistently.

Signed-off-by: György Krajcsovits <gyorgy.krajcsovits@grafana.com>
Coded with Claude Sonnet 4.6.

* Apply suggestion from @dashpole

Co-authored-by: David Ashpole <dashpole@google.com>
Signed-off-by: George Krajcsovits <krajorama@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Bartlomiej Plotka <bwplotka@gmail.com>
Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>

---------

Signed-off-by: György Krajcsovits <gyorgy.krajcsovits@grafana.com>
Signed-off-by: George Krajcsovits <krajorama@users.noreply.github.com>
Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>
Co-authored-by: David Ashpole <dashpole@google.com>
Co-authored-by: Bartlomiej Plotka <bwplotka@gmail.com>

Author: 3 people

docs/specs/om/open_metrics_spec_2_0.md

@@ -152,6 +152,12 @@ 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 few places in this standard that use Timestamps:
+
+* Exemplar's Timestamp
+* Sample's Timestamp
+* Sample's Start Timestamp
+
 #### Strings
 
 Strings MUST only consist of valid UTF-8 characters and MAY be zero length. NULL (ASCII 0x0) MUST be supported.
@@ -186,9 +192,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. See [Exposing Timestamps](#exposing-timestamps) for why this is not recommended. 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 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
 
@@ -262,9 +270,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.
 
@@ -314,7 +322,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.
 
@@ -416,7 +424,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.