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.

Input Parameters

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)

Valied query keys

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)

Valied query fields

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)

Valied operators in a query

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)

Valied types in a query

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 Codes

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

Response Parameters

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"}}

目次

• 1. What is Smart Data Platform Monitoring API
  • 1.1. How to use API client
• 2. Smart Data Platform Monitoring API List
  • 2.1. Alarm Management
  • 2.2. Meter Management
  • 2.3. Sample Management
  • 2.4. Resource Management
  • 2.5. Check Capability
• 3. Smart Data Platform Monitoring API DataType List
  • 3.1. Alarm
  • 3.2. AlarmChange
  • 3.3. AlarmThresholdRule
  • 3.4. Meter
  • 3.5. MeterStatistic
  • 3.6. Custom Meter
  • 3.7. Sample
  • 3.8. Resource
  • 3.9. Query
• 4. Revision History

---

List Meters

Create and Put a value into Custom Meter