Function Description

If Time To Live (TTL) of the OpenTSDB database is set for a metric, the system periodically deletes the data whose data point timestamp is earlier than the time calculated by the formula "Current system time – TTL".

The unit of TTL is hour, and data is cleared by hour. For example, if the current system time is 19:30 and the TTL of a metric is set to 2, the data before 17:00 will be cleared rather than the data before 17:30.

• If the TTL of a metric is not set, the global TTL is used. If the global TTL is not set, the data will not be cleared. If the TTL of a metric is set, the metric's own TTL is used.
• If the TTL of a metric is 0, TTL is not set for the metric and data will not be cleared.

URI

• URI format
  • Set TTL.

    PUT {OpenTSDB URL}/api/ttl

  • Query TTL.

    POST {OpenTSDB URL}/api/ttl

  • Delete TTL.

    DELETE {OpenTSDB URL}/api/ttl

Request

• Sample request: Setting TTL

  {
  	"global":36,
  	"ttl":{
  		"sys.cpu.nice":24,
  		"cpu.system":12
  	}
  }

  The following table describes the parameters. At least one of the global and ttl parameters must be specified.

  Table 1 Parameters

  Parameter	Type	Mandatory	Description
  global	Integer	No	Global TTL. The unit is hour. It indicates that the validity period of the metric data whose TTL is not configured will be set to the value of global. If global is set to 0, the global TTL is invalid.
  ttl	Map	No	List of metrics for which the TTL is set. A key-value format is used. A key is a metric name, and a value is the TTL (unit: hour). For example: "sys.cpu.nice": 24 indicates that the TTL of the sys.cpu.nice metric is 24 hours.

• Sample request: Querying TTL

  Querying the TTL of the specified metric:

  {
           "metrics":["sys.cpu.nice", "cpu.system"]
  }

  Querying all metrics for which the TTL is set and the global TTL

  {
            "all":true
  }

  The following table describes the parameters. At least one of the following parameters must be specified. If the metrics parameter is specified, at least one metric must be specified.

  Table 2 Parameters

  Parameter	Type	Mandatory	Description
  global	Boolean	No	Whether to query the global TTL. The value true indicates that the value of the global parameter is queried.
  all	Boolean	No	Whether to query the TTL of all metrics. If all is set to true, the TTL of all metrics and the global TTL are returned. The metrics parameter is invalid.
  metrics	String/Array	No	Indicates the name of the metric to be queried. If one metric is set, the type is String. If multiple metrics are set, the type is Array.

• Sample request: Deleting TTL

  {
  	"global":true,
          "metrics":["sys.cpu.nice", "cpu.system"]
  }

  The following table describes the parameters. At least one metric must be specified in metrics or global is set to true.

  Table 3 Parameters

  Parameter	Type	Mandatory	Description
  global	Integer, Boolean	No	Whether to delete the global TTL. The value true indicates that the value of the global parameter is deleted.
  all	Boolean	No	Whether to delete all TTL values. The value true indicates that all TTL values are deleted. In this case, the metrics parameter is invalid.
  metrics	String/Array	No	Names of the metrics to be deleted. If one metric is set, the type is String. If multiple metrics are set, the type is Array.

Response

• Sample response: Querying TTL

  {
      "global": 36,
      "ttl": {
          "sys.cpu.nice": 24,
          "cpu.system": 12
      }
  }

  Table 4 Response parameters

  Parameter	Type	Description
  global	Integer	Global TTL. The unit is hour. It indicates that the validity period of the metric data whose TTL is not configured will be set to the value of global. If global is set to 0, the global TTL is invalid.
  ttl	Map	List of metrics for which the TTL is set. A key-value format is used. A key is a metric name, and a value is the TTL (unit: hour). For example: "sys.cpu.nice": 24 indicates that the TTL of the sys.cpu.nice metric is 24 hours.

• Sample Response: Setting or deleting TTL

  No content is returned in the body.

Status Code

For details about status codes, see Response Code.