/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 its 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
}