openstack/nova
Code Issues Proposed changes

Enhance simple usage API documentation

Browse Source 
Nova's `os-simple-tenant-usage` has the following statement.

```
Reports usage statistics of compute and storage resources periodically
for an individual tenant or all tenants. The usage statistics will
include all instances’ CPU, memory and local disk during a specific
period.

```

To some people, when reading that, they might get the understanding that
the `os-simple-tenant-usage` will report the actual use of resources.
Therefore, if a VM is stopped and then started back again, it (the
`os-simple-tenant-usage`) would only report the time the VM has been up
and running. However, that is not what happens. The
`os-simple-tenant-usage` reports the time that a virtual machine (VM)
exists in the cloud environment. Therefore, actions such as pause,
suspend, and stop do not affect the usage accounting.

This might be a problem for people using this API for billing, or for
people that use other systems (e.g. CloudKitty) for billing.
End-users might try to cross-check the data from the billing from
CloudKitty for instance, with the usage report found in Horizon that
uses this API, and the numbers will not add up, as people might only
consider the time a VM has been up and running to charge users in
CloudKitty.

An extension was proposed in [1], to allow operators to customize
the usage accounting. However, during a meeting with the community [2],
the extension was rejected for two reasons:

* Nova tries to avoid using config driven APIs. Meaning, APIs that change
  the response according to server-side configurations;
* The community has decided to get rid of usage and billing accounting
  in Nova.

Having said that, we would like to propose a documentation amendment.
The idea is to explicitly say for users/operators that the simple usage
API only considers the time that the VM existed in the cloud for the
accounting, and not the actual time it has been up and running.
This will save some misunderstanding and misuse of the API data.

References
===========
[1] https://review.opendev.org/c/openstack/nova/+/711113
[2] http://eavesdrop.openstack.org/meetings/nova/2020/nova.2020-12-03-16.00.log.txt

Closes-Bug: #1907133
Change-Id: Ic55669f5210b57f151f693393f205655765a8dc9
This commit is contained in:
Rafael Weingärtner 2020-12-07 17:26:33 -03:00
parent 97729aabaa
commit 01f0424930
1 changed files with 12 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
api-ref/source/os-simple-tenant-usage.inc
View File

@ -8,6 +8,18 @@ Reports usage statistics of compute and storage resources periodically
for an individual tenant or all tenants. The usage statistics will include
all instances' CPU, memory and local disk during a specific period.
.. warning::
The `os-simple-tenant-usage` will report usage statistics based on the latest
flavor that is configured in the virtual machine (VM), and ignoring stop,
pause, and other events that might have happened with the VM. Therefore, it
uses the time the VM existed in the cloud environment to execute the usage
accounting.
More information can be found at
http://eavesdrop.openstack.org/meetings/nova/2020/nova.2020-12-03-16.00.log.txt,
and https://review.opendev.org/c/openstack/nova/+/711113
Microversion 2.40 added pagination (and ``next`` links) to the usage
statistics via optional ``limit`` and ``marker`` query parameters. If
``limit`` isn't provided, the configurable ``max_limit`` will be used which