Merge "Define timestamp as extension attribute"

specs/mitaka/add-port-timestamp.rst

@@ -0,0 +1,243 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+==========================================
+add-resource-timestamp
+==========================================
+
+https://blueprints.launchpad.net/Neutron/+spec/add-port-timestamp
+
+Resource models like network, subnet and port in Neutron should include
+timestamp fields "created_at" and "updated_at". These two fields can
+facilitate the task of monitoring resource changes, which are time-consuming
+and inefficient currently.
+
+
+Problem Description
+===================
+
+End users may be interested in monitoring Neutron resources or collecting
+statistics on a group of resources in a specific time-frame, for instance,
+querying ports that have changed or refreshed in the last 5 seconds in a
+large scale application. In Neutron, we do not have timestamp fields
+associated with resources, so there is no way we can query them based on
+their operational time.
+
+
+Proposed Change
+===============
+
+We propose to add created_at and updated_at fields to resource models. In the
+sqlalchemy model definition, "default" argument is set to timeutils.utcnow()
+for created_at and updated_at, so when a resource is created, sqlalchemy will
+automatically fill these two fields with the timestamp the resource is created;
+"onupdate" argument is also set to timeutils.utcnow() for updated_at so when a
+resource is updated, updated_at will be refreshed. All the timestamp field
+operations are finished in the database side, so there is no extra work needed
+in the plugin side.
+
+Based on these two fields, change_since filter is introduced for retrieving
+resources. It accepts a timestamp and Neutron will return resources with
+updated_at field later than this timestamp.
+
+Data Model Impact
+-----------------
+
+Two new attributes are added to resource model:
+
++----------------+----------+--------------------+----------+------+-------------------------------+
+| Attribute name | Type     | Default Value      | Required | CRUD | Description                   |
++----------------+----------+--------------------+----------+------+-------------------------------+
+| created_at     | DateTime | timeutils.utcnow() | Y        | R    | Timestamp resource is created |
+| updated_at     | DateTime | timeutils.utcnow() | Y        | R    | Timestamp resource is updated |
++----------------+----------+--------------------+----------+------+-------------------------------+
+
+As discussed above, these two fields are maintained by sqlalchemy in Neutron
+server. It's not necessary for users to pass these two values when creating or
+updating resource, so only Read operation in CRUD is provided.
+
+REST API Impact
+---------------
+
+Created_at and updated_at will be exposed to users via extension API. If plugin
+supports, they are returned when users issue resource retrieving requests.
+Also, resources list API accepts new query string parameter change_since. Users
+can pass timestamp of ISO 8601 format to the list API uri to retrieve resources
+operated since a specific time.
+
+Take port as an example, the request uri looks like this:
+
+.. code::
+
+  GET /v2.0/ports?changed_since=2015-07-31T00:00:00
+
+and response:
+
+.. code::
+
+  {
+      "ports": [
+          {
+              "status": "ACTIVE",
+              "name": "",
+              "allowed_address_pairs": [],
+              "admin_state_up": true,
+              "network_id": "70c1db1f-b701-45bd-96e0-a313ee3430b3",
+              "tenant_id": "",
+              "extra_dhcp_opts": [],
+              "device_owner": "network:router_gateway",
+              "mac_address": "fa:16:3e:58:42:ed",
+              "fixed_ips": [
+                  {
+                      "subnet_id": "008ba151-0b8c-4a67-98b5-0d2b87666062",
+                      "ip_address": "172.24.4.2"
+                  }
+              ],
+              "id": "d80b1a3b-4fc1-49f3-952e-1e2ab7081d8b",
+              "security_groups": [],
+              "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824"
+              "created_at": 2015-07-31T11:50:05
+              "updated_at": 2015-07-31T11:51:12
+          }
+      ]
+  }
+
+Security Impact
+---------------
+
+None
+
+Notifications Impact
+--------------------
+
+None
+
+Other End User Impact
+---------------------
+
+Neutron python client may add help to inform users the new filter. Neutron
+python client supports dynamic assigning search fields so it is easy for it to
+support this new filter. Also Neutron python client needs to add the two new
+fields when displaying resource information.
+
+Take port as an example, the command looks like:
+
+::
+
+  neutron port-list --changed-since 2015-07-31T00:00:00
+
+Performance Impact
+------------------
+
+Performance of syncing resource status with other systems like a monitor system
+or a user interface can be improved. Instead of retrieving all the resources in
+every syncing period to update resource status, these systems can just retrieve
+resources updated during the syncing interval using change_since filter.
+
+IPv6 Impact
+-----------
+
+None
+
+Other Deployer Impact
+---------------------
+
+NTP service needs to be configured and started to synchronize time among nodes,
+so the timestamps saved in created_at and updated_at are valid across nodes.
+
+Developer Impact
+----------------
+
+None
+
+Community Impact
+----------------
+
+This change will bring facility to monitor Neutron resources. Actually most
+projects in OpenStack like `Nova`_, `Cinder`_ have timestamp fields to track
+the operation time of resources.
+
+One problem of absolute timestamp is that sudden system time change caused by
+attack or failure will make the previous cached timestamp invalid. Seeking a
+relative timestamp storing strategy may be a better choice, but it's out of
+the extent of this blueprint.
+
+Alternatives
+------------
+
+None
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  caizhiyuan1@huawei.com
+
+Other contributors:
+  TBD
+
+Work Items
+----------
+
+* Update database schema
+* Add API filter
+* Add related test
+* Update neutron client to support the new filter
+
+
+Dependencies
+============
+
+None
+
+
+Testing
+=======
+
+Tempest Tests
+-------------
+
+None
+
+Functional Tests
+----------------
+
+* Test if created_at and updated_at can be correctly initiated.
+* Test if updated_at can be correctly written when resource updated.
+* Test if change_since filter can be correctly applied.
+
+API Tests
+---------
+
+Test if the new filter can be correctly parsed and validated.
+
+
+Documentation Impact
+====================
+
+User Documentation
+------------------
+
+Update Neutron API reference.
+
+Developer Documentation
+-----------------------
+
+Update developer documentation to introduce the new filter.
+
+
+References
+==========
+
+.. target-notes::
+
+.. _`Nova`: https://github.com/openstack/nova/blob/master/nova/db/sqlalchemy/models.py#L43
+.. _`Cinder`: https://github.com/openstack/cinder/blob/master/cinder/db/sqlalchemy/models.py#L35
+