TimeSeries Query for last 5 Minutes not Last 5 Minutes

[waprin]

The usage docs say

query = client.query(METRIC, minutes=5)

will give you stats for the last five minutes. But since the code replaces seconds and microseconds with 0, it's not actually the last 5 minutes since you won't be querying any time interval between the end of the previous minute and the current second.

The reason this came up is in the system tests, I write a point, then try to query it back, but I never get the time series even if they are there, since I

write_point: 2016-09-28T19:29:57.726637
query end_time: 2016-09-28T19:29:00.000000Z

so even though write_point happened first, it's end_time is after the end_time of the query.

Maybe people think second granularity doesn't matter? I'm curious why replacing the second/microseconds with 0 was done in the first place. I think at a minimum the docs are slightly misleading, since it's not the last 5 minutes in the colloquial sense (doesn't include the seconds up until now in the current minute).

cc @rimey @supriyagarg

[supriyagarg]

@waprin: To get the data for a time period ending exactly now, it is recommended to explicitly specify the end time either during initialization or using select_interval. Given that you can write up to one point per minute, this could miss the latest data point.

The end time of the query determines the exact timestamps when using alignment, so zeroing out seconds and microseconds makes the results look nicer, and easier to understand.

[waprin]

Ok, that's what I did in #2460 so we could leave it at that. However I still think the behavior is a bit surprising so I'm curious if you

• Can explain the motivation for replacing the seconds
• Agree we should at least call this out more explicitly in the docs, rather than just say "the last 5 minutes"

[supriyagarg]

The motivation is as I mentioned in the previous comment:

The end time of the query determines the exact timestamps when using alignment, so zeroing out seconds and microseconds makes the results look nicer, and easier to understand.

In most cases alignment is indeed required, so this applies to a majority of use cases. Also, for specifying exact time intervals select_interval is better. The init method is designed to support common use cases, especially when trying out the library.

Agreed that the top level docs should be updated. Something like the following would work:

Display CPU utilization across your GCE instances over a 5 minute duration ending at the start of the current minute.

[rimey]

It's good to know that this pitfall exists, but we have to focus on normal end-user use-cases. Using a round minute as the default end time makes aligned data much prettier. I found the library annoying to use with the exact current time as the default.

[waprin]

Yeah it makes sense to me, writing a time series and immediately reading it back is probably only something we'll do in the system test, and I'm sure on charts and graphs having round minutes is cleaner. I think the doc change is still a good idea just in case, so after that gets merged I think we can close the issue.