Merge pull request #15111 from prometheus/beorn7/doc

docs: Declare "float literals are time durations" as stable

docs/querying/api.md

@@ -59,7 +59,7 @@ timestamps are always represented as Unix timestamps in seconds.
 * `<series_selector>`: Prometheus [time series
 selectors](basics.md#time-series-selectors) like `http_requests_total` or
 `http_requests_total{method=~"(GET|POST)"}` and need to be URL-encoded.
-* `<duration>`: [Prometheus duration strings](basics.md#time-durations).
+* `<duration>`: [the subset of Prometheus float literals using time units](basics.md#float-literals-and-time-durations).
 For example, `5m` refers to a duration of 5 minutes.
 * `<bool>`: boolean values (strings `true` and `false`).
 

docs/querying/basics.md

@@ -68,9 +68,10 @@ Example:
     'these are unescaped: \n \\ \t'
     `these are not unescaped: \n ' " \t`
 
-### Float literals
+### Float literals and time durations
 
-Scalar float values can be written as literal integer or floating-point numbers in the format (whitespace only included for better readability):
+Scalar float values can be written as literal integer or floating-point numbers
+in the format (whitespace only included for better readability):
 
     [-+]?(
           [0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?
@@ -88,15 +89,52 @@ Examples:
     -Inf
     NaN
 
-
+Additionally, underscores (`_`) can be used in between decimal or hexadecimal
-As of version 2.54, float literals can also be represented using the syntax of time durations, where the time duration is converted into a float value corresponding to the number of seconds the time duration represents. This is an experimental feature and might still change.
+digits to improve readability.
 
 Examples:
 
-    1s # Equivalent to 1.0
+    1_000_000
-    2m # Equivalent to 120.0
+    .123_456_789
-    1ms # Equivalent to 0.001
+    0x_53_AB_F3_82
 
+Float literals are also used to specify durations in seconds. For convenience,
+decimal integer numbers may be combined with the following
+time units:
+
+* `ms` – milliseconds
+* `s` – seconds – 1s equals 1000ms
+* `m` – minutes – 1m equals 60s (ignoring leap seconds)
+* `h` – hours – 1h equals 60m
+* `d` – days – 1d equals 24h (ignoring so-called daylight saving time)
+* `w` – weeks – 1w equals 7d
+* `y` – years – 1y equals 365d (ignoring leap days)
+
+Suffixing a decimal integer number with one of the units above is a different
+representation of the equivalent number of seconds as a bare float literal.
+
+Examples:
+
+    1s # Equivalent to 1.
+    2m # Equivalent to 120.
+    1ms # Equivalent to 0.001.
+    -2h # Equivalent to -7200.
+
+The following examples do _not_ work:
+
+    0xABm # No suffixing of hexadecimal numbers.
+    1.5h # Time units cannot be combined with a floating point.
+    +Infd # No suffixing of ±Inf or NaN.
+
+Multiple units can be combined by concatenation of suffixed integers. Units
+must be ordered from the longest to the shortest. A given unit must only appear
+once per float literal.
+
+Examples:
+
+    1h30m # Equivalent to 5400s and thus 5400.
+    12h34m56s # Equivalent to 45296s and thus 45296.
+    54s321ms # Equivalent to 54.321.
 
 ## Time series selectors
 
@@ -208,53 +246,22 @@ syntax](https://github.com/google/re2/wiki/Syntax).
 ### Range Vector Selectors
 
 Range vector literals work like instant vector literals, except that they
-select a range of samples back from the current instant. Syntactically, a [time
+select a range of samples back from the current instant. Syntactically, a
-duration](#time-durations) is appended in square brackets (`[]`) at the end of
+[float literal](#float-literals-and-time-durations) is appended in square
-a vector selector to specify how far back in time values should be fetched for
+brackets (`[]`) at the end of a vector selector to specify for how many seconds
-each resulting range vector element. The range is a left-open and right-closed interval,
+back in time values should be fetched for each resulting range vector element.
-i.e. samples with timestamps coinciding with the left boundary of the range are excluded from the selection,
+Commonly, the float literal uses the syntax with one or more time units, e.g.
-while samples coinciding with the right boundary of the range are included in the selection.
+`[5m]`. The range is a left-open and right-closed interval, i.e. samples with
+timestamps coinciding with the left boundary of the range are excluded from the
+selection, while samples coinciding with the right boundary of the range are
+included in the selection.
 
-In this example, we select all the values recorded less than 5m ago for all time series
+In this example, we select all the values recorded less than 5m ago for all
-that have the metric name `http_requests_total` and
+time series that have the metric name `http_requests_total` and a `job` label
-a `job` label set to `prometheus`:
+set to `prometheus`:
 
     http_requests_total{job="prometheus"}[5m]
 
-### Time Durations
-
-Time durations are specified as a number, followed immediately by one of the
-following units:
-
-* `ms` - milliseconds
-* `s` - seconds
-* `m` - minutes
-* `h` - hours
-* `d` - days - assuming a day always has 24h
-* `w` - weeks - assuming a week always has 7d
-* `y` - years - assuming a year always has 365d<sup>1</sup>
-
-<sup>1</sup> For days in a year, the leap day is ignored, and conversely, for a minute, a leap second is ignored.
-
-Time durations can be combined by concatenation. Units must be ordered from the
-longest to the shortest. A given unit must only appear once in a time duration.
-
-Here are some examples of valid time durations:
-
-    5h
-    1h30m
-    5m
-    10s
-
-
-As of version 2.54, time durations can also be represented using the syntax of float literals, implying the number of seconds of the time duration. This is an experimental feature and might still change.
-
-Examples:
-
-    1.0 # Equivalent to 1s
-    0.001 # Equivalent to 1ms
-    120 # Equivalent to 2m
-
 ### Offset modifier
 
 The `offset` modifier allows changing the time offset for individual
@@ -337,7 +344,7 @@ Note that the `@` modifier allows a query to look ahead of its evaluation time.
 
 Subquery allows you to run an instant query for a given range and resolution. The result of a subquery is a range vector.
 
-Syntax: `<instant_query> '[' <range> ':' [<resolution>] ']' [ @ <float_literal> ] [ offset <duration> ]`
+Syntax: `<instant_query> '[' <range> ':' [<resolution>] ']' [ @ <float_literal> ] [ offset <float_literal> ]`
 
 * `<resolution>` is optional. Default is the global evaluation interval.