/api/uid/uidmeta

This endpoint enables editing or deleting UID meta data information, that is meta data associated with metrics, tag names and tag values. 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.

Note

Deleting a meta data entry will not delete the UID assignment nor will it delete any data points or associated timeseries information. Deletion only removes the specified meta data object, not the actual value. If you query for the same UID, you'll see the default meta data with empty fields.

Verbs

  • GET - Query string only
  • POST - Updates only the fields provided
  • PUT - Overwrites all user configurable meta data fields
  • DELETE - Deletes the UID meta data

Requests

Fields that can be supplied with a request include:

Name Data Type Required Description Default QS RW Example
uid String Required A hexadecimal representation of the UID uid RO 00002A
type String Required The type of UID, must be metric, tagk or tagv type RO metric
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

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.

Example GET Request

http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric

Example POST or PUT Request

Query String:

http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric&method=post&display_name=System%20CPU%20Time

JSON Content:

{
  "uid":"00002A",
  "type":"metric",
  "displayName":"System CPU Time",
  "custom": {
    "owner": "Jane Doe",
    "department": "Operations",
    "assetTag": "12345"
  }
}

Example DELETE Request

Query String:

http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric&method=delete

JSON Content:

{
  "uid":"00002A",
  "type":"metric"
}

Response

A successful response to a GET, POST or PUT request will return the full UID 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 response will be a 304 without any body content. If the requested UID 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 a couple of others:

Name Data Type Description Example
name String The name of the UID as given when the data point was stored or the UID assigned sys.cpu.0
created Integer A Unix epoch timestamp in seconds when the UID was first created. If the meta data was not stored when the UID was assigned, this value may be 0. 1350425579

Example Response

{
  "uid": "00002A",
  "type": "TAGV",
  "name": "web01.mysite.com",
  "description": "Website hosting server",
  "notes": "This server needs a new boot disk",
  "created": 1350425579,
  "custom": {
    "owner": "Jane Doe",
    "department": "Operations",
    "assetTag": "12345"
  },
  "displayName": "Webserver 01"
}

© 2010–2016 The OpenTSDB Authors
Licensed under the GNU LGPLv2.1+ and GPLv3+ licenses.
http://opentsdb.net/docs/build/html/api_http/uid/uidmeta.html