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