From 1600eee0e282ed892ba56ea60565b56950e72de1 Mon Sep 17 00:00:00 2001 From: Luka Peschke Date: Thu, 28 Mar 2019 16:19:57 +0100 Subject: [PATCH] Spec: Making CloudKitty timezone-aware See specs/train/timezone_aware.rst and the associated story for more details. Story: 2005319 Task: 30240 Change-Id: Iebf19852302ce2ae85418ccca07cec9632486b7d --- specs/train/timezone_aware.rst | 170 +++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 specs/train/timezone_aware.rst diff --git a/specs/train/timezone_aware.rst b/specs/train/timezone_aware.rst new file mode 100644 index 0000000..4bb2201 --- /dev/null +++ b/specs/train/timezone_aware.rst @@ -0,0 +1,170 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +================================ +Making CloudKitty timezone-aware +================================ + +Associated story: https://storyboard.openstack.org/#!/story/2005319 + +Currently, CloudKitty is not timezone-aware and every timestamp is considered +to be UTC. In order to improve user experience, avoid confusion and potential +bugs (when doing time object conversions), CloudKitty should be made +timezone-aware. + +Problem Description +=================== + +Internally, CloudKitty manipulates timezone-unaware ``datetime`` objects and +timestamps. Every object representing some point in time is considered to be +UTC. This can be confusing for users (which expect the timestamps of their data +to be in their current timezone) as well as a source of bugs: A ``datetime`` +object (converted to an iso8601 format timestamp) has no timezone information. +There is no guarantee about how this kind of string will be interpreted by +another API: as UTC, or in the API's local time ? + +Proposed Change +=============== + +In order to secure CloudKitty's behaviour about timezones, the following points +should be applied: + +* All ``datetime`` objects must be made timezone-aware. + +* CloudKitty must only manipulate ``datetime`` objects. Functions or interfaces + accepting several types of objects for parameters containing time information + must be changed in order to only accept timezone-aware ``datetime`` objects. + +* The conversion to/from iso8601 timestamps or unix timestamps must be done at + the interface level. This means that conversions to/from timezone-aware + ``datetime`` objects must only be done by CloudKitty's HTTP API and the + different drivers (storage, fetcher, collector, messaging...), and only when + this type is not supported. + +* Any timezone-unaware object retrieved by the API must be considered as UTC, + made timezone-aware and raise a warning. + +* The handling of timezone-aware objects is not consistent between different + SQL databases. In consequence, the storage state will still be stored with + no timezone information and will be stored as UTC. The storage state driver + will be in charge of making objects aware/unaware and will only + provide/accept timezone-aware ``datetime`` objects. To avoid complex + migrations and inconsistencies, the same rule will apply to the timestamps of + dataframes: They will be stored as timezone-unaware timestamps and considered + to be UTC. The storage driver will be responsible for the conversions. + +* Client functions querying the v2 API will send iso8601 timestamps with + timezone information. If no timezone information is provided in the CLI + arguments, they will be considered as local time and adequate timezone + information will be added. + +For convenience, microseconds will not be supported for now, and will be set +to 0 in all ``datetime`` objects. + +Alternatives +------------ + +- Leaving the code as is and making clear in the documentation that everything + is UTC. This does not prevent unexpected behaviour when sending + timezone-unaware info to other APIs. + +Data model impact +----------------- + +None, the storage state model is not modified. + +REST API impact +--------------- + +None. + +Security impact +--------------- + +None. + +Notifications Impact +-------------------- + +None. + +Other end user impact +--------------------- + +For v2 API endpoints, timestamps with no timezone information passed to the +client will be considered as localtime by the client, and timezone information +will be updated accordingly. + +Performance Impact +------------------ + +None. + +Other deployer impact +--------------------- + +None. The upgrade will impact neither the state storage nor the dataframes +storage as no storage migration will be required. In consequence, the existing +data will not be impacted. + +Developer impact +---------------- + +Clear and stricter rules will reduce potential time-related bugs in new +features implementation. + +Implementation +============== + +Assignee(s) +----------- + +Gerrit topic: + timezone-aware + +Primary assignee: + peschk_l + +Other contributors: + None + +Work Items +---------- + +Some of the following points are highly interdependent and may need to be +implemented in the same commit: + +- Removing usage of Unix timestamps from the codebase in order to only + manipulate ``datetime`` objects internally. + +- Adding timezone information to all ``datetime`` objects manipulated + internally. + +- Make the functions of the client querying the v2 API timezone-aware. + +Dependencies +============ + +- ``python-dateutil``: Library providing extensions to the standard library's + ``datetime`` module. + +Testing +======= + +Unit tests are sufficient until the v2 API has more endpoints. Tempest tests +testing v2 API endpoints should be ran with and without timezone information +in timestamps to ensure that the API has the expected behaviour. + +Documentation Impact +==================== + +The v2 API documentation and client documentation will include a description +of their behaviour with timezone-aware/unaware timestamps. + +References +========== + +None.