/api/histogram

适用于 OpenTSDB 2.4

该端点允许通过 HTTP 在 OpenTSDB 中存储直方图数据，以替代 Telnet 接口。直方图写请求只能通过与 POST 方法关联的内容来执行。通过查询端点执行对直方图数据的查询。

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

尽管该 API 确实支持每个请求多个数据点，但只有在处理完每个 API 后，该 API 才会返回。这意味着必须验证度量标准和标签名称/值，解析值并将数据排队存储。如果您的放置请求具有大量数据点，则 API 可能需要花费很长时间才能响应，尤其是在 OpenTSDB 必须为标记名称或值分配 UID 的情况下。因此，最好限制每个请求的最大数据点数。每个请求 50 美元是一个很好的起点。

另一个建议是在 HTTPClient 端上启用保持活动状态，以便您每次放置数据时都可以重新使用与服务器的连接。

Verbs

• POST

Requests

可以提供一些查询字符串参数，这些参数会更改对放置请求的响应：

Name	Data Type	Required	Description	Default	QS	RW	Example
summary	Present	Optional	是否返回摘要信息	false	summary		/api/put?summary
details	Present	Optional	是否返回详细信息	false	details		/api/put?details
sync	Boolean	Optional	在返回结果之前是否 await 数据刷新到存储。	false	sync		/api/put?sync
sync_timeout	Integer	Optional	超时(以毫秒为单位)，await 数据刷新到存储，然后返回错误。发生超时时，使用details标志将告诉您有多少个数据点失败以及有多少成功。也必须提供sync才能生效。值为 0 表示写入将不会超时。	0	sync_timeout		/api/histogram/?sync&sync_timeout=60000

如果查询字符串中同时包含detailed和summary，则 API 将以detailed信息进行响应。

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

Name	Data Type	Required	Description	Default	QS	RW	Example
metric	String	Required	您要存储的 Metrics 的名称			W	sys.cpu.nice
timestamp	Integer	Required	Unix 时代风格的时间戳，以秒或毫秒为单位。时间戳不得包含非数字字符。			W	1365465600
id	Integer	Optional	在编写默认的简单桶状直方图以外的直方图或草图时，必须将此值设置为tsd.core.histograms.config配置设置中定义的适当直方图编解码器的 ID。该值必须在 0 到 255 之间。如果指定，则必须设置value。			w	1
value	String	Optional	要存储的直方图或草图的基数为 64 的二进制编码数据。 注意 写入二进制数据时还必须提供 ID，以匹配正确的编解码器。			W	AgMIGo=
buckets	Map	Optional	桶下限和上限(用逗号分隔)作为具有整数计数器桶值的键的 Map。详细信息如下。			W	{"0,1.75":12,"1.75,3.5":16}
underflow	Integer	Optional	测量计数低于最低存储桶下限。默认值为零。			W	0
overflow	Integer	Optional	测量计数高于最高存储桶上限。默认值为零。			W	0
tags	Map	Required	标签名称/标签值对的 Map。必须至少提供一对。			W	{"host":"web01"}

Buckets

逗号分隔的存储桶下限(逗号的左侧)和上限(逗号的右侧)。连续存储桶的上限和下限必须重叠。即我们可能有两个存储桶0,1.75=12和1.75,3.5=16。“，” 0,1.75 = 12“。简单直方图也限制为最大100个存储桶。存储桶可能以任何 Sequences 出现。

示例单个数据点写入

您可以在请求中提供一个数据点：

{
    "metric": "sys.cpu.nice",
    "timestamp": 1356998400,
    "overflow": 1,
    "underflow": 0,
    "buckets": {
        "0,1.75": 12,
        "1.75,3.5": 16
    },
    "tags": {
        "host": "web01",
        "dc": "lga"
    }
}

多数据点写入示例

多个数据点必须包含在数组中：

[{
    "metric": "sys.cpu.nice",
    "timestamp": 1346846400,
    "value": "AgMIGoAAAAADAAAAAAAAAAAAAAAAAPA/AAAAAABARUAAAAAAAADwPwAAAAAAADhAAAAAAABARUA=",
    "tags": {
        "host": "web01",
        "dc": "lga"
    },
    "id": 1
}, {
    "metric": "sys.cpu.nice",
    "timestamp": 1346846460,
    "value": "AgMIGoAAAAADAAAAAAAAAAAAAAAAAChAMzMzMzNTVkAAAAAAAAAoQAAAAAAAAC5AMzMzMzNTVkA=",
    "tags": {
        "host": "web01",
        "dc": "lga"
    },
    "id": 1
}, {
    "metric": "sys.cpu.nice",
    "timestamp": 1346846520,
    "value": "AgMIGoAAAAADAAAAAAAAAOxRuB6F6xtAAAAAAACAQEDsUbgehesbQGZmZmZmZjZAAAAAAACAQEA=",
    "tags": {
        "host": "web01",
        "dc": "lga"
    },
    "id": 1
}]

Response

默认情况下，如果所有数据点都已成功存储，则直方图端点将以204 HTTP 状态代码响应，并且不显示任何内容。如果一个或多个数据点有错误，则 API 将返回400，内容中包含错误消息。

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

summary或detailed响应中包含的字段包括：

Name	Data Type	Description
success	Integer	已成功排队存储的数据点数
failed	Integer	不能排队存储的数据点数
errors	Array	失败的数据点列表以及原因。仅出现在details响应中。

带有摘要的示例响应

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

带有详细信息的示例响应

{
    "errors": [{
        "datapoint": {
            "metric": "sys.cpu.nice",
            "timestamp": 1346846460,
            "value": "AgMIGoAAAAADAAAAAAAAAAAAAAAAAChAMzMzMzNTVkAAAAAAAAAoQAAAAAAAAC5AMzMzMzNTVkA=",
            "tags": {
                "host": "web01",
                "dc": "lga"
            },
            "id": 1
        },
        "error": "Unable to find histogram codec for id: 1"
    }],
    "failed": 1,
    "success": 0
}