01f0424930
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
161 lines
5.3 KiB
ReStructuredText
161 lines
5.3 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
========================================
|
|
Usage reports (os-simple-tenant-usage)
|
|
========================================
|
|
|
|
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
|
|
currently defaults to 1000. Older microversions will not accept these new
|
|
paging query parameters, but they will start to silently limit by
|
|
``max_limit``.
|
|
|
|
.. code-block:: none
|
|
|
|
/os-simple-tenant-usage?limit={limit}&marker={instance_uuid}
|
|
/os-simple-tenant-usage/{tenant_id}?limit={limit}&marker={instance_uuid}
|
|
|
|
.. note::
|
|
|
|
A tenant's usage statistics may span multiple pages when the number of
|
|
instances exceeds ``limit``, and API consumers will need to stitch together
|
|
the aggregate results if they still want totals for all instances in a
|
|
specific time window, grouped by tenant.
|
|
|
|
List Tenant Usage Statistics For All Tenants
|
|
============================================
|
|
|
|
.. rest_method:: GET /os-simple-tenant-usage
|
|
|
|
Lists usage statistics for all tenants.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- detailed: detailed_simple_tenant_usage
|
|
- end: end_simple_tenant_usage
|
|
- start: start_simple_tenant_usage
|
|
- limit: usage_limit
|
|
- marker: usage_marker
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_usages: tenant_usages
|
|
- start: start_simple_tenant_usage_body
|
|
- stop: stop_simple_tenant_usage
|
|
- tenant_id: tenant_id_body
|
|
- total_hours: total_hours
|
|
- total_local_gb_usage: total_local_gb_usage
|
|
- total_memory_mb_usage: total_memory_mb_usage
|
|
- total_vcpus_usage: total_vcpus_usage
|
|
- server_usages: server_usages_optional
|
|
- server_usages.ended_at: ended_at_optional
|
|
- server_usages.flavor: flavor_name_optional
|
|
- server_usages.hours: hours_optional
|
|
- server_usages.instance_id: server_id_optional
|
|
- server_usages.local_gb: local_gb_simple_tenant_usage_optional
|
|
- server_usages.memory_mb: memory_mb_simple_tenant_usage_optional
|
|
- server_usages.name: server_name_optional
|
|
- server_usages.started_at: started_at_optional
|
|
- server_usages.state: vm_state_optional
|
|
- server_usages.tenant_id: tenant_id_optional
|
|
- server_usages.uptime: uptime_simple_tenant_usage_optional
|
|
- server_usages.vcpus: vcpus_optional
|
|
- tenant_usages_links: usage_links
|
|
|
|
**Example List Tenant Usage For All Tenants (v2.40): JSON response**
|
|
|
|
If the ``detailed`` query parameter is not specified or
|
|
is set to other than 1 (e.g. ``detailed=0``), the response is as follows:
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-simple-tenant-usage/v2.40/simple-tenant-usage-get.json
|
|
:language: javascript
|
|
|
|
If the ``detailed`` query parameter is set to one (``detailed=1``),
|
|
the response includes ``server_usages`` information for each tenant.
|
|
The response is as follows:
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-simple-tenant-usage/v2.40/simple-tenant-usage-get-detail.json
|
|
:language: javascript
|
|
|
|
Show Usage Statistics For Tenant
|
|
================================
|
|
|
|
.. rest_method:: GET /os-simple-tenant-usage/{tenant_id}
|
|
|
|
Shows usage statistics for a tenant.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id
|
|
- end: end_simple_tenant_usage
|
|
- start: start_simple_tenant_usage
|
|
- limit: usage_limit
|
|
- marker: usage_marker
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_usage: tenant_usage
|
|
- server_usages: server_usages
|
|
- server_usages.ended_at: ended_at
|
|
- server_usages.flavor: flavor_name
|
|
- server_usages.hours: hours
|
|
- server_usages.instance_id: server_id
|
|
- server_usages.local_gb: local_gb_simple_tenant_usage
|
|
- server_usages.memory_mb: memory_mb_simple_tenant_usage
|
|
- server_usages.name: server_name
|
|
- server_usages.started_at: started_at
|
|
- server_usages.state: OS-EXT-STS:vm_state
|
|
- server_usages.tenant_id: tenant_id_body
|
|
- server_usages.uptime: uptime_simple_tenant_usage
|
|
- server_usages.vcpus: vcpus
|
|
- start: start_simple_tenant_usage_body
|
|
- stop: stop_simple_tenant_usage
|
|
- tenant_id: tenant_id_body
|
|
- total_hours: total_hours
|
|
- total_local_gb_usage: total_local_gb_usage
|
|
- total_memory_mb_usage: total_memory_mb_usage
|
|
- total_vcpus_usage: total_vcpus_usage
|
|
- tenant_usage_links: usage_links
|
|
|
|
**Example Show Usage Details For Tenant (v2.40): JSON response**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-simple-tenant-usage/v2.40/simple-tenant-usage-get-specific.json
|
|
:language: javascript
|