openTSDB详解之api/uid/tsmeta

openTSDB详解之api/uid/tsmeta【待完善】

api/uid/tsmeta

这个端点可以让你查询，编辑或者删除时间序列元数据信息，这个元数据信息是和具体的时间序列的metric，tag name，tag value相关联的。一些字段被TSD设置，但是一些却是可以有用户设置的。【译者注：这些特性和uidmeta很相像】。当使用POST方法时，仅仅请求中的字段将会被存储。存在的字段不会被包含在内，将会被单独留下。使用PUT方法将会覆写用户所有的可变字段，使用给定值，或者默认值，如果一个给出的字段没有被提供。
请注意：删除一个meta data 项不会删除时间序列的数据点。这个操作既不会移除UID 分配，同时也不会移除相关UID meta对象。

1. Verbs

• GET 查看一或多个TS meta data
• POST 仅仅更新提供的字段
• PUT 覆写所有用户可配置的meta data字段
• DELETE 删除TS meta data

2. GET Requests

一个GET请求能够查找TS meta对象，为一个或者多个时间序列，如果它们存在与存储系统中。两种类型的查询是被支持的：

• tsuid 单个十六进制的TSUID可能被应用，并且一个meta data 对象将会被返回。结果将会包涵单个对象。
• metric 与数据点查询相似，你能应用一个metric并且已到多个tag pair。任何TS meta data匹配于查询的都将被返回。结果将会是一或多个对象的数组。仅仅metric 查询被应用于一次调用，并且通配符或者分组符是不被支持的。

2.1 Example TSUI GET Request

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

2.2 Example Metric GET Request

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

3. POST/PUT Requests

默认情况下，你能仅仅写数据到一个TS meta 对象，如果该对象已经存在的话。TS meta data被创建通过meta sync CLI命令或者实时的当数据点被写入的时候。如果你尝试写数据到tsmeta endpoint，为一个不存在的TSUID时，一个错误将会被返回，并且不会存储任何的数据。
一个请求中可以包含的字段有：

3.1 Note

自定义的字段不能通过查询字符串传递。你必须使用POST或者PUT方法

3.2 warning

如果你使用PUT方式请求，你没有应用的任何字段将会被覆写成他们本来的默认值。例如：description字段将会被设置成一个空字符串，同时custom字段将会被重置成null。
在opentSDB 2.1中，你可能应用一个metric 样式的查询，如果UID存在，对于给定的metric以及tags，一个新的TS meta对象将会被存储。数据可能被应用通过POST针对上述字段，作为一个正常的请求，然后tsuid字段必须是留空。另外，两个查询字符串必须被应用：

• m - 与GET请求或者数据点查询相同，m代表A metric 以及tags
• create - 一个值为true的标签
  例如：
  http://localhost:4242/api/uid/tsmeta?display_name=Testing&m=sys.cpu.nice{host=web01,dc=lga}&create=true&method_override=post
  如果一个TS meta对象已经存在，对于给出的metric和tags，字段将会被更新或者覆写。

4.1 Example POST or PUT Request

查询字符串
http://localhost:4242/api/uid/tsmeta?tsuid=00002A000001000001&method_override=post&display_name=System%20CPU%20Time
Json 内容

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

4.2 Example DELETE Request

查询字符串
http://localhost:4242/api/uid/tsmeta?tsuid=00002A000001000001&method_override=delete

{
    "tsuid":"00002A000001000001"
}

5. Response

一个成功的GET,POST,PUT请求的响应将会返回完整的TS meta 数据对象带有任何给定的变化。成功的DELETE调用将会返回一个204 状态码，并且没有任何内容。当修改数据时，如果任何的状态是存在的。例如：调用没有提供任何存储的数据，响应将会是304，不带有任何的内容。如果请求的TSUID不存在与系统中，一个404将会被返回，同时伴有一个错误消息。如果无效的数据被应用，一个错误将会被返回。
除了其他字段之外，所有请求字段都将显示在响应中：

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

6.实战案例

笔者在自己的openTSDB测试集群测试http://192.168.211.4:4399/api/uid/tsmeta?m=test_meta地址，得到数据如下：

[
  {
    "tsuid": "000005000003000005",
    "metric": {
      "uid": "000005",
      "type": "METRIC",
      "name": "test_meta",
      "description": "",
      "notes": "",
      "created": 0,
      "custom": null,
      "displayName": ""
    },
    "tags": [
      {
        "uid": "000003",
        "type": "TAGK",
        "name": "accessNumber",
        "description": "",
        "notes": "",
        "created": 0,
        "custom": null,
        "displayName": ""
      },
      {
        "uid": "000005",
        "type": "TAGV",
        "name": "cs",
        "description": "",
        "notes": "",
        "created": 0,
        "custom": null,
        "displayName": ""
      }
    ],
    "description": "",
    "notes": "",
    "created": 1541500656,
    "units": "",
    "retention": 0,
    "max": "NaN",
    "min": "NaN",
    "displayName": "",
    "dataType": "",
    "lastReceived": 1541502954,
    "totalDatapoints": 224
  },
  {
    "tsuid": "000005000003000008",
    "metric": {
      "uid": "000005",
      "type": "METRIC",
      "name": "test_meta",
      "description": "",
      "notes": "",
      "created": 0,
      "custom": null,
      "displayName": ""
    },
    "tags": [
      {
        "uid": "000003",
        "type": "TAGK",
        "name": "accessNumber",
        "description": "",
        "notes": "",
        "created": 0,
        "custom": null,
        "displayName": ""
      },
      {
        "uid": "000008",
        "type": "TAGV",
        "name": "firminal",
        "description": "",
        "notes": "",
        "created": 0,
        "custom": null,
        "displayName": ""
      }
    ],
    "description": "",
    "notes": "",
    "created": 1541500656,
    "units": "",
    "retention": 0,
    "max": "NaN",
    "min": "NaN",
    "displayName": "",
    "dataType": "",
    "lastReceived": 1541502955,
    "totalDatapoints": 224
  }
]