1004      微软  windows

GetHistograms__日志库相关接口_API-Reference_日志服务-阿里云

GetHistograms接口查询指定Project下某个Logstore中日志的分布情况。还可以通过指定相关参数仅查询符合指定条件的日志分布情况。

当日志写入到Logstore中，日志服务的查询接口（GetHistograms和GetLogs）能够查到该日志的延时因写入日志类型不同而异。日志服务按日志时间戳把日志分为如下两类：

• 实时数据：日志中时间点为服务器当前时间点(-180秒，900秒]，例如日志时间为UTC 2014-09-25 12:03:00，服务器收到时UTC 2014-09-25 12:05:00，则该日志被作为实时数据处理，一般出现在正常场景下。
• 历史数据：日志中时间点为服务器当前时间点[-7 x 86400秒, -180秒)，例如日志时间为UTC 2014-09-25 12:00:00，服务器收到时UTC 2014-09-25 12:05:00，则该日志被作为历史数据处理，一般出现在补数据场景下。

其中实时数据写入至可查询的延时为1分钟。

请求语法

GET /logstores/<logstorename>?type=histogram&topic=<logtopic>&from=<starttime>&to=<endtime>&query=<querystring> HTTP/1.1
Authorization: <AuthorizationString>
Date: <GMT Date>
Host: <Project Endpoint>
x-log-bodyrawsize: 0
x-log-apiversion: 0.6.0
x-log-signaturemethod: hmac-sha1

请求参数

请求头

GetHistograms接口无特有请求头，关于日志服务API的公共请求头请参考公共请求头。

响应头

GetHistograms接口无特有响应头，关于日志服务API的公共响应头请参考公共响应头。

响应元素

GetHistograms请求成功，其响应Body会包括查询命中的日志数量在时间轴上的分布情况。响应结果会把用户查询的时间范围进行均匀分割成若干个（1到60个不等）子时间区间，并返回每个子时间区间内命中的日志条数。由于日志服务需要在限定时间内返回结果以保证实时性，每次查询只能扫描指定条数的日志量。当需要查询日志数据量非常大时，该接口的响应结果可能并不完整。所以响应元素中有专门成员表示请求返回结果是否完整。具体响应元素格式如下：

上表中的histograms数组中的每个元素结构如下：

细节描述

• 该接口中涉及的时间区间（无论是请求参数from和to定义的时间区间，还是返回结果中各个子时间区间）都遵循“左闭右开”原则，即该时间区间包括区间开始时间点，但不包括区间结束时间点。如果from和to的值相同，则为无效区间，函数直接返回错误。
• 该接口的响应中子区间划分方式是一致稳定的。如果用户在请求查询的时间区间不变，则响应中子区间划分结果也不会改变。
• 如上所述，该接口一次调用必须要在限定时间内返回结果，每次查询只能扫描指定条数的日志量。如果一次请求需要处理的数据量非常大的时候，该请求会返回不完整的结果（并在返回结果中的progress成员标示是否完整）。如此同时，服务端会缓存15分钟内的查询结果。当查询请求的结果有部分被缓存命中，则服务端会在这次请求中继续扫描未被缓存命中的日志数据。为了减少用户合并多次查询结果的工作量，服务端会把缓存命中的查询结果与本次查询新命中的结果合并返回给用户。因此日志服务可以让用户通过以相同参数反复调用该接口来获取最终完整结果。因为用户查询涉及的日志数据量变化非常大，日志服务API无法预测需要调用多少次该接口而获取完整结果。所以需要用户通过检查每次请求的返回结果中progress成员状态值来确定是否需要继续。需要注意的是，每次重复调用该接口都会重新消耗相同数量的查询CU。

特有错误码

GetHistograms接口除了可能返回日志服务API的通用错误码，还可能返回如下特有错误码：

上表错误消息中{name}表示该部分会被具体的Logstore Name来替换。

示例

以杭州Region内名为big-game的Project为例，查询该Project内名为app_log的Logstore中，主题为groupA的日志分布情况。查询区间为2014-09-01 00:00:00到2014-09-01 22:00:00，查询关键字是"error"。

请求示例：

GET /logstores/app_log?type=histogram&topic=groupA&from=1409529600&to=1409608800&query=error HTTP/1.1
Authorization: <AuthorizationString>
Date: Wed, 3 Sept. 2014 08:33:46 GMT
Host: big-game.cn-hangzhou.log.aliyuncs.com
x-log-bodyrawsize: 0
x-log-apiversion: 0.6.0
x-log-signaturemethod: hmac-sha1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json
Content-MD5: E6AD9C21204868C2DE84EE3808AAA8C8
Content-Type: application/json
Date: Wed, 3 Sept. 2014 08:33:47 GMT
Content-Length: 232
x-log-requestid: efag01234-12341-15432f

{
    "progress": "Incomplete",
    "count": 3,
    "histograms": [
        {
            "from": 1409529600,
            "to": 1409569200,
            "count": 2,
            "progress": "Complete"
        },
        {
            "from": 1409569200,
            "to": 1409608800,
            "count": 1,
            "progress": "Incomplete"
        }
    ]
}

在这个响应示例中，服务端把整个Histogram划分到两个均等的时间区间，分别为[2014-09-01 00:00:00, 2014-09-01 11:00:00）和[2014-09-01 11:00:00, 2014-09-01 22:00:00）。由于用户数据量过大，第一次查询会返回不完整数据。响应结果告知用户命中日志条数为3，但整体结果不完整，仅在时间段[2014-09-01 00:00:00 2014-09-01 11:00:00）结果完整且命中2条，而在另外一个时间段结果不完整但已经命中1条。在这个情况下，如果用户希望得到完整结果，则需要重复调用上面的请求示例若干次直到整个响应中的"progress”成员值变成“Complete”（例如下响应）：

HTTP/1.1 200 OK
Content-Type: application/json
Content-MD5: E6AD9C21204868C2DE84EE3808AAA8C8
Content-Type: application/json
Date: Wed, 3 Sept. 2014 08:33:48 GMT
Content-Length: 232
x-log-requestid: afag01322-1e241-25432e

{
    "progress": "Incomplete",
    "count": 4,
    "histograms": [
        {
            "from": 1409529600,
            "to": 1409569200,
            "count": 2,
            "progress": "Complete"
        },
        {
            "from": 1409569200,
            "to": 1409608800,
            "count": 2,
            "progress": "complete"
        }
    ]
}

最后更新：2016-11-23 16:04:02

  上一篇： GetLogs__日志库相关接口_API-Reference_日志服务-阿里云

  下一篇： CreateMachineGroup__Logtail机器组相关接口_API-Reference_日志服务-阿里云