Skip to content

Commit a92a2c0

Browse files
Update created timestamp references to start timestamp in histogram docs (#2956)
Signed-off-by: Carrie Edwards <carrie.edwards@grafana.com>
1 parent 7e9de70 commit a92a2c0

1 file changed

Lines changed: 13 additions & 14 deletions

File tree

docs/specs/native_histograms.md

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -665,7 +665,7 @@ message Histogram {
665665
// Buckets for the classic histogram.
666666
repeated Bucket bucket = 3 [(gogoproto.nullable) = false]; // Ordered in increasing order of upper_bound, +Inf bucket is optional.
667667
668-
google.protobuf.Timestamp created_timestamp = 15;
668+
google.protobuf.Timestamp start_timestamp = 15;
669669
670670
// Everything below here is for native histograms (also known as sparse histograms).
671671
@@ -741,7 +741,7 @@ Note the following:
741741
`Histogram` proto message, i.e. the existing `Histogram` message got extended
742742
with fields for native histograms.
743743
- The fields for the sum and the count of observations and the
744-
`created_timestamp` are shared between classic and native histograms and keep
744+
`start_timestamp` are shared between classic and native histograms and keep
745745
working in the same way for both.
746746
- The format originally did not support classic float histograms. While
747747
extending the format for native histograms, support for classic float
@@ -946,8 +946,8 @@ If step 2 or 3 have changed the histogram, a reset will be performed once
946946
`NativeHistogramMinResetDuration` has passed since the last reset, not only to
947947
remove the buckets but also to return to the initial values for the zero
948948
threshold and the bucket resolution. Note that this is treated like a reset for
949-
other reasons in all aspects, including updating the so-called [created
950-
timestamp](#created-timestamp-handling).
949+
other reasons in all aspects, including updating the [start
950+
timestamp](#start-timestamp-handling).
951951

952952
It is tempting to set a very low `NativeHistogramBucketFactor` (e.g. 1.005)
953953
together with a reasonable `NativeHistogramMaxBucketNumber` (e.g. 160). In this
@@ -1404,7 +1404,7 @@ between chunk size and compression ratio.
14041404

14051405
Generally, Prometheus considers a counter to have reset whenever its value
14061406
drops from one sample to the next (but see also the [next section about the
1407-
created timestamp](#created-timestamp-handling)). The situation is more complex
1407+
start timestamp](#start-timestamp-handling)). The situation is more complex
14081408
when detecting a counter reset between two histogram samples.
14091409

14101410
First of all, gauge histograms and counter histograms are explicitly different
@@ -1594,23 +1594,22 @@ by other means. However, due to the complications caused by insertion and
15941594
removal of chunks, out-of-order samples, and overlapping blocks (as explained
15951595
above), this information MAY get lost if a second round of counter reset
15961596
detection is required. (TODO: Currently, this information is reliably lost, see
1597-
TODO above.) A better way to safely mark a counter reset is via created
1597+
TODO above.) A better way to safely mark a counter reset is via start
15981598
timestamps (see next section).
15991599

1600-
### Created timestamp handling
1600+
### Start timestamp handling
16011601

1602-
OpenMetrics introduced so-called created timestamps for counters, summaries,
1602+
OpenMetrics introduced the so-called created timestamps for counters, summaries,
16031603
and classic counter histograms. (The term is probably short for “created-at
1604-
timstamp”. The more appropriate term might have been “creation timestamp” or
1605-
“reset timestamp”, but the term “created timestamp” is firmly established by
1606-
now.)
1604+
timestamp”. The more appropriate term might have been “creation timestamp” or
1605+
“reset timestamp”.) The term has since been renamed to "start timestamp".
16071606

1608-
The created timestamp provides the most recent time the metric was created or
1607+
The start timestamp provides the most recent time the metric was created or
16091608
reset. A [design
16101609
doc](https://github.com/prometheus/proposals/blob/main/proposals/2023-06-13_created-timestamp.md)
1611-
describes how Prometheus handles created timestamps.
1610+
describes how Prometheus handles start timestamps.
16121611

1613-
Created timestamps are also useful for native histograms. In the same way a
1612+
Start timestamps are also useful for native histograms. In the same way a
16141613
synthetic zero sample is inserted for float counters, a zero value of a
16151614
histogram sample is inserted for counter histograms. A zero value of a
16161615
histogram has no populated buckets, and the sum of observations, the count of

0 commit comments

Comments
 (0)