From 4cb5f23c35a5ccfc691485d9db69aeca16d6a59f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Rabenstein?= Date: Tue, 1 Oct 2024 18:03:46 +0200 Subject: [PATCH] api: Improve doc comments for v1.MinTime and v1.MaxTime (#14986) api: Improve doc comments for v1.MinTime and v1.MaxTime While investigated something mostly unrelated, I got nerd-sniped by the calculation of v1.MinTime and v1.MaxTime. The seemingly magic number in there (62135596801) needed an explanation. While looking for it, I found out that the offsets used here are actually needlessly conservative. Since the timestamps are so far in the past or future, respectively, that there is no practical impact, except that the calculation is needlessly obfuscated. However, we won't change the values now to not cause any confusion for users of this code. Still, I think the doc comment should explain the circumstances so nobody gets nerd-sniped again as I did today. For the record: 62135596800 is the difference in seconds between 0001-01-01 00:00:00 (Unix time zero point) and 1971-01-01 00:00:00 (Go time zero point) in the Gregorian calendar. If "Prometheus time" were in seconds (not milliseconds), that difference would be relevant to prevent over-/underflow when converting from "Prometheus time" to "Go time". Signed-off-by: beorn7 --------- Signed-off-by: beorn7 --- web/api/v1/api.go | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/web/api/v1/api.go b/web/api/v1/api.go index 0279f727f1..46666af90c 100644 --- a/web/api/v1/api.go +++ b/web/api/v1/api.go @@ -834,12 +834,22 @@ func (api *API) labelValues(r *http.Request) (result apiFuncResult) { } var ( - // MinTime is the default timestamp used for the begin of optional time ranges. - // Exposed to let downstream projects to reference it. + // MinTime is the default timestamp used for the start of optional time ranges. + // Exposed to let downstream projects reference it. + // + // Historical note: This should just be time.Unix(math.MinInt64/1000, 0).UTC(), + // but it was set to a higher value in the past due to a misunderstanding. + // The value is still low enough for practical purposes, so we don't want + // to change it now, avoiding confusion for importers of this variable. MinTime = time.Unix(math.MinInt64/1000+62135596801, 0).UTC() // MaxTime is the default timestamp used for the end of optional time ranges. // Exposed to let downstream projects to reference it. + // + // Historical note: This should just be time.Unix(math.MaxInt64/1000, 0).UTC(), + // but it was set to a lower value in the past due to a misunderstanding. + // The value is still high enough for practical purposes, so we don't want + // to change it now, avoiding confusion for importers of this variable. MaxTime = time.Unix(math.MaxInt64/1000-62135596801, 999999999).UTC() minTimeFormatted = MinTime.Format(time.RFC3339Nano)