List Meter Statistics¶
Overview¶
Computes and lists statistics for samples in a specified time range.
Narrow down the result by specifying the following parameters in a query.
- timestamp
- resource id
- resource name
- namespace
- project id
This API performs the same function as "OpenStack Telemetry API: GET /v2/meters/{meter_name}/statistics".
Classification¶
- List
API Operation Object¶
- meter statistic
Synchronous / Asynchronous¶
- Synchronous
Request¶
HTTP Request Method¶
- GET
HTTP Request Path¶
{api_endpoint}/v2/meters/{meter_name}/statistics
HTTP Request Header¶
Content-Type: application/json
Accept: application/json
X-Auth-Token: <token_id>
HTTP Request Body¶
- none
Request Parameter¶
You can retrieve the specified resource's statistics up to one month per request.
| name | style | format | description | required/optional | default value | action for invalid parameter | response code for invalid parameter |
|---|---|---|---|---|---|---|---|
| meter_name | url | string | name of the meter | required | - | - | 200 |
| q | Query | list | queries of the meter statistics retrieval condition (Key-Value) | required | - | Terminate | 400 |
| period | Query | integer | the sampling period to compute statistic, in seconds | optional | 0 (all samples between start-timestamp and end-timestamp are included to compute statistics ) | Terminate | 400 |
| groupby | Query | list | non-supported parameter | - | - | - | - |
| aggregate | Query | list | non-supported parameter | - | - | - | - |
| page | Query | integer | target page number | optional | 1 | Terminate | 400 |
| per_page | Query | integer | number of meter statistics contained in a page | optional | 100 | Terminate | 400 |
| token_id | Header | authentication token string | authentication token | required | - | Terminate | 401 |
A query key can be designated by describing after a dot(.) . (ex. q.field, q.op)
| key name | format | description | required/optional | default value |
|---|---|---|---|---|
| field | string | a retrieving target | required | - |
| op | string | a comparison operator | optional | eq |
| value | string | a field value for retrieving meter statistics | required | - |
| type | string | format used to convert the value for comparison | optional | - |
A query field can be designated by describing after "q.field=". (ex. q.field=timestamp)
| key name | format | description | required/optional | default value | valied operator |
|---|---|---|---|---|---|
| timestamp | datetime | start time of the retrieving range | optional | - | ge |
| timestamp | datetime | end time of the retrieving range | optional | - | le |
| project_id | string | project(tenant) id | optional | - | eq |
| resource_id | string | resource id | required | - | eq |
| resource_name | string | resource name | optional | - | eq |
| namespace | string | namespace of the services | optional | - | eq |
| source | string | non-supported parameter | - | - | - |
A query operator can be designated by describing after "q.op=". (ex. q.op=eq)
| operator | description |
|---|---|
| eq | equal to |
| le | less than or equal to |
| ge | greater than or equal to |
A query type can be designated by describing after "q.type=". (ex. q.type=integer)
| type | ex. (q.value) |
|---|---|
| integer | 1234 |
| float | 1234.1234 |
| boolean | 0 or 1 |
| string | abcd |
| datetime | 2015-12-01T12:34:00+09:00 |
Response¶
Response Header¶
Format¶
HTTP/1.1 <response_code> <status> (ex. 200 OK)
Per-Page: <per_page>
Link: <link>; rel="<rel>", <link>; rel="<rel>", <link>; rel="<rel>", <link>; rel="<rel>"
Total: <total>
Content-Type: application/json; charset=utf-8
- <response_code>: see "Response Code" section
- <status>: message based on the response code
- <per_page>: number of meter statistics contained in a page
The following are the information about pagination.
<link>: url of a specific page (ex. http://monitoring-jp1-ecl.api.ntt.com/v2/meters?page=3)
- <rel>: property of the url
- "next": url of the next page
- "last": url of the last page
- "prev": url of the previous page
- "first": url of the first page
<total>: total number of meter statistics
注釈
Not including auto-insert fields such as "Transfer-Encoding", "Date" and others.
Response Code¶
| response code | status | condition | message |
|---|---|---|---|
| 200 | ok | normal end | |
| 400 | bad request | specified non query field | Field can't be blank. |
| invalid query field | Unrecognized field in query. valid keys:["project_id", "timestamp", "resource_id", "esource_name", "meter"] | ||
| invalid query op | Unimplemented operator 'xxxx' for specified field. | ||
| specified non query value | Value can't be blank. | ||
| invalid query data type (1) | The data type 'xxxx' is not supported. The supported data type list is: ['integer', 'float', 'boolean', 'string', 'datetime'] | ||
| invalid query data type (2) | Unimplemented data type 'xxxx' for timestamp. valid data types: ["datetime"] | ||
| invalid value (1) | Unable to convert the value 'xxxx' to the expected data type 'integer'. | ||
| invalid value (2) | Unexpected exception converting 'xxxx' to the expected data type "datetime". | ||
| invalid timestamp value | Please designate end_timestamp newer than start_timestamp. | ||
| invalid period | A bad out-of-range value was supplied for the request parameter. | ||
| 401 | unauthorized | authentication failure | The request you have made requires authentication. |
| invalid project id | Not authorized to access project. | ||
| 500 | internal server error | internal server error | The request processing has failed due to some unknown error, exception or failure |
Response Body¶
Format¶
[
{
"period": "<period>",
"period_start": "<period_start>",
"period_end": "<period_end>",
"duration": "<duration>",
"duration_start": "<duration_start>",
"duration_end": "<duration_end>",
"sum": "<sum>",
"count": "<count>",
"avg": "<avg>",
"max": "<max>",
"min": "<min>",
"unit": "<unit>"
},
<<repeat>>
]
Response Parameter¶
| item | format | description | |
|---|---|---|---|
| period | integer | the number of seconds between the period start and end date and time stamps | |
| period_start | datetime | the period start date and time | |
| period_end | datetime | the period end date and time | |
| duration | integer | the number of seconds between the oldest and newest sample's timestamps | |
| duration_start | datetime | the timestamp of the oldest sample during the period | |
| duration_end | datetime | the timestamp of the newest sample during the period | |
| sum | float | the sum of sample volumes between period_start and period_end | |
| count | integer | the number of samples between period_start and period_end | |
| avg | float | the average volume of samples between period_start and period_end | |
| max | float | the maximum volume of samples between period_start and period_end | |
| min | float | the minimun volume of samples between period_start and period_end | |
| unit | string | unit of the meter |
Sample Request and Response¶
Sample API Request¶
Request URL¶
GET /v2/meters/nova.cpu.utilization.percents/statistics?q.field=timestamp&q.op=ge&q.value=2015-11-14T11:25:00+09:00&q.type=datetime&q.field=timestamp&q.value=2015-11-14T16:15:00+09:00&q.op=le&q.type=datetime&period=1200
Request Header¶
Content-Type: application/json
Accept: application/json
X-Auth-Token: 61389973e52b49c394ba3b89179b290b
Request Body¶
- none
Sample API Response¶
Response Header¶
HTTP/1.1 200 OK
Response Body¶
[
{
"period":1200,
"period_start":"2015-11-14T02:25:00+00:00",
"period_end":"2015-11-14T02:45:00+00:00",
"duration":900,
"duration_start":"2015-11-14T02:25:00+00:00",
"duration_end":"2015-11-14T02:40:00+00:00",
"sum":70.0,
"count":8,
"avg":8.75,
"max":20.0,
"min":5.0,
"unit":"percent"
},
{
"period":1200,
"period_start":"2015-11-14T02:45:00+00:00",
"period_end":"2015-11-14T03:05:00+00:00",
"duration":900,
"duration_start":"2015-11-14T02:45:00+00:00",
"duration_end":"2015-11-14T03:00:00+00:00",
"sum":150.0,
"count":8,
"avg":18.75,
"max":40.0,
"min":5.0,
"unit":"percent"
},
(... snipped ...)
{
"period":1200,
"period_start":"2015-11-14T07:05:00+00:00",
"period_end":"2015-11-14T07:25:00+00:00",
"duration":600,
"duration_start":"2015-11-14T07:05:00+00:00",
"duration_end":"2015-11-14T07:15:00+00:00",
"sum":150.0,
"count":6,
"avg":25.0,
"max":50.0,
"min":0.0,
"unit":"percent"
}
]
Sample Error Response¶
HTTP Request¶
GET /v2/meters/nova.cpu.utilization.percents/statistics?q.field=timestamp&q.op=ge&q.value=2015-11-14T11:25:00+09:00&q.type=datetime&q.field=timestamp&q.value=2015-11-14T16:15:00+09:00&q.op=le&q.type=integer&period=1200'
User-Agent: curl/7.19.7
Content-Type: application/json
Accept: application/json
X-Auth-Token: 61389973e52b49c394ba3b89179b290b
HTTP Response¶
HTTP/1.1 400 Bad Request
Date: Wed, 02 Dec 2015 07:26:59 GMT
Server: Apache
Cache-Control: no-cache
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Status: 400 Bad Request
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{"error":{"code":400,"message":"Unimplemented data type 'integer' for timestamp. valid data types: [\"datetime\"]","title":"Bad Request"}}