/api/put

该端点允许通过 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/put端点将不可用,并且所有调用都将返回 404 错误。

Verbs

  • POST

Requests

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

NameData TypeRequiredDescriptionDefaultQSRWExample
summaryPresentOptional是否返回摘要信息falsesummary /api/put?summary
detailsPresentOptional是否返回详细信息falsedetails /api/put?details
syncBooleanOptional在返回结果之前是否 await 数据刷新到存储。falsesync /api/put?sync
sync_timeoutIntegerOptional超时(以毫秒为单位),await 数据刷新到存储,然后返回错误。发生超时时,使用details标志将告诉您有多少个数据点失败以及有多少成功。也必须提供sync才能生效。值为 0 表示写入将不会超时。0sync_timeout /api/put/?sync&sync_timeout=60000

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

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

NameData TypeRequiredDescriptionDefaultQSRWExample
metricStringRequired您要存储的 Metrics 的名称 Wsys.cpu.nice
timestampIntegerRequiredUnix 时代风格的时间戳,以秒或毫秒为单位。时间戳不得包含非数字字符。 W1365465600
value整数,浮点数,字符串Required要为此数据点记录的值。它可以带引号或不带引号,并且必须符合 OpenTSDB 值规则:../../user_guide/writing W42.5
tagsMapRequired标签名称/标签值对的 Map。必须至少提供一对。 W{"host":"web01"}

示例单个数据点放置

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

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

Response

默认情况下,如果所有数据点都已成功存储,则 put 终结点将使用204 HTTP 状态代码进行响应,并且不显示任何内容。如果一个或多个数据点有错误,则 API 将返回400,内容中包含错误消息。

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

summarydetailed响应中包含的字段包括:

NameData TypeDescription
successInteger已成功排队存储的数据点数
failedInteger不能排队存储的数据点数
errorsArray失败的数据点列表以及原因。仅出现在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
}