ac4cc65cb5
Contains .inc files which have all the contents of the .rst files but are grouped together for easier editing. Contains parameters.yaml, which has all parameters in one file. Contains request and response samples (JSON and XML) that are pointed to from the .inc files. Change-Id: I42d5451300f95774a3ec4df66bc95cb36795844d
387 lines
7.6 KiB
ReStructuredText
387 lines
7.6 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
======
|
|
Meters
|
|
======
|
|
|
|
Lists all meters, adds samples to meters, and lists samples for
|
|
meters. For list operations, if you do not explicitly set the
|
|
``limit`` query parameter, a default limit is applied. The default
|
|
limit is the ``default_api_return_limit`` configuration option
|
|
value.
|
|
|
|
Also, computes and lists statistics for samples in a time range.
|
|
You can use the ``aggregate`` query parameter in the ``statistics``
|
|
URI to explicitly select the ``stddev``, ``cardinality``, or any
|
|
other standard function. For example:
|
|
|
|
::
|
|
|
|
GET /v2/meters/METER_NAME/statistics?aggregate.func=NAME
|
|
&
|
|
aggregate.param=VALUE
|
|
|
|
The ``aggregate.param`` parameter value is optional for all
|
|
functions except the ``cardinality`` function.
|
|
|
|
The API silently ignores any duplicate aggregate function and
|
|
parameter pairs.
|
|
|
|
The API accepts and storage drivers support duplicate functions
|
|
with different parameter values. In this example, the
|
|
``cardinality`` function is accepted twice with two different
|
|
parameter values:
|
|
|
|
::
|
|
|
|
GET /v2/meters/METER_NAME/statistics?aggregate.func=cardinality
|
|
&
|
|
aggregate.param=resource_id
|
|
&
|
|
aggregate.func=cardinality
|
|
&
|
|
aggregate.param=project_id
|
|
|
|
**Examples:**
|
|
|
|
Use the ``stddev`` function to request the standard deviation of
|
|
CPU utilization:
|
|
|
|
::
|
|
|
|
GET /v2/meters/cpu_util/statistics?aggregate.func=stddev
|
|
|
|
The response looks like this:
|
|
|
|
.. code-block:: json
|
|
|
|
[
|
|
{
|
|
"aggregate": {
|
|
"stddev": 0.6858829
|
|
},
|
|
"duration_start": "2014-01-30T11:13:23",
|
|
"duration_end": "2014-01-31T16:07:13",
|
|
"duration": 104030,
|
|
"period": 0,
|
|
"period_start": "2014-01-30T11:13:23",
|
|
"period_end": "2014-01-31T16:07:13",
|
|
"groupby": null,
|
|
"unit": "%"
|
|
}
|
|
]
|
|
|
|
Use the ``cardinality`` function with the project ID to return the
|
|
number of distinct tenants with images:
|
|
|
|
::
|
|
|
|
GET /v2/meters/image/statistics?aggregate.func=cardinality
|
|
&
|
|
aggregate.param=project_id
|
|
|
|
The following, more complex, example determines:
|
|
|
|
- The number of distinct instances (``cardinality``)
|
|
|
|
- The total number of instance samples (``count``) for a tenant in
|
|
15-minute intervals (``period`` and ``groupby`` options)
|
|
|
|
::
|
|
|
|
GET /v2/meters/instance/statistics?aggregate.func=cardinality
|
|
&
|
|
aggregate.param=resource_id
|
|
&
|
|
aggregate.func=count
|
|
&
|
|
groupby=project_id
|
|
&
|
|
period=900
|
|
|
|
The response looks like this:
|
|
|
|
.. code-block:: json
|
|
|
|
[
|
|
{
|
|
"count": 19,
|
|
"aggregate": {
|
|
"count": 19,
|
|
"cardinality/resource_id": 3
|
|
},
|
|
"duration": 328.47803,
|
|
"duration_start": "2014-01-31T10:00:41.823919",
|
|
"duration_end": "2014-01-31T10:06:10.301948",
|
|
"period": 900,
|
|
"period_start": "2014-01-31T10:00:00",
|
|
"period_end": "2014-01-31T10:15:00",
|
|
"groupby": {
|
|
"project_id": "061a5c91811e4044b7dc86c6136c4f99"
|
|
},
|
|
"unit": "instance"
|
|
},
|
|
{
|
|
"count": 22,
|
|
"aggregate": {
|
|
"count": 22,
|
|
"cardinality/resource_id": 4
|
|
},
|
|
"duration": 808.00385,
|
|
"duration_start": "2014-01-31T10:15:15",
|
|
"duration_end": "2014-01-31T10:28:43.003840",
|
|
"period": 900,
|
|
"period_start": "2014-01-31T10:15:00",
|
|
"period_end": "2014-01-31T10:30:00",
|
|
"groupby": {
|
|
"project_id": "061a5c91811e4044b7dc86c6136c4f99"
|
|
},
|
|
"unit": "instance"
|
|
},
|
|
{
|
|
"count": 2,
|
|
"aggregate": {
|
|
"count": 2,
|
|
"cardinality/resource_id": 2
|
|
},
|
|
"duration": 0,
|
|
"duration_start": "2014-01-31T10:35:15",
|
|
"duration_end": "2014-01-31T10:35:15",
|
|
"period": 900,
|
|
"period_start": "2014-01-31T10:30:00",
|
|
"period_end": "2014-01-31T10:45:00",
|
|
"groupby": {
|
|
"project_id": "061a5c91811e4044b7dc86c6136c4f99"
|
|
},
|
|
"unit": "instance"
|
|
}
|
|
]
|
|
|
|
|
|
Show meter statistics
|
|
=====================
|
|
|
|
.. rest_method:: GET /v2/meters/{meter_name}/statistics
|
|
|
|
Computes and lists statistics for samples in a time range.
|
|
|
|
|
|
Normal response codes: 200
|
|
Error response codes:
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- meter_name: meter_name
|
|
- q: q
|
|
- groupby: groupby
|
|
- period: period
|
|
- aggregate: aggregate
|
|
- limit: limit
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- count: count
|
|
- duration_start: duration_start
|
|
- min: min
|
|
- max: max
|
|
- duration_end: duration_end
|
|
- period: period
|
|
- sum: sum
|
|
- duration: duration
|
|
- period_end: period_end
|
|
- aggregate: aggregate
|
|
- period_start: period_start
|
|
- avg: avg
|
|
- groupby: groupby
|
|
- unit: unit
|
|
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ../samples/statistics-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
|
|
|
|
List meters
|
|
===========
|
|
|
|
.. rest_method:: GET /v2/meters
|
|
|
|
Lists meters, based on the data recorded so far.
|
|
|
|
|
|
Normal response codes: 200
|
|
Error response codes:
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- q: q
|
|
- limit: limit
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- user_id: user_id
|
|
- name: name
|
|
- resource_id: resource_id
|
|
- source: source
|
|
- meter_id: meter_id
|
|
- project_id: project_id
|
|
- type: type
|
|
- unit: unit
|
|
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ../samples/meters-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
|
|
|
|
List samples for meter
|
|
======================
|
|
|
|
.. rest_method:: GET /v2/meters/{meter_name}
|
|
|
|
Lists samples for a meter, by meter name.
|
|
|
|
|
|
Normal response codes: 200
|
|
Error response codes:
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- meter_name: meter_name
|
|
- q: q
|
|
- limit: limit
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- user_id: user_id
|
|
- resource_id: resource_id
|
|
- timestamp: timestamp
|
|
- meter: meter
|
|
- volume: volume
|
|
- source: source
|
|
- recorded_at: recorded_at
|
|
- project_id: project_id
|
|
- type: type
|
|
- id: id
|
|
- unit: unit
|
|
- metadata: metadata
|
|
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ../samples/samples-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
|
|
|
|
Add samples to meter
|
|
====================
|
|
|
|
.. rest_method:: POST /v2/meters/{meter_name}
|
|
|
|
Adds samples to a meter, by meter name.
|
|
|
|
If you attempt to add a sample that is not supported, this call
|
|
returns the ``409`` response code.
|
|
|
|
|
|
Normal response codes: 200
|
|
Error response codes:409,
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- user_id: user_id
|
|
- resource_id: resource_id
|
|
- timestamp: timestamp
|
|
- meter: meter
|
|
- volume: volume
|
|
- source: source
|
|
- recorded_at: recorded_at
|
|
- project_id: project_id
|
|
- type: type
|
|
- id: id
|
|
- unit: unit
|
|
- metadata: metadata
|
|
- meter_name: meter_name
|
|
- direct: direct
|
|
- samples: samples
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: ../samples/sample-create-request.json
|
|
:language: javascript
|
|
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- user_id: user_id
|
|
- resource_id: resource_id
|
|
- timestamp: timestamp
|
|
- meter: meter
|
|
- volume: volume
|
|
- source: source
|
|
- recorded_at: recorded_at
|
|
- project_id: project_id
|
|
- type: type
|
|
- id: id
|
|
- unit: unit
|
|
- metadata: metadata
|
|
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ../samples/sample-show-response.json
|
|
:language: javascript
|
|
|
|
|
|
|
|
|