openTSDB API 接口使用说明


接口列表:
1./s
返回的是静态文件的内容:(目前仅支持:just HTML, JSON, Javascript and PNG. )
例子:
http://localhost:4242/s/queryui.nocache.js


返回结果:
function queryui(){var T='',Bb='" for "gwt:onLoadErrorFn"',zb='" for "gwt:onPropertyErrorFn"',mb='"><\/script>',bb='#',Zb='.cache.html',db='/',pb='//',Tb='45CED05058B96FCCC06AD4ADCAACF7C6',Ub='46w[Gb]=function(){var b=navigator.userAgent.toLowerCase();var c=function(a){return .........
queryui();


2./api/aggregators
此接口仅列出时间序列查询中使用的已实现的聚合函数的名称。


请求类型:
GET
POST


此接口不需要任何查询的参数字符串或者方法体。


例子:
http://localhost:4242/api/aggregators




返回结果:
[
    "mult",
    "p90",
    "zimsum",
    "mimmax",
    "sum",
    "p50",
    "none",
    "p95",
    "ep99r7",
    "p75",
    "p99",
    "ep99r3",
    "ep95r7",
    "min",
    "avg",
    "ep75r7",
    "dev",
    "ep95r3",
    "ep75r3",
    "ep50r7",
    "ep90r7",
    "mimmin",
    "p999",
    "ep50r3",
    "ep90r3",
    "ep999r7",
    "last",
    "max",
    "count",
    "ep999r3",
    "first"
]


返回结果是可以使用的聚合函数的名字


3./api/annotation


这些接口提供了添加,编辑或删除存储在OpenTSDB后端的注释的方法。 注释是非常基本的对象,用于在某个点记录任意事件的注释,
可选地与时间序列关联。 注释并不意味着被用作跟踪或基于事件的系统,而是通过在图表上或通过API查询调用显示通知来提供指向这些系统的链接。


创建,修改或删除注释时,所有更改将传播到搜索插件(如果已配置)。


/api/annotation/bulk
默认/注释接口一次处理一个符号。 / annotation / bulk端点允许一次添加或更新多个注释。


请求类型:
GET - Retrieve a single 注释
POST - Create or modify an 注释
PUT - Create or replace an 注释
DELETE - Delete an 注释




所有注释都由 startTime 字段和可选的 tsuid 字段标识。 每个字符可以是全局的,意味着它与所有的时间序列相关联,
或者它可以是本地的,意味着它与特定的 tsuid 相关联。 如果 tsuid 没有提供或者有一个空值,注释被认为是一个全局注释。


【注】:自定义字段不能通过查询字符串传递。 您必须使用POST或PUT动词。
   如果您的请求使用PUT,那么您不提供请求的任何字段将被覆盖其默认值。 
   例如,说明字段将被设置为空字符串,自定义字段将被重置为空。


例子:
http://localhost:4242/api/annotation?start_time=1518078239427
返回:


{
    "error": {
        "code": 404,
        "message": "Unable to locate annotation in storage",
        "trace": "net.opentsdb.tsd.BadRequestException: Unable to locate annotation in storage\n\tat net.opentsdb.tsd.AnnotationRpc.fetchSingleAnnotation(AnnotationRpc.java:351) ~[tsdb-2.3.0.jar:]\n\tat net.opentsdb.tsd.AnnotationRpc.execute(AnnotationRpc.java:71) ~[tsdb-2.3.0.jar:]\n\tat net.opentsdb.tsd.RpcHandler.handleHttpQuery(RpcHandler.java:283) [tsdb-2.3.0.jar:]\n\tat net.opentsdb.tsd.RpcHandler.messageReceived(RpcHandler.l.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617) [na:1.8.0_71]\n\tat java.lang.Thread.run(Thread.java:745) [na:1.8.0_71]\n"
    }
}


返回说明:


对GET,POST或PUT请求的成功响应将返回具有所请求更改的完整对象。 成功的DELETE调用将返回一个204状态代码,并且没有主体内容。 当修改数据时,如果没有改变,即该调用没有提供任何数据来存储,则该响应将是没有任何主体内容的304。 如果所请求的注释在系统中不存在,则会返回一个404错误消息。 如果提供的数据无效,则会返回400错误。






4./api/config
该端点返回有关TSD运行配置的信息。 它是只读的,不能用于设置配置选项。


例子:
http://localhost:4242/api/config


返回结果:


{
    "tsd.core.auto_create_metrics": "true",
    "tsd.core.auto_create_tagks": "true",
    "tsd.core.auto_create_tagvs": "true",
    "tsd.core.connections.limit": "0",
    .....
    "tsd.storage.hbase.scanner.maxNumRows": "128",
    "tsd.storage.hbase.tree_table": "tsdb-tree",
    "tsd.storage.hbase.uid_table": "tsdb-uid",
    "tsd.storage.hbase.zk_basedir": "/hbase",
    "tsd.storage.hbase.zk_quorum": "10.6.26.218:2181",
    "tsd.storage.repair_appends": "false",
    "tsd.timeseriesfilter.enable": "false",
    "tsd.uidfilter.enable": "false"
}


返回结果说明:


返回的是配置属性名和值的Map


5./api/dropcaches


此接口清除在OpenTSDB中缓存的内存数据。 
这包括所有UID来命名和命名为度量标准名称和标签值的UID映射。


例子:


http://localhost:4242/api/dropcaches


返回结果:


{
    "message": "Caches dropped",
    "status": "200"
}


6./api/put
此接口允许通过HTTP将数据存储在OpenTSDB中,作为Telnet接口的替代方案。 
Put请求只能通过与POST方法关联的内容来执行。 内容的格式取决于选择的序列化程序。 
不过,下面列出了一些常见的参数和响应。


为了节省带宽,put API允许客户端在一个请求中存储多个数据点。 数据点不必以任何方式相关。
每个数据点被单独处理,并且一个数据的错误不会影响良好数据的存储。 这意味着如果您的请求有100个数据点,
其中有1个数据点有错误,则99个数据点仍将被写入,其中一个将被拒绝。 
有关确定未存储什么数据点的详细信息,请参阅下面的响应部分。




如果发生错误:


如果您提供的请求的内容不能被解析,这样的JSON内容缺少一个引号或花括号,那么所有的数据点将被丢弃。 该API将返回错误,并提供有关出错的详细信息。


【注1:】
虽然API确实支持每个请求多个数据点,但是直到处理完每个API之后,API才会返回。 这意味着度量和标签名称/值必须验证,解析的值和数据排队存储。 如果你的put请求有大量数据点,那么API可能需要很长时间才能响应,特别是如果OpenTSDB必须将UID分配给标记名或值。 
因此,限制每个请求的最大数据点数是一个好主意。 每个请求50个是一个很好的起点。


另一个建议是在你的HTTP客户端上启用保持连接,这样每次你输入数据就可以重新使用到服务器的连接。


【注2:】


对put使用HTTP时,如果您的HTTP客户端自动将较大的请求分解为较小的数据包,则可能需要启用对块的支持。 
例如,CURL将分解大于2或3个数据点的消息,默认情况下,OpenTSDB禁用块支持。 
通过在配置文件中将tsd.http.request.enable_chunked设置为true来启用它。


【注3:】
如果tsd.mode设置为ro,则/ api / put端点将不可用,所有调用将返回404错误。


请求类型:
POST


【补充:】




例子:
http://localhost:4242/api/put


参数体:
单组:
{
    "metric": "sys.cpu.nice",
    "timestamp": 1346846400,
    "value": 18,
    "tags": {
       "host": "web01",
       "dc": "lga"
    }
}


多组:


[
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": 18,
        "tags": {
           "host": "web01",
           "dc": "lga"
        }
    },
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": 9,
        "tags": {
           "host": "web02",
           "dc": "lga"
        }
    }
]






返回说明:


默认情况下,如果所有数据点都成功存储,put端点将响应一个204的HTTP状态代码,并且没有内容。 
如果一个或多个数据点发生错误,则API将返回一个400,并在内容中显示错误消息。


出于调试的目的,您可以要求响应包括成功存储多少个数据点和失败的摘要,或者获取有关哪些数据点无法存储的详细信息以及为什么可以修复您的客户端代码。 此外,数据点的错误将记录在TSD的日志文件中,因此您可以在这里查找问题。


提供摘要或详细回复的字段包括:


Name    Data Type        Description
success    Integer          The number of data points that were queued successfully for storage
failed    Integer          The number of data points that could not be queued for storage
errors    Array          A list of data points that failed be queued and why. Present in the details response only.




返回样例:




{
    "failed": 1,
    "success": 0
}


细节信息:


{
    "errors": [
        {
            "datapoint": {
                "metric": "sys.cpu.nice",
                "timestamp": 1365465600,
                "value": "NaN",
                "tags": {
                    "host": "web01"
                }
            },
            "error": "Unable to parse value to a number"
        }
    ],
    "failed": 1,
    "success": 0
}




7./api/rollup
这个接口允许通过 HTTP 在 OpenTSDB 上存储汇总和 / 或预先汇总的数据。 
有关汇总和预集合的详细信息,请参阅用户指南:汇总和预集合。


另请参阅/api/put文档,了解与/api/rollup端点共享的注释和常用参数。 
本页列出了两者之间的差异。




请求类型:
POST


汇总和预汇总值是put对象的扩展,具有三个附加字段。 为了完整性,所有字段列在下面:








参数体:


单组数据:


{
    "metric": "sys.cpu.nice",
    "timestamp": 1346846400,
    "value": 18,
    "tags": {
       "host": "web01",
       "dc": "lga"
    },
    "interval": "1h",
    "aggregator": "SUM",
    "groupByAggregator": "SUM"
}


多组数据:


[
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": 18,
        "tags": {
           "host": "web01",
           "dc": "lga"
        },
        "interval": "1h",
        "aggregator": "SUM",
        "groupByAggregator": "SUM"
    },
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": 9,
        "tags": {
           "host": "web02",
           "dc": "lga"
        },
        "interval": "1h",
        "aggregator": "SUM",
        "groupByAggregator": "SUM"
    }
]


返回结果与/put/接口一致




8./api/histogram





9./api/query


可能是API中最有用的接口,/api/query 使得能够以选择的串行器所确定的各种格式从存储系统中提取数据。 
查询可以通过1.0查询字符串格式或正文内容提交。


多个查询接口:


/api/query/exp


http://opentsdb.net/docs/build/html/api_http/query/exp.html


/api/query/gexp


http://opentsdb.net/docs/build/html/api_http/query/gexp.html


/api/query/last


http://opentsdb.net/docs/build/html/api_http/query/last.html


请求类型:
GET
POST
DELETE


子查询


OpenTSDB查询至少需要一个子查询,这是一种选择哪个时间序列应该包含在结果集中的方法。 有两种类型:


度量标准查询 - 提供度量标准的完整名称以及可选的标签列表。 
这是针对将多个时间序列合并成一个结果而优化的。
TSUID Query(TSUID查询) - 共享一个公用指标的一个或多个TSUID的列表。 
这适用于获取不需要聚合的个别时间序列。
查询可以包含多个子查询以及这两种类型的混合。 
在通过内容主体提交查询时,如果提供了TSUID列表,则该特定子查询的度量标签和标签将被忽略。
每个子查询可以检索单个或一组时间序列数据,对每个集合执行聚合或分组计算。 每个子查询的字段包括:


细节参考:
http://opentsdb.net/docs/build/html/api_http/query/index.html


10./api/search
这个接口提供了一个搜索OpenTSDB元数据的基本手段。 启用时可以针对tsdb-meta表执行查找。 
可选地,可以安装搜索插件来从外部搜索索引服务(例如弹性搜索)发送和检索信息。 
由每个搜索插件来实现此端点的各个部分,并以一致的格式返回数据。 搜索和返回的对象类型取决于所选的端点。


/api/search/lookup
/api/search/tsmeta - TSMETA Response
/api/search/tsmeta_summary - TSMETA_SUMMARY Response
/api/search/tsuids - TSUIDS Response
/api/search/uidmeta - UIDMETA Response
/api/search/annotation - Annotation Response


请求方式:


GET
POST


支持参数:




Name     Data Type     Required   Description Default                       QS      RW        Example
query     String         Optional      The string based query to pass to the search engine. This will be parsed by the engine or plugin to perform the actual search. Allowable values depends on the plugin. Ignored for lookups. query name:sys.cpu.*


limit     Integer Optional Limits the number of results returned per query so as not to override the TSD or search engine. Allowable values depends on the plugin. Ignored for lookups. 25       limit 100


startIndex Integer Optional Used in combination with the limit value to page through results. Allowable values depends on the plugin. Ignored for lookups. 0 start_index 42


metric String Optional The name of a metric or a wildcard for lookup queries * metric tsd.hbase.rpcs


tags Array Optional One or more key/value objects with tag names and/or tag values for lookup queries. See /api/search/lookup tags




例子:


http://localhost:4242/api/search/tsmeta?query=name:*&limit=3&start_index=0


POST参数体:


{
    "query": "name:*",
    "limit": 4,
    "startIndex": 5
}


返回参考:
http://opentsdb.net/docs/build/html/api_http/search/index.html  后半部分








10./api/serializers


该接口列出了正在运行的TSD加载的序列化程序插件。 给出的信息包括名称,实现的方法,内容类型和方法。


请求方法:
POST
GET


只读操作,没有参数体


返回样例:
返回系统数据


[
    {
        "formatters": [
            "SuggestV1",
            "SerializersV1",
            "ErrorV1",
            "ErrorV1",
            "NotFoundV1"
        ],
        "serializer": "json",
        "parsers": [
            "SuggestV1"
        ],
        "class": "net.opentsdb.tsd.HttpJsonSerializer",
        "response_content_type": "application/json; charset=UTF-8",
        "request_content_type": "application/json"
    }
]


11./api/stats




此端点提供正在运行的TSD的统计信息列表。 子端点返回有关其他TSD组件(如JVM,线程状态或存储客户端)的详细信息。 
所有统计数据都是只读的。
做状态统计


/api/stats/jvm
参考:
http://opentsdb.net/docs/build/html/api_http/stats/jvm.html


/api/stats/query
参考:
http://opentsdb.net/docs/build/html/api_http/stats/query.html


/api/stats/region_clients
参考:
http://opentsdb.net/docs/build/html/api_http/stats/region_clients.html


/api/stats/threads
参考:
http://opentsdb.net/docs/build/html/api_http/stats/threads.html




请求方式:
GET
POST


请求参数体:空


样例:


http://localhost:4242/api/stats


返回样例:


[
  {
      "metric": "tsd.connectionmgr.connections",
      "timestamp": 1369350222,
      "value": "1",
      "tags": {
          "host": "wtdb-1-4"
      }
  },
  {
      "metric": "tsd.connectionmgr.exceptions",
      "timestamp": 1369350222,
      "value": "0",
      "tags": {
          "host": "wtdb-1-4"
      }
  },
  {
      "metric": "tsd.rpc.received",
      "timestamp": 1369350222,
      "value": "0",
      "tags": {
          "host": "wtdb-1-4",
          "type": "telnet"
      }
  }
]




12./api/suggest
该接口提供了一种实现“自动完成”调用的方法,当用户在GUI中输入请求时,可以重复访问该调用。 
它不提供全文搜索或通配符,而只是将查询中传递的整个字符串与存储数据的第一个字符进行匹配。
例如,传递类型= metrics&q = sys的查询将返回系统中以sys开头的前25个度量标准。 
匹配区分大小写,所以sys不会匹配System.CPU。 结果按字母顺序排序。




请求方式:
GET
POST




样例:


http://localhost:4242/api/suggest?type=metrics&q=sys&max=10




参数体:


{
  "type":"metrics",
  "q":"sys",
  "max":10
}


返回值说明:
返回是与查询匹配的给定类型的字符串数组。 如果没有发现匹配查询,则返回一个空数组。


[
  "sys.cpu.0.nice",
  "sys.cpu.0.system",
  "sys.cpu.0.user",
  "sys.cpu.1.nice",
  "sys.cpu.1.system",
  "sys.cpu.1.user"
]




13./api/tree
树是元数据,用于按类似于典型文件系统的分层结构组织时间序列。 
/树根下的许多端点允许处理各种树相关的数据:


/api/tree/branch


/api/tree/collisions


/api/tree/notmatched


/api/tree/rule


/api/tree/rules


/api/tree/test




详情参考:
http://opentsdb.net/docs/build/html/api_http/tree/index.html


14./api/uid


1./api/uid/assign
该接口允许将UID分配给新的metrics,tag名称 和 tag值。 可以在一次调用中提供多种类型和名称,API将单独处理每个名称,报告哪些名称已成功分配了UID以及分配的UID,哪些由于无效字符或已经分配而失败。 分配可以通过查询字符串或内容数据来执行。


请求方式:
GET
POST
每个请求必须有一个或多个以下字段:
Name Data Type Required Description Default QS RW Example
metric String Optional A list of metric names for assignment metric RW sys.cpu.0
tagk String Optional A list of tag names for assignment tagk RW host
tagv String Optional A list of tag values for assignment tagv RW web01


样例:


http://localhost:4242/api/uid/assign?metric=sys.cpu.0,sys.cpu.1&tagk=host&tagv=web01,web02,web03


参数体:
JOSN形式
{
    "metric": [
        "sys.cpu.0",
        "sys.cpu.1",
        "illegal!character"
    ],
    "tagk": [
        "host"
    ],
    "tagv": [
        "web01",
        "web02",
        "web03"
    ]
}


返回值说明:
返回将包含成功分配的映射以及十六进制编码的UID值。 如果一个或多个值未分配,则单独的地图将包含值的列表以及未分配的原因。 
仅当提供了该类型的一个或多个值时才会生成带有类型名称和<类型> _errors的地图。
    当所有的值都被赋值时,端点返回一个200状态码,但是如果任何赋值失败,它将返回一个400。


    返回值:
    {
    "metric": {},
    "metric_errors": {
        "sys.cpu.0": "Name already exists with UID: 000042",
        "sys.cpu.1": "Name already exists with UID: 000043",
        "illegal!character": "Invalid metric (illegal!character): illegal character: !",
    },
    "tagv": {},
    "tagk_errors": {
        "host": "Name already exists with UID: 0007E5"
    },
    "tagk": {
        "web01": "000012",
        "web02": "000013",
        "web03": "000014"
    }
}


2./api/uid/tsmeta
该接口使得能够搜索,编辑或删除时间序列元数据信息,即与度量标准关联的特定时间序列以及一个或多个tag名称/值对相关联的元数据。 
某些字段由TSD设置,但其他字段可由用户设置。 使用POST方法时,只会存储请求提供的字段。 不包括的现有字段将被单独保留。 如果未提供给定字段,则使用PUT方法将覆盖具有给定值或默认值的所有用户可变字段。


请注意,删除元数据项不会删除为时间序列存储的数据点。 它也不会删除UID分配或关联的UID元对象。


请求类型:
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
GET请求可以查找一个或多个时间序列的TS元对象(如果存在于存储系统中)。 支持两种类型的查询:
tsuid - 可能会提供一个十六进制的TSUID,如果存在,则会返回一个元数据对象。 结果将包括一个单一的对象。
metric - (Version 2.1)与数据点查询类似,您可以提供一个度量标准和一个或多个标记对。 任何匹配查询的TS元数据将被返回。 结果将是一个或多个对象的数组。 每个呼叫只能提供一个指标查询,不支持通配符或分组操作符。


例子:
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


...细节略:
请参考:
http://opentsdb.net/docs/build/html/api_http/uid/tsmeta.html


3./api/uid/uidmeta


该接口允许编辑或删除UID元数据信息,即与指标,tag名称和tag值相关联的元数据。 
某些字段由TSD设置,但其他字段可由用户设置。 使用POST方法时,只会存储请求提供的字段。 不包括的现有字段将被单独保留。 如果未提供给定字段,则使用PUT方法将覆盖具有给定值或默认值的所有用户可变字段。


请求方式:
GET - Query string only
POST - Updates only the fields provided
PUT - Overwrites all user configurable meta data fields
DELETE - Deletes the UID meta data


例子:
GET:
http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric
POST or PUT:
http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric&method=post&display_name=System%20CPU%20Time
参数体:
{
    "uid":"00002A",
    "type":"metric",
    "displayName":"System CPU Time",
    "custom": {
        "owner": "Jane Doe",
        "department": "Operations",
        "assetTag": "12345"
    }
}




DELETE:
http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric&method=delete
参数体:
{
    "uid":"00002A",
    "type":"metric"
}


返回说明:
{
    "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"
}


15./api/version


该接口返回有关OpenTSDB运行版本的信息。


例子:
http://localhost:4242/api/version


返回值:


{
    "timestamp": "1362712695",
    "host": "localhost",
    "repo": "/opt/opentsdb/build",
    "full_revision": "11c5eefd79f0c800b703ebd29c10e7f924c01572",
    "short_revision": "11c5eef",
    "user": "localuser",
    "repo_status": "MODIFIED",
    "version": "2.0.0"
}
展开阅读全文

没有更多推荐了,返回首页