/api/uid/tsmeta

This endpoint enables searching, editing or deleting timeseries meta data information, that is meta data associated with a specific timeseries associated with a metric and one or more tag name/value pairs. Some fields are set by the TSD but others can be set by the user. When using the POST method, only the fields supplied with the request will be stored. Existing fields that are not included will be left alone. Using the PUT method will overwrite all user mutable fields with given values or defaults if a given field is not provided.

Please note that deleting a meta data entry will not delete the data points stored for the timeseries. Neither will it remove the UID assignments or associated UID meta objects.

Verbs

  • GET - Lookup one or more TS meta data
  • POST - Updates only the fields provided
  • PUT - Overwrites all user configurable meta data fields
  • DELETE - Deletes the TS meta data

GET Requests

A GET request can lookup the TS meta objects for one or more time series if they exist in the storage system. Two types of queries are supported:

  • tsuid - A single hexadecimal TSUID may be supplied and a meta data object will be returned if located. The results will include a single object.
  • metric - (Version 2.1) Similar to a data point query, you can supply a metric and one or more tag pairs. Any TS meta data matching the query will be returned. The results will be an array of one or more objects. Only one metric query may be supplied per call and wild cards or grouping operators are not supported.

Example TSUID GET Request

http://localhost:4242/api/uid/tsmeta?tsuid=00002A000001000001

Example Metric GET Request

http://localhost:4242/api/uid/tsmeta?m=sys.cpu.nice&dc=lga

POST/PUT Requests

By default, you may only write data to a TS meta object if it already exists. TS meta data is created via the meta sync CLI command or in real-time as data points are written. If you attempt to write data to the tsmeta endpoint for a TSUID that does not exist, an error will be returned and no data will be saved.

Fields that can be supplied with a request include:

Name Data Type Required Description Default QS RW Example
tsuid String Required A hexadecimal representation of the timeseries UID   tsuid RO 00002A000001000001
description String Optional A brief description of what the UID represents   description RW System processor time
displayName String Optional A short name that can be displayed in GUIs instead of the default name   display_name RW System CPU Time
notes String Optional Detailed notes about what the UID represents   notes RW Details
custom Map Optional A key/value map to store custom fields and values null   RW See Below
units String Optional Units reflective of the data stored in the timeseries, may be used in GUIs or calculations   units RW Mbps
dataType String Optional The kind of data stored in the timeseries such as counter, gauge, absolute, etc. These may be defined later but they should be similar to Data Source Types in an RRD   data_type RW counter
retention Integer Optional The number of days of data points to retain for the given timeseries. Not Implemented. When set to 0, the default, data is retained indefinitely. 0 retention RW 365
max Float Optional An optional maximum value for this timeseries that may be used in calculations such as percent of maximum. If the default of NaN is present, the value is ignored. NaN max RW 1024
min Float Optional An optional minimum value for this timeseries that may be used in calculations such as percent of minimum. If the default of NaN is present, the value is ignored. NaN min RW 0

Note

Custom fields cannot be passed via query string. You must use the POST or PUT verbs.

Warning

If your request uses PUT, any fields that you do not supply with the request will be overwritten with their default values. For example, the description field will be set to an emtpy string and the custom field will be reset to null.

With OpenTSDB 2.1 you may supply a metric style query and, if UIDs exist for the given metric and tags, a new TS meta object will be stored. Data may be supplied via POST for the fields above as per a normal request, however the tsuid field must be left empty. Additionally two query string parameters must be supplied:

  • m - A metric and tags similar to a GET request or data point query
  • create - A flag with a value of true

For example:

http://localhost:4242/api/uid/tsmeta?display_name=Testing&m=sys.cpu.nice{host=web01,dc=lga}&create=true&method_override=post

If a TS meta object already exists in storage for the given metric and tags, the fields will be updated or overwritten.

Example POST or PUT Request

Query String:

http://localhost:4242/api/uid/tsmeta?tsuid=00002A000001000001&method_override=post&display_name=System%20CPU%20Time

JSON Content:

{
    "tsuid":"00002A000001000001",
    "displayName":"System CPU Time for Webserver 01",
    "custom": {
        "owner": "Jane Doe",
        "department": "Operations",
        "assetTag": "12345"
    }
}

Example DELETE Request

Query String:

http://localhost:4242/api/uid/tsmeta?tsuid=00002A000001000001&method_override=delete

JSON Content:

{
    "tsuid":"00002A000001000001"
}

Response

A successful response to a GET, POST or PUT request will return the full TS meta data object with any given changes. Successful DELETE calls will return with a 204 status code and no body content. When modifying data, if no changes were present, i.e. the call did not provide any data to store, the resposne will be a 304 without any body content. If the requested TSUID did not exist in the system, a 404 will be returned with an error message. If invalid data was supplied an error will be returned.

All Request fields will be present in the response in addition to others:

Name Data Type Description Example
metric UIDMeta A UID meta data object representing information about the UID See Below
tags Array of UIDMeta A list of tag name / tag value UID meta data objects associated with the timeseries. The tagk UID will be first followed by it's corresponding tagv object. See Below
created Integer A Unix epoch timestamp, in seconds, when the timeseries was first recorded in the system. Note that if the TSD was upgraded or meta data recently enabled, this value may not be accurate. Run the uid utility to synchronize meta data. 1350425579
lastReceived Integer A Unix epoch timestamp, in seconds, when a data point was last recieved. This is only updated on TSDs where meta data is enabled and it is not updated for every data point so there may be some lag. 1350425579
totalDatapoints Integer The total number of data points recorded for the timeseries. NOTE: This may not be accurate unless you have enabled metadata tracking since creating the TSDB tables. 3242322

Example Response

{
    "tsuid": "00002A000001000001",
    "metric": {
        "uid": "00002A",
        "type": "METRIC",
        "name": "sys.cpu.0",
        "description": "System CPU Time",
        "notes": "",
        "created": 1350425579,
        "custom": null,
        "displayName": ""
    },
    "tags": [
        {
            "uid": "000001",
            "type": "TAGK",
            "name": "host",
            "description": "Server Hostname",
            "notes": "",
            "created": 1350425579,
            "custom": null,
            "displayName": "Hostname"
        },
        {
            "uid": "000001",
            "type": "TAGV",
            "name": "web01.mysite.com",
            "description": "Website hosting server",
            "notes": "",
            "created": 1350425579,
            "custom": null,
            "displayName": "Web Server 01"
        }
    ],
    "description": "Measures CPU activity",
    "notes": "",
    "created": 1350425579,
    "units": "",
    "retention": 0,
    "max": "NaN",
    "min": "NaN",
    "custom": {
        "owner": "Jane Doe",
        "department": "Operations",
        "assetTag": "12345"
    },
    "displayName": "",
    "dataType": "absolute",
    "lastReceived": 1350425590,
    "totalDatapoints", 12532
}