List Samples

Overview

• lists samples in a specified time range.

• Narrow down the result by specifying the following parameters in a query.

  • timestamp
  • resource id
  • resource name
  • meter name
  • namespace
  • project id

• This API performs the same function as "OpenStack Telemetry API: GET /v2/samples".

Classification

• List

API Operation Object

• sample

Synchronous / Asynchronous

• Synchronous

Request

HTTP Request Method

• GET

HTTP Request Path

{api_endpoint}/v2/samples

HTTP Request Header

Content-Type: application/json
Accept: application/json
X-Auth-Token: <token_id>

HTTP Request Body

• none

Request Parameter

Input Parameters

name	style	format	description	required/optional	default value	action for invalid parameter	response code for invalid parameter
q	Query	list	queries of the retrieval condition (Key-Value)	optional	-	Terminate	400
limit	Query	integer	number of samples contained in a page (equal to 'per_page', but 'limit' is given priority over 'per_page' when both of them were specified)	optional	100	Terminate	400
page	Query	integer	target page number	optional	1	Terminate	400
per_page	Query	integer	number of samples 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	optional	-	eq
resource_name	string	resource name	optional	-	eq
meter	string	meter 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 samples 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/samples?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 samples

注釈

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", "resource_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.
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

[
    {
       "metadata":"",
       "meter":"<meter>",
       "display_name":"<display_name>",
       "project_id":"<project_id>",
       "recorded_at":"<recorded_at>",
       "resource_id":"<resource_id>",
       "namespace":"<nova>",
       "source":"",
       "timestamp":"<timestamp>",
       "type":"<type>",
       "unit":"<unit>",
       "user_id":"",
       "volume":<volume>
    },
    <<repeat>>
]

Response Parameter

Response Parameters

item	format		description
metadata	-		metadata (non-use)
meter	String		the meter name
display_name	String		the display name of the meter
project_id	String		ID of the project which the resource is belonging to
recorded_at	datetime		the date and time when the sample was recorded
resource_id	String		the unique id of the metering resource
namespace	String		namespace of the metering SDP
source	-		source (non-use)
timestamp	datetime		the date and time in iso8601 format when the measurement was made
type	String		MeterType
unit	string		the unit of measure for the volume value
user_id	-		user id (non-use)
volume	float		the actual measured value

Sample Request and Response

Sample API Request

Request URL

GET /v2/samples?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&q.field=meter&q.op=eq&q.value=nova.cpu.utilization.percents&q.type=string&per_page=10

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
Date: Thu, 03 Dec 2015 07:26:54 GMT
Cache-Control: max-age=0, private, must-revalidate
Per-Page: 10
Link: <{api_endpoint}/v2/samples?page=12&per_page=10&q.field=meter&q.op=eq&q.type=string&q.value=nova.cpu.utilization.percents>; rel="last", <{api_endpoint}/v2/samples?page=2&per_page=10&q.field=meter&q.op=eq&q.type=string&q.value=nova.cpu.utilization.percents>; rel="next"
Total: 118
Status: 200 OK
Content-Type: application/json; charset=utf-8

Response Body

[
    {
       "metadata":"",
       "meter":"nova.cpu.utilization.percents",
       "display_name":"CpuUtilization",
       "project_id":"29fb4edda2d642ccaab20eb5c27d081f",
       "recorded_at":"2015-11-14T02:25:00+00:00",
       "resource_id":"nova_testvm02e6f-b266-4bef-a23a-b4e7446f259e",
       "namespace":"nova",
       "source":"",
       "timestamp":"2015-12-03T07:26:54+00:00",
       "type":"gauge",
       "unit":"percent",
       "user_id":"",
       "volume":5.0
    },
    {
       "metadata":"",
       "meter":"nova.cpu.utilization.percents",
       "display_name":"CpuUtilization",
       "project_id":"29fb4edda2d642ccaab20eb5c27d081f",
       "recorded_at":"2015-11-14T02:30:00+00:00",
       "resource_id":"nova_testvm02e6f-b266-4bef-a23a-b4e7446f259e",
       "namespace":"nova",
       "source":"",
       "timestamp":"2015-12-03T07:26:54+00:00",
       "type":"gauge",
       "unit":"percent",
       "user_id":"",
       "volume":10.0
    },

    (... snipped ...)

    {
       "metadata":"",
       "meter":"nova.cpu.utilization.percents",
       "display_name":"CpuUtilization",
       "project_id":"29fb4edda2d642ccaab20eb5c27d081f",
       "recorded_at":"2015-11-14T03:10:00+00:00",
       "resource_id":"nova_testvm02e6f-b266-4bef-a23a-b4e7446f259e",
       "namespace":"nova",
       "source":"",
       "timestamp":"2015-12-03T07:26:54+00:00",
       "type":"gauge",
       "unit":"percent",
       "user_id":"",
       "volume":50.0
    }
]

Sample Error Response

HTTP Request

GET /v2/samples?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&q.field=meter&q.op=eq&q.value=nova.cpu.utilization.percents&q.type=string&q.field=resource_id&q.op=ge&q.value=nova_testvm02e6f-b266-4bef-a23a-b4e7446f259e&q.type=string&per_page=10
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: Thu, 03 Dec 2015 08:04:40 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 operator 'ge' for specified field.","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

---

2.3. Sample Management

2.4. Resource Management