OpenTSDB的/ API / PUT（opentsdb的输入的api）简介

最新推荐文章于 2025-03-14 17:40:53 发布

jyj019

最新推荐文章于 2025-03-14 17:40:53 发布

阅读量3.5k

点赞数 1

分类专栏： OpenTSDB 文章标签： opentsdb

OpenTSDB 专栏收录该内容

17 篇文章

订阅专栏

写在前面，这里是补充宇毅的博客内容翻译几篇文档，补充下java代码的一些实现，参考文献和其他文章列表放在末尾

翻译原文档http://opentsdb.net/docs/build/html/api_http/put.html

这篇文章讲的OpenTSDB如何存储数据的理论知识，比较简单，但需要在使用前了解。其中有两点比较重要的地方。

第一是存储数据的json格式，4个指标必须都有，并按正确的json格式才能存入数据。

第二是opentsdb使用http api存储使其状态监控比较困难，响应是为数不多相当有效的手段，包括返回的响应信息和错误代码都是很重要的信息。

/ API / PUT

此端点允许通过HTTP在OpenTSDB中存储数据，以替代Telnet接口。Put请求只能通过与POST方法关联的内容执行。内容的格式取决于所选的序列化程序。但是，有一些常见的参数和响应，如下所述。

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

虽然API确实支持每个请求多个数据点，但API在处理完每个数据点之前不会返回。这意味着必须验证度量标准和标记名称/值，解析值并将数据排队等待存储。如果您的put请求包含大量数据点，则API可能需要很长时间才能响应，特别是如果OpenTSDB必须将UID分配给标记名称或值。因此，限制每个请求的最大数据点数是个好主意; 每个请求50个是一个很好的选择。

另一个建议是在HTTP客户端上启用keep-alives，以便每次放入数据时都可以重新使用与服务器的连接。

注意

如果无法解析您提供的请求内容，此类JSON内容缺少引号或大括号，则将丢弃所有数据点。API将返回错误，其中包含有关错误的详细信息。

注意

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

注意

如果tsd.mode设置为ro，则/api/put端点将不可用，并且所有呼叫都将返回404错误。

Requests

可以提供一些查询字符串参数来更改对put请求的响应：

名称	类型	是否必要	描述	默认	QS	示例
summary	Present	否	是否返回摘要信息	false	summary	/api/put?summary
details	Present	否	是否返回详细信息	false	details	/api/put?details
sync	Boolean	否	是否在返回结果之前等待数据刷新到存储。	false	sync	/api/put?sync
sync_timeout	Integer	否	在返回错误之前等待数据刷新到存储的超时（以毫秒为单位）。发生超时时，使用该`details`标志将告知有多少数据点失败以及有多少数据点成功。`sync`还必须为此生效。值为0表示写入不会超时。	0	sync_timeout	/api/put/?sync&sync_timeout=60000

如果查询字符串中都存在detailed和summary，则API将使用detailed信息进行响应。

下面的字段和示例引用了默认的JSON序列化程序。

名称	数据类型	是否必要	描述	读写	示例
metric	String	是	您要存储的指标的名称	W	sys.cpu.nice
timestamp	Integer	是	Unix纪元样式时间戳，以秒或毫秒为单位。时间戳不得包含非数字字符。	W	1365465600
value	Integer, Float, String	是	要记录此数据点的值。它可以引用或不引用，并且必须符合OpenTSDB值规则：../../ user_guide / writing	W	42.5
tags	Map	是	标记名称/标记值对的映射。必须至少提供一对tags。	W	{"host":"web01"}

单点数据写入示例，要求为json格式：

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

多点数据写入示例，要求均为json格式

[
    {
        "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端点将使用204HTTP状态代码进行响应，如果所有数据点都已成功存储，则不会回复内容。如果一个或多个数据点出现错误，API将400在内容中返回一条错误消息。

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

存在summary或detailed回复的字段包括：

名称	数据类型	描述
success	Integer	成功排队等待存储的数据点数
failed	Integer	无法排队等待存储的数据点数
errors	Array	排队失败的数据点列表及其原因。`details`仅在回复中出现。

示例响应摘要

{
    "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
}

响应代码

每个请求都将返回标准的HTTP响应代码。大多数回复都包含信息，尤其是里面错误代码，其中包含正文中有关错误的详细信息。从API返回的成功代码包括：

码	描述
200	请求已成功完成
204	服务器已成功完成请求，但未返回正文中的内容。这主要用于存储数据点，因为不需要将数据返回给调用者
301	这可以在API调用已迁移或应转发到其他服务器的情况下使用

常见的错误响应代码包括：

码	描述
400	API用户通过查询字符串或内容数据提供的信息出错或丢失。这通常包括错误正文中有关导致问题的参数的信息。更正数据，然后重试。
404	找不到请求的端点或文件。这通常与静态文件端点有关。
405	请求的动词或方法不被允许。请参阅您尝试访问的端点的文档
406	请求无法以指定的格式生成响应。例如，如果您要求提供`logs`endpoing 的PNG文件，则会得到406响应，因为日志条目无法转换为PNG图像（很容易）
408	请求已超时。这可能是由于从底层存储系统获取数据的超时或其他问题
413	查询返回的结果可能太大，无法处理服务器的缓冲区。如果您从OpenTSDB请求大量原始数据，就会发生这种情况。在这种情况下，将查询分解为较小的查询并单独运行
500	OpenTSDB中发生内部错误。确保OpenTSDB所依赖的所有系统都可访问，并检查错误列表中的问题
501	请求的功能尚未实现。格式化程序或调用依赖于插件的方法时可能会出现这种情况
503	发生了临时过载。检查与OpenTSDB交互的其他用户/应用程序，并确定是否需要减少请求或扩展系统。

错误

如果发生错误，API将返回一个响应，其中包含按请求的响应类型格式化的错误对象。错误对象字段包括：

字段名称	数据类型	是否永远存在	描述	例
code	Integer	Yes	HTTP状态代码	400
message	String	Yes	关于出错的描述性错误消息	Missing required parameter
details	String	Optional	有关错误的详细信息，通常是堆栈跟踪	Missing value: type
trace	String	Optional	JAVA堆栈跟踪，描述生成错误的位置。可以通过`tsd.http.show_stack_trace`配置选项禁用此功能。TSD的默认设置是显示堆栈跟踪。

所有错误都将返回有效的HTTP状态错误代码和包含错误详细信息的内容正文。默认格式化程序将错误消息作为JSON返回application/json内容类型。如果请求了不同的格式化程序，则输出可能不同。

示例错误结果

{
    "error": {
        "code": 400,
        "message": "Missing parameter <code>type</code>",
        "trace": "net.opentsdb.tsd.BadRequestException: Missing parameter <code>type</code>\r\n\tat net.opentsdb.tsd.BadRequestException.missingParameter(BadRequestException.java:78) ~[bin/:na]\r\n\tat net.opentsdb.tsd.HttpQuery.getRequiredQueryStringParam(HttpQuery.java:250) ~[bin/:na]\r\n\tat net.opentsdb.tsd.SuggestRpc.execute(SuggestRpc.java:63) ~[bin/:na]\r\n\tat net.opentsdb.tsd.RpcHandler.handleHttpQuery(RpcHandler.java:172) [bin/:na]\r\n\tat net.opentsdb.tsd.RpcHandler.messageReceived(RpcHandler.java:120) [bin/:na]\r\n\tat org.jboss.netty.channel.SimpleChannelUpstreamHandler.handleUpstream(SimpleChannelUpstreamHandler.java:75) [netty-3.5.9.Final.jar:na]\r\n\tat org.jboss.netty.channel.DefaultChannelPipeline.sendUpstream(DefaultChannelPipeline.java:565) [netty-3.5.9.Final.jar:na]
        ....\r\n\tat java.lang.Thread.run(Unknown Source) [na:1.6.0_26]\r\n"
    }
}

参考文档：

中文博客，介绍了存储的其他形式https://blog.youkuaiyun.com/xsdxs/article/details/53882504

OpenTSDB系列

OpenTSDB的/ API / PUT（opentsdb的输入的api）简介https://blog.youkuaiyun.com/jyj1100/article/details/81323705

OpenTSDB使用/ API / PUT进行数据存储的java实现https://blog.youkuaiyun.com/jyj1100/article/details/81330623

（转）opentsdb查询的简介——基础知识和UI操作https://blog.youkuaiyun.com/jyj1100/article/details/81324017

OpenTSDB的/ API / query（opentsdb的查询的api）简介（一）https://blog.youkuaiyun.com/jyj1100/article/details/81326660

OpenTSDB的/ API / query（opentsdb的查询的api）简介（二）https://blog.youkuaiyun.com/jyj1100/article/details/81329290

OpenTSDB使用/ API / query进行数据查询的java实现https://blog.youkuaiyun.com/jyj1100/article/details/81347817

其他OpenTSDB系列文章见

OpenTSDB系列目录https://blog.youkuaiyun.com/jyj1100/article/details/83450282