Request path and method
Request path | Request method | Description |
---|---|---|
/api/put | POST | Writes multiple data points at a time. |
Request parameters
Parameter | Type | Required | Description | Default value | Example |
---|---|---|---|---|---|
summary | Untyped | No | Specifies whether to return the summary. | false | /api/put?summary |
details | Untyped | No | Specifies whether to return the details. | false | /api/put?details |
sync_timeout | Integer | No | The timeout period. Unit: milliseconds. The value 0 indicates that the request never times out. | 0 | /api/put/?sync&sync_timeout=60000 |
ignoreErrors | Untyped | No | Specifies whether to ignore the write exceptions of some data points. | false | /api/put/?ignoreErrors |
Note:
The system determines that the value of an untyped parameter is true if the parameter is configured. For example, the system determines that the value of the summary parameter is true regardless of whether you set the parameter to true or false.
If you specify both the details parameter and the summary parameter, the API operation returns the details.
Request parameters
Specify a data point in the JSON format. The following table describes the parameters for a data point.
Parameter | Type | Required | Limit | Description | Example |
---|---|---|---|---|---|
metric | String | Yes | The value can contain only letters, digits, and the following special characters: | The name of the metric to be stored. | sys.cpu Note In the High-availability Edition, the metric name can be up to 255 bytes in length. |
timestamp | Long | Yes | None | The timestamp measured in seconds or milliseconds. For more information about the rules for determining the unit, see the Timestamp units section in this topic. | 1499158925 |
value | Long,Double,String,Boolean | Yes | None | The value in the data point. | 42.5, true |
tags | Map | No | The value can contain only letters, digits, and the following special characters: | The tag key-value pairs. Tag keys and tag values are character strings. Specify at least one tag key-value pair. | {"host":"web01"}. Tag keys and tag values that are not of the STRING data type are explicitly converted to the STRING type. |
Timestamp units
This section describes the rules for determining the unit of a timestamp. These rules apply to the following API operations: /api/put
and api/query
. /api/put and is used to write data. /api/query is used to query data.
Timestamps can be measured in seconds or milliseconds. Time Series Database (TSDB) uses the following rules to determine the unit of a timestamp based on the numeric value:
If the value falls within the range of [4294968,4294967295], the unit is seconds. In this case, the date and time range is [1970-02-20 01:02:48, 2106-02-07 14:28:15].
If the value falls within the range of [4294967296,9999999999999], the unit is milliseconds. In this case, the date and time range is [1970-02-20 01:02:47.296, 2286-11-21 01:46:39.999].
If the value falls within the range of (-∞,4294968) or (9999999999999,+∞), the timestamp is invalid.
Description of values in data points
Values of the STRING data type can contain all characters and can be stored in the JSON format. The size of a string value cannot exceed 20 KB.
Tag description
When you write data in a time series, you can specify only a limited number of tag keys. The maximum number of tag keys varies based on the instance type of the TSDB instance, as listed in the following table.
The type of the instance. | Maximum number of tag keys in a single time series |
---|---|
mLarge | 16 |
Large | 16 |
3xLarge | 20 |
4xLarge | 20 |
6xLarge | 20 |
12xLarge | 20 |
24xLarge | 24 |
48xLarge | 24 |
96xLarge | 24 |
Sample requests
Request line: POST /api/put
Request line:
[
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":18,
"tags":{
"host":"web01",
"dc":"lga"
}
},
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":9,
"tags":{
"host":"web02",
"dc":"lga"
}
},
{
"metric":"sys.cpu.alter",
"timestamp":1346846400,
"value":"High CPU Load",
"tags":{
"host":"web03",
"dc":"lga"
}
},
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":true,
"tags":{
"host":"web04",
"dc":"lga"
}
}
]
Write modes and responses
TSDB supports four write modes. To use each of the modes, configure the request parameters based on the following instructions:
Simple mode
To use this mode, do not configure the parameters when you call the
api/put
operation. If data is written to TSDB as expected, the status code 204 is returned. If data fails to be written, only the corresponding error code and error message are returned.This mode is suitable for reporting monitoring data of general business.
Statistical mode
To use this mode, configure the
summary
parameter when you call theapi/put
operation. The success and failed parameters are returned, regardless of whether data is written to TSDB as expected. This helps you collect statistics of your business. The success parameter indicates the number of data points that were written. The failed parameter indicates the number of data points that failed to be written.Parameter
Type
Description
success
Integer
The number of data points that were written as expected.
failed
Integer
The number of data points that failed to be written.
Example:
{ "failed":0, "success": 20 }
NoticeIn statistical mode, the data points in an
api/put
request are all written as expected or all fail to be written. If a data write fails, thefailed
parameter indicates the number of data points specified in your request.The statistical mode is suitable for reporting monitoring data of general business that requires statistics on the reported data.
Detailed mode
The detailed mode is an extension of the statistical mode. To use this mode, configure the
details
parameter when you call theapi/put
operation. The success, failed, and errors parameters are returned regardless of whether data is written to TSDB as expected. The success parameter indicates the number of data points that were written. The failed parameter indicates the number of data points that failed to be written. The errors parameter indicates the direct cause of the write failure.Parameter
Type
Description
success
Integer
The number of data points that were written as expected.
failed
Integer
The number of data points that failed to be written.
errors
Array
The direct cause of the failure of the first data point that failed to be written. The value is an array that consists of the information about the data point and the failure cause.
Example:
{ "errors":[{ "datapoint":{ "metric":"sys.cpu.nice", "timestamp":1365465600, "value":"NaN", "tags":{ "host":"web01" } }, "error":"Unable to parse value to a number" }], "failed":1, "success":0 }
NoticeIn detailed mode, the data points in one request that calls the
api/put
operation are all written or all fail to be written. The value oferrors
contains only the information about the first data point that failed to be written and the direct cause of the failure. To view the number of data points that failed to be written, view the value of thefailed
parameter.This mode is suitable for reporting monitoring data of business that requires statistics on the reported data and fault location.
Fault-tolerant mode
To use this mode, configure the
ignoreErrors
parameter when you call theapi/put
operation. When you send a request to write a batch of data points to TSDB in fault-tolerant mode, the write failure of one data point has no impact on the writes of the other data points. This mode ensures that most data points can be written to TSDB when valid and invalid data points exist in the same batch. The data points that failed to be written are enumerated in the response. The response contains the same parameters as those returned when you configure thedetails
parameter in your request. However, theerrors
parameter contains the name of each data point that failed to be written and the failure cause. The data points that are not included in the value of the errors parameter were written to TSDB as expected.Parameter
Type
Description
success
Integer
The number of data points that were written as expected.
failed
Integer
The number of data points that failed to be written.
errors
Array
An array of each data point that failed to be written and the corresponding failure cause.
Example:
NoticeIn fault-tolerant mode, if not all data points in a batch failed to be written, the status code 200 is returned. If all data points in a batch failed to be written due to a critical error such as a failure of underlying storage, a status code other than 200 is returned. In fault-tolerant mode, the
failed
parameter indicates the number of data points failed to be written.This mode is suitable for reporting monitoring data of business that requires the integrity of the reported data and the fault rectification and rewrites of failed data points.