chore(om2.0): rename created timestamp to start timestamp (#2770)

krajorama · web-flow · commit a04d7ce0f3d9 · 2025-11-11T08:57:06.000+01:00
From dev summit decision on 23rd October 2023.

Signed-off-by: György Krajcsovits &lt;gyorgy.krajcsovits@grafana.com&gt;
diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md
@@ -192,9 +192,9 @@ Counters measure discrete events. Common examples are the number of HTTP request
 
 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 Created Timestamp. This can help ingestors discern between new metrics and long-running ones it did not see before.
+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.
 
-A MetricPoint in a Metric's Counter's Total MAY reset to 0. If present, the corresponding Created Timestamp MUST also be set to the timestamp of the reset.
+A MetricPoint in a Metric's Counter's Total MAY reset to 0. If present, the corresponding Start Timestamp MUST also be set to the timestamp of the reset.
 
 A MetricPoint in a Metric's Counter's Total MAY have an exemplar.
 
@@ -230,7 +230,7 @@ MetricFamilies of type Info MUST have an empty Unit string.
 
 Histograms measure distributions of discrete events. Common examples are the latency of HTTP requests, function runtimes, or I/O request sizes.
 
-A Histogram MetricPoint MUST contain at least one bucket, and SHOULD contain Sum, and Created Timestamp values. Every bucket MUST have a threshold and a value.
+A Histogram MetricPoint MUST contain at least one bucket, and SHOULD contain Sum, and Start Timestamp values. Every bucket MUST have a threshold and a value.
 
 Histogram MetricPoints MUST have one bucket with an +Inf threshold. Buckets MUST be cumulative. As an example for a metric representing request latency in seconds its values for buckets with thresholds 1, 2, 3, and +Inf MUST follow value_1 <= value_2 <= value_3 <= value_+Inf. If ten requests took 1 second each, the values of the 1, 2, 3, and +Inf buckets MUST equal 10.
 
@@ -242,7 +242,7 @@ The Sum is only a counter semantically as long as there are no negative event va
 
 Negative threshold buckets MAY be used. Bucket thresholds MUST NOT equal NaN. Count and bucket values MUST be integers.
 
-A Histogram MetricPoint SHOULD have a Timestamp value called Created Timestamp. This can help ingestors discern between new metrics and long-running ones it did not see before.
+A Histogram MetricPoint 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 Histogram's Metric's LabelSet MUST NOT have a "le" label name.
 
@@ -276,12 +276,12 @@ Summaries also measure distributions of discrete events and MAY be used when His
 
 They MAY also be used for backwards compatibility, because some existing instrumentation libraries expose precomputed quantiles and do not support Histograms. Precomputed quantiles SHOULD NOT be used, because quantiles are not aggregatable and the user often can not deduce what timeframe they cover.
 
-A Summary MetricPoint MAY consist of a Count, Sum, Created Timestamp, and a set of quantiles.
+A Summary MetricPoint MAY consist of a Count, Sum, Start Timestamp, 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 MetricPoint in a Metric with the type Summary which contains Count or Sum values SHOULD have a Timestamp value called Created Timestamp. This can help ingestors discern between new metrics and long-running ones it did not see before. Created Timestamp MUST NOT relate to the collection period of quantile values.
+A MetricPoint in a Metric with the type Summary which contains Count or Sum values 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. Start Timestamp MUST NOT relate to the collection period of quantile values.
 
 Quantiles are a map from a quantile to a value. An example is a quantile 0.95 with value 0.2 in a metric called myapp_http_request_duration_seconds which means that the 95th percentile latency is 200ms over an unknown timeframe. If there are no events in the relevant timeframe, the value for a quantile MUST be NaN.
 A Quantile's Metric's LabelSet MUST NOT have "quantile" label name.
@@ -338,7 +338,7 @@ metric = *sample
 metric-type = counter / gauge / histogram / gaugehistogram / stateset
 metric-type =/ info / summary / unknown
 
-sample = metricname-and-labels SP number [SP timestamp] [SP created] [exemplar] LF
+sample = metricname-and-labels SP number [SP timestamp] [SP start-timestamp] [exemplar] LF
 
 exemplar = SP HASH SP labels-in-braces SP number [SP timestamp]
 
@@ -406,8 +406,8 @@ 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
 
-; Lowercase ct @ timestamp
-created = %d99.116 "@" timestamp
+; Lowercase st @ timestamp
+start-timestamp = %d115.116 "@" timestamp
 ```
 
 #### Overall Structure
@@ -428,10 +428,10 @@ An example of a complete exposition:
 # 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 ct@1605281325.0
-acme_http_router_request_seconds_count{path="/api/v1",method="GET"} 807283.0 ct@1605281325.0
-acme_http_router_request_seconds_sum{path="/api/v2",method="POST"} 479.3 ct@1605301325.0
-acme_http_router_request_seconds_count{path="/api/v2",method="POST"} 34.0 ct@1605301325.0
+acme_http_router_request_seconds_sum{path="/api/v1",method="GET"} 9036.32 st@1605281325.0
+acme_http_router_request_seconds_count{path="/api/v1",method="GET"} 807283.0 st@1605281325.0
+acme_http_router_request_seconds_sum{path="/api/v2",method="POST"} 479.3 st@1605301325.0
+acme_http_router_request_seconds_count{path="/api/v2",method="POST"} 34.0 st@1605301325.0
 # TYPE go_goroutines gauge
 # HELP go_goroutines Number of goroutines that currently exist.
 go_goroutines 69
@@ -660,52 +660,52 @@ foo 18.0 456
 
 ##### Counter
 
-The MetricPoint's Total Value Sample MetricName SHOULD have the suffix `_total`. If present, the MetricPoint's Created Timestamp MUST be inlined with the Metric point with a `ct@` prefix. If the value's timestamp is present, the Created Timestamp MUST be added right after it. If exemplar is present, the Created Timestamp MUST be added before it.
+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.
 
-An example with a Metric with no labels, and a MetricPoint with no timestamp and no Created Timestamp:
+An example with a Metric with no labels, and a MetricPoint with no timestamp and no Start Timestamp:
 
 ```openmetrics-add-eof
 # TYPE foo counter
 foo_total 17.0
 ```
 
-An example with a Metric with no labels, and a MetricPoint with a timestamp and no Created Timestamp:
+An example with a Metric with no labels, and a MetricPoint with a timestamp and no Start Timestamp:
 
 ```openmetrics-add-eof
 # TYPE foo counter
 foo_total 17.0 1520879607.789
 ```
 
-An example with a Metric with no labels, and a MetricPoint with no timestamp and a Created Timestamp:
+An example with a Metric with no labels, and a MetricPoint with no timestamp and a Start Timestamp:
 
 ```openmetrics-add-eof
 # TYPE foo counter
-foo_total 17.0 ct@1520430000.123
+foo_total 17.0 st@1520430000.123
 ```
 
-An example with a Metric with no labels, and a MetricPoint with a timestamp and a Created Timestamp:
+An example with a Metric with no labels, and a MetricPoint with a timestamp and a Start Timestamp:
 
 ```openmetrics-add-eof
 # TYPE foo counter
-foo_total 17.0 1520879607.789 ct@1520430000.123
+foo_total 17.0 1520879607.789 st@1520430000.123
 ```
 
-An example with a Metric with no labels, and a MetricPoint without the `_total` suffix and with a timestamp and a created:
+An example with a Metric with no labels, and a MetricPoint without the `_total` suffix and with a timestamp and a start timestamp:
 
 ```openmetrics-add-eof
 # TYPE foo counter
-foo 17.0 1520879607.789 ct@1520879607.789
+foo 17.0 1520879607.789 st@1520879607.789
 ```
 
 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 Created Timestamp and an exemplar:
+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
-foo_total 17.0 1520879607.789 ct@1520430000.123 # {trace_id="KOO5S4vxi0o"} 0.67
+foo_total 17.0 1520879607.789 st@1520430000.123 # {trace_id="KOO5S4vxi0o"} 0.67
 ```
 
 ##### StateSet
@@ -760,22 +760,22 @@ Metric labels and MetricPoint value labels MAY be in any order.
 
 If present, the MetricPoint's Sum Value Sample MetricName MUST have the suffix `_sum`. If present, the MetricPoint's Count Value MetricName MUST have the suffix `_count`. If present, the MetricPoint's Quantile Values MUST specify the quantile measured using a label with a label name of "quantile" and with a label value of the quantile measured.
 
-If present the MetricPoint's Created Timestamp MUST be inlined with the Metric point with a `ct@` prefix. If the value's timestamp is present, the Created Timestamp MUST be added right after it. If exemplar is present, the Created Timestamp MUST be added before it. Created Timestamp MUST be appended to all Quantile Values, to the MetricPoint's Sum and MetricPoint's Count.
+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. Start Timestamp MUST be appended to all Quantile Values, to the MetricPoint's Sum and MetricPoint's Count.
 
-An example of a Metric with no labels and a MetricPoint with Sum, Count and Created Timestamp values:
+An example of a Metric with no labels and a MetricPoint with Sum, Count and Start Timestamp values:
 
 ```openmetrics-add-eof
 # TYPE foo summary
-foo_count 17.0 ct@1520430000.123
-foo_sum 324789.3 ct@1520430000.123
+foo_count 17.0 st@1520430000.123
+foo_sum 324789.3 st@1520430000.123
 ```
 
-An example of a Metric with no labels and a MetricPoint with two quantiles and Created Timestamp values:
+An example of a Metric with no labels and a MetricPoint with two quantiles and Start Timestamp values:
 
 ```openmetrics-add-eof
 # TYPE foo summary
-foo{quantile="0.95"} 123.7 ct@1520430000.123
-foo{quantile="0.99"} 150.0 ct@1520430000.123
+foo{quantile="0.95"} 123.7 st@1520430000.123
+foo{quantile="0.99"} 150.0 st@1520430000.123
 ```
 
 Quantiles MAY be in any order.
@@ -784,29 +784,29 @@ Quantiles MAY be in any order.
 
 The MetricPoint's Bucket Values Sample MetricNames MUST have the suffix `_bucket`. If present, the MetricPoint's Sum Value Sample MetricName MUST have the suffix `_sum`.
 
-If present the MetricPoint's Created Timestamp MUST be inlined with the Metric point with a `ct@` prefix. If the value's timestamp is present, the Created Timestamp MUST be added right after it. If exemplar  is present, the Created Timestamp MUST be added before it. Created Timestamp MUST be appended to all Bucket Values, to the MetricPoint's Sum and MetricPoint's Count.
+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. Start Timestamp MUST be appended to all Bucket Values, to the MetricPoint's Sum and MetricPoint's Count.
 
 If and only if a Sum Value is present in a MetricPoint, then the MetricPoint's +Inf Bucket value MUST also appear in a Sample with a MetricName with the suffix "_count".
 
 Buckets MUST be sorted in number increasing order of "le", and the value of the "le" label MUST follow the rules for Canonical Numbers.
 
-An example of a Metric with no labels and a MetricPoint with Sum, Count, and Created Timestamp values, and with 12 buckets. A wide and atypical but valid variety of “le” values is shown on purpose:
+An example of a Metric with no labels and a MetricPoint with Sum, Count, and Start Timestamp values, and with 12 buckets. A wide and atypical but valid variety of “le” values is shown on purpose:
 
 ```openmetrics-add-eof
 # TYPE foo histogram
-foo_bucket{le="0.0"} 0 ct@1520430000.123
-foo_bucket{le="1e-05"} 0 ct@1521430000.123
-foo_bucket{le="0.0001"} 5 ct@1521430020.123
-foo_bucket{le="0.1"} 8 ct@1520430321.123
-foo_bucket{le="1.0"} 10 ct@1522430000.123
-foo_bucket{le="10.0"} 11 ct@1520430123.123
-foo_bucket{le="100000.0"} 11 ct@1521430010.123
-foo_bucket{le="1e+06"} 15 ct@1520430301.123
-foo_bucket{le="1e+23"} 16 ct@1521430001.123
-foo_bucket{le="1.1e+23"} 17 ct@1522430220.123
-foo_bucket{le="+Inf"} 17 ct@1520430000.123
-foo_count 17 ct@1520430000.123
-foo_sum 324789.3 ct@1520430000.123
+foo_bucket{le="0.0"} 0 st@1520430000.123
+foo_bucket{le="1e-05"} 0 st@1521430000.123
+foo_bucket{le="0.0001"} 5 st@1521430020.123
+foo_bucket{le="0.1"} 8 st@1520430321.123
+foo_bucket{le="1.0"} 10 st@1522430000.123
+foo_bucket{le="10.0"} 11 st@1520430123.123
+foo_bucket{le="100000.0"} 11 st@1521430010.123
+foo_bucket{le="1e+06"} 15 st@1520430301.123
+foo_bucket{le="1e+23"} 16 st@1521430001.123
+foo_bucket{le="1.1e+23"} 17 st@1522430220.123
+foo_bucket{le="+Inf"} 17 st@1520430000.123
+foo_count 17 st@1520430000.123
+foo_sum 324789.3 st@1520430000.123
 ```
 
 ###### Exemplars
@@ -818,13 +818,13 @@ The "0.01" bucket has no Exemplar. The 0.1 bucket has an Exemplar with no Labels
 
 ```openmetrics-add-eof
 # TYPE foo histogram
-foo_bucket{le="0.01"} 0 ct@1520430000.123
-foo_bucket{le="0.1"} 8 ct@1520430000.123 # {} 0.054
-foo_bucket{le="1"} 11 ct@1520430000.123 # {trace_id="KOO5S4vxi0o"} 0.67
-foo_bucket{le="10"} 17 ct@1520430000.123 # {trace_id="oHg5SJYRHA0"} 9.8 1520879607.789
-foo_bucket{le="+Inf"} 17 ct@1520430000.123
-foo_count 17 ct@1520430000.123
-foo_sum 324789.3 ct@1520430000.123
+foo_bucket{le="0.01"} 0 st@1520430000.123
+foo_bucket{le="0.1"} 8 st@1520430000.123 # {} 0.054
+foo_bucket{le="1"} 11 st@1520430000.123 # {trace_id="KOO5S4vxi0o"} 0.67
+foo_bucket{le="10"} 17 st@1520430000.123 # {trace_id="oHg5SJYRHA0"} 9.8 1520879607.789
+foo_bucket{le="+Inf"} 17 st@1520430000.123
+foo_count 17 st@1520430000.123
+foo_sum 324789.3 st@1520430000.123
 ```
 
 ##### GaugeHistogram
@@ -1165,7 +1165,7 @@ my_time_since_boot_seconds 123
 ```
 
 Conversely, there are no best practice restrictions on exemplars timestamps.
-Keep in mind that due to race conditions or time not being perfectly synced across devices, that an exemplar timestamp may appear to be slightly in the future relative to a ingestor's system clock or other metrics from the same exposition. Similarly it is possible that a "ct@" for a MetricPoint could appear to be slightly after an exemplar or sample timestamp for that same MetricPoint.
+Keep in mind that due to race conditions or time not being perfectly synced across devices, that an exemplar timestamp may appear to be slightly in the future relative to a ingestor's system clock or other metrics from the same exposition. Similarly it is possible that a "st@" for a MetricPoint could appear to be slightly after an exemplar or sample timestamp for that same MetricPoint.
 
 Keep in mind that there are monitoring systems in common use which support everything from nanosecond to second resolution, so having two MetricPoints that have the same timestamp when truncated to second resolution may cause an apparent duplicate in the ingestor. In this case the MetricPoint with the earliest timestamp MUST be used.
 
