Create and Put a value into Custom Meter¶

Overview¶

Create a custom meter
Put a sample value into the specified custom meter
"OpenStack Telemetry API" doesn't provide the equivalent of the "Create and Put a value into Custom Meter" API

警告

When a new custom meter creation is requested, it is not possible to put a sample value into the custom meter at the same time.

If "counter_volume" parameter is specified concurrently with the new custom meter creation, the custom meter will be created successfully. However, the "counter_volume" parameter will be ignored.

警告

There is an upper limit to the number of custom meters which you can put sample value(counter_volume) in 24 hours.
The custom meters registerd a sample value in the past 24 hours are called "active custom meters".
Basic Plan: 1 active custom meter is available per a tenant.
Advanced Plan: 30 active custom meter are available per a tenant.

警告

There is an upper limit to the number of sample value(counter_volume) registration to a custom meter per day.
Up to 1500 sample values can be registerd to a custom meter per a day.
The limit counts will be reset at 0:00(UTC) daily.

注釈

This api allow to send multiple requests at the same time by JSON array format.

A JSON array including up to 100 items will be accepted.

Classification¶

Create

API Operation Object¶

custom meter

Synchronous / Asynchronous¶

Synchronous

Request¶

HTTP Request Method¶

POST

HTTP Request Path¶

{api_endpoint}/v2/meters/<custom_meter_name>

HTTP Request Header¶

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

HTTP Request Body¶

Format¶

[
  {
    "project_id": "<project_id>",
    "namespace": "<namespace>",
    "resource_id": "<resource_id>",
    "counter_name": "<counter_name>",
    "counter_type": "<counter_type>",
    "counter_unit": "<counter_unit>",
    "resource_metadata": {
      "display_name": "<display_name>"
    },
    "timestamp": "<timestamp>",
    "counter_volume": "<counter_volume>",
    "recorded_at": "<recorded_at>",
  },
  <<repeat (less than 100 times)>>
]

Request Parameter¶

Input Parameters¶
name	style	format	description	required/optional	default value	action for invalid parameter	response code for invalid parameter
custom_meter_name	Path	String (Up to 255 alpha-numerical one byte characters and some symbols: ['-', '_', '.'])	authentication token	required	-	Terminate	400
token_id	Header	authentication token string	authentication token	required	-	Terminate	401
project_id	Body	String (UUID)	The unique ID of the project(tenant) which the resource and the custom meter are belonging to	optional	the tenant when acquiring the <token_id>	Terminate	401
namespace	Body	String (Up to 32 alpha-numerical one byte characters and some symbols: ['-', '_', '.'])	The namespace of the service	optional	-	Terminate	400
resource_id	Body	String (Up to 64 alpha-numerical one byte characters and some symbols: ['-', '_', '.']) such as "<namespace>_<UUID>"	The unique ID of the metering resource to associate with the custom meter	required	-	Terminate	400
counter_name	Body	String (Must be the same value with "custom_meter_name". Up to 255 alpha-numerical one byte characters and some symbols: ['-', '_', '.'])	The name of the custom meter	required	-	Terminate	400
counter_type	Body	String ( MeterType )	The type of measurement associated with the custom meter	optional	delta	Terminate	400
counter_unit	Body	String (Up to 32 alpha-numerical one byte characters and some symbols: ['-', '_', '.'])	The unit of measurement associated with the custom meter	optional	""	Terminate	400
display_name	Body	String (Up to 255 alpha-numerical one byte characters and some symbols: ['-', '_', '.'])	The friendly display name of the custom meter	optional	the same value with "counter_name"	Terminate	400
timestamp	Body	Datetime (ISO8601)	arbitrary timestamp	optional	the present time when the API request has been accepted	Terminate	400
counter_volume	Body	Float (integer portion: up to 12 digits, fractional portion: up to 4 digits. String will convert to Float.)	The sample value registered with the custom meter. If this parameter is specified in the request, the "counter_volume" value will be put into the custom meter as a sample value.	optional	-	Terminate	400
recorded_at	Body	Datetime (ISO8601)	The datetime when the sample value (counter_volume) was measured and recorded	optional	the present time when the API request has been accepted	Terminate	400

Response¶

Response Header¶

Format¶

HTTP/1.1 <response_code> <status>       (ex. 200 OK)
Content-Type: application/json; charset=utf-8

<response_code>: see "Response Code" section
<status>: message based on the response code

注釈

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	Invalid counter_type. valid meter types: ['cumulative', 'delta', 'gauge']	Invalid counter_type.
		Invalid recorded_at. recorded_at must be the datetime format (ISO8601).	Invalid recorded_at.
		Invalid counter_volume. counter_volume must be float (The max integer portion: 12 digits, The max fractional portion: 4 digits)	Invalid counter_volume.
		Invalid display_name. display_name must be alpha-numerical one byte characters and some symbols: ['-', '_', '.']	Invalid display_name.
		string size of the requested counter_unit is over than 32.	counter_unit string size is over than 32.
		requested counter_name is different from {custom_meter_name} specified in the url path	different from meter_name in counter_name.
		counter_name was not specified	counter_name can't be blank.
		resource_id was not specified	resource_id can't be blank.
		the just-created custom meter can't accept sample values(counter_volume). Please retry after 1min.	Custom meters failed to send samples.
		Only 1 custom meters is cannot update in 24 hours in the basic plan. Please upgrade to the advanced plan and you can update 30 custom meters in 24 hours.	Only 1 custom meters is cannot update in 24 hours in the current plan.
		Can't put sample values(counter_volume) to the custom meter over 1500 times a day.	Custom meter is over than the update limit.
		Too many custom meters has been created in the tenant.	Custom meter is over than the creation limit.
		More than 100 requests are included in the requested JSON array.	Request size is over than 100.
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¶

[
  {
    "project_id": "<project_id>",
    "namespace": "<namespace>",
    "resource_id": "<resource_id>",
    "counter_name": "<counter_name>",
    "counter_type": "<counter_type>",
    "counter_unit": "<counter_unit>",
    "resource_metadata": {
      "display_name": "<display_name>"
    },
    "timestamp": "<timestamp>",
    "counter_volume": "<counter_volume>",
    "source": "",
    "recorded_at": "<recorded_at>",
    "message_id": ""
  },
  <<repeat>>
]

Response Parameter¶

Response Parameters¶
item	format	description
project_id	String	The unique ID of the project(tenant) which the resource and the custom meter are belonging to
namespace	String	The namespace of the service
resource_id	String	The unique ID of the metering resource associated with the custom meter
counter_name	String	The name of the custom meter
counter_type	String ( MeterType )	The type of measurement associated with the custom meter
counter_unit	String	The unit of measurement associated with the custom meter
display_name	String	The friendly display name of the custom meter
timestamp	datetime	The timestamp when the "Create and Put a value into Custom Meter" API has been requested
counter_volume	String	The sample value registered the custom meter
recorded_at	datetime	The datetime of the sample value (counter_volume) recorded
source	-	Non-use
message_id	-	Non-use

Sample Request and Response¶

Sample API Request¶

Request URL¶

GET /v2/meters/vm1_load_average

Request Header¶

Content-Type: application/json
Accept: application/json
X-Auth-Token: 61389973e52b49c394ba3b89179b290b

Request Body¶

[
  {
    "resource_id": "nova_bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
    "counter_name": "vm1_load_average",
    "counter_unit": "count",
    "counter_type": "gauge",
    "counter_volume": "1.01",
    "resource_metadata": {
      "display_name": "Load-Average"
    },
    "recorded_at": "2016-08-01T18:03:00+09:00"
  }
]

Sample API Response¶

Response Header¶

HTTP/1.1 200 OK

Response Body¶

[
  {
    "project_id": "26574d10673044dbb03ffc8facc7ab7a",
    "namespace": "nova",
    "resource_id": "nova_bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
    "counter_name": "vm1_load_average",
    "counter_type": "gauge",
    "counter_unit": "count",
    "resource_metadata": {
      "display_name": "Load-Average"
    },
    "timestamp": "2016-08-01T11:07:17Z",
    "counter_volume": "1.01",
    "source": "",
    "recorded_at": "2016-08-01T18:03:00+09:00",
    "message_id": ""
  }
]

Sample Error Response¶

HTTP Request¶

GET /v2/meters/vm1_load_average
User-Agent: curl/7.19.7
Content-Type: application/json
Accept: application/json
X-Auth-Token: 61389973e52b49c394ba3b89179b290b

[
  {
    "resource_id": "nova_bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
    "counter_name": "vm2_load_average",
    "counter_unit": "count",
    "counter_type": "gauge",
    "counter_volume": "2.51",
    "resource_metadata": {
      "display_name": "Load-Average"
    },
    "recorded_at": "2016-08-01T18:05:00+09:00"
  }
]

HTTP Response¶

HTTP/1.1 400 Bad Request
Date: Mon, 01 Aug 2016 12:26:36 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":"different from meter_name in counter_name.","title":"Bad Request"}}

List Meter Statistics

Sample Scripts to put a sample value into the specified Custom Meter