/api/uid/tsmeta

    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.

    • 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

    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.

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

    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:

    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:

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

    Query String:

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

    JSON Content:

    Query String:

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

    JSON Content:

    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 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

    3242322

    1. {
    2.     "tsuid": "00002A000001000001",
    3.     "metric": {
    4.         "type": "METRIC",
    5.         "name": "sys.cpu.0",
    6.         "description": "System CPU Time",
    7.         "notes": "",
    8.         "created": 1350425579,
    9.         "custom": null,
    10.         "displayName": ""
    11.     },
    12.     "tags": [
    13.         {
    14.             "uid": "000001",
    15.             "type": "TAGK",
    16.             "name": "host",
    17.             "description": "Server Hostname",
    18.             "notes": "",
    19.             "created": 1350425579,
    20.             "custom": null,
    21.             "displayName": "Hostname"
    22.         },
    23.         {
    24.             "uid": "000001",
    26.             "name": "web01.mysite.com",
    27.             "notes": "",
    28.             "created": 1350425579,
    29.             "custom": null,
    30.             "displayName": "Web Server 01"
    31.         }
    32.     ],
    33.     "description": "Measures CPU activity",
    34.     "notes": "",
    35.     "created": 1350425579,
    36.     "units": "",
    37.     "retention": 0,
    38.     "max": "NaN",
    39.     "min": "NaN",
    40.     "custom": {
    41.         "owner": "Jane Doe",
    42.         "department": "Operations",
    43.         "assetTag": "12345"
    44.     },
    45.     "displayName": "",
    46.     "dataType": "absolute",
    47.     "lastReceived": 1350425590,
    48.     "totalDatapoints", 12532
    49. }