Docs4dev
Docs
opentsdb / 2.3 / reference / api_http-histogram.html

/api/histogram

适用于 OpenTSDB 2.4

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

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

Note

如果无法解析为请求提供的内容，例如缺少引号或花括号的 JSON 内容，则所有数据点都将被丢弃。 API 将返回错误，并提供有关错误原因的详细信息。

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

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

Note

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

Note

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

Warning

2.4 中实现的直方图在查询时不支持导数计算(例如费率)。编写直方图时，它们应该以固定的间隔来自每个来源，并且必须仅反映该特定间隔的测量值。例如。如果源要每 5 分钟报告一次延迟直方图，则源应每 5 分钟创建一个新的直方图对象，将其填充测量值，将其写入 TSDB，并在接下来的 5 分钟间隔内创建一个新的空直方图。

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

Note

必须设置id和value字段，或者必须设置buckets的值。如果同时设置了value和buckets，则value优先，并且桶将被忽略。

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
}