Function Description

You can write multiple pieces of data to OpenTSDB with one request. Multiple pieces of data can be independent of each other. Each piece of data can be independently processed, and one error pieces of data will not affect other data. However, if a request contains a large number of data points, the API may take a long time to respond.

URI

• URI format
  1. Write data.

     POST {OpenTSDB URL}/api/put

  2. Write data and return summary information.

     POST {OpenTSDB URL}/api/put?summary

  3. Write data and return details.

     POST {OpenTSDB URL}/api/put?details

     

     If both the summary and details flags exist in the query character string, the API returns the detailed information.

  4. Write data and wait for the data to be written to disks.

     POST {OpenTSDB URL}/api/put?sync

     

     It is strongly recommended that the sync parameter be used. Otherwise, the API returns a response before data is successfully written, which may cause data loss.

  5. Write data, wait for the data to be written to disks, and set a timeout interval. When a timeout occurs, the number of successful and failed data points will be returned if the details flag is used.

     POST {OpenTSDB URL}/api/put?sync&sync_timeout=60000

Request

• Sample request: Writing a single data point

  {
      "metric": "sys.cpu.nice",
      "timestamp": 1346846400,
      "value": 18,
      "tags": {
         "host": "web01",
         "dc": "lga"
      }
  }

• Sample request: Writing multiple data points

  [
      {
          "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"
          }
      }
  ]

• Parameter description

  Table 1 Request parameters

  Attribute	Type	Mandatory	Description	Restrictions
  metric	String	Yes	Metric name	Contains only uppercase and lowercase letters, digits, hyphens (-), underscores (_), periods (.), and slashes (/). Cannot contain spaces or other characters. The value is case-sensitive.
  timestamp	Integer	Yes	Timestamp. The unit is second.	Unix/POSIX Epoch timestamp (unit: second). The value is the seconds starting from 00:00:00 UTC on January 1, 1970. NOTE: You are advised to set the timestamp to a value between 4334400 seconds and 4291718400 seconds, that is, from 1970/02/20 12:00:00 to 2106/01/01 00:00:00. Must be an integer. Contains a maximum of 13 digits.
  value	Integer,Long,Double,Boolean	Yes	Data value	Integer, single-precision (Float) floating point number, double-precision (Double) floating point number, or Boolean
  tags	Map	Yes	Key-value pair of Tagk and Tagv	Contains only uppercase and lowercase letters, digits, hyphens (-), underscores (_), periods (.), and slashes (/). Cannot contain spaces or other characters. The value is case-sensitive. At least one key pair and at most eight Tagk and Tagv key-value pairs

Response

• Sample response: summary

  {
      "failed": 1,
      "success": 0
  }

  Sample response: details

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

• Parameter description

  Table 2 Attributes of the returned information

  Parameter	Type	Description
  success	Integer	Number of data points that are successfully written
  failed	Integer	Number of data points that fail to be written
  errors	Array	The value and causes of the data point that fails to be written. This parameter is valid only in details mode.

Status Code

For details about status codes, see Response Code.