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

从日志写入日志库到查询接口(GetHistograms 和 GetLogs)查到该日志,延时时长因写入日志类型不同而异。日志服务按日志时间戳把日志分为如下两类:

  • 实时数据:日志中时间点为服务器当前时间点( -180秒,900秒]。例如,日志时间为 UTC 2014-09-25 12:03:00,服务器收到时为 UTC 2014-09-25 12:05:00,则该日志被视作实时数据处理。实时数据从写入到在日志查询界面查询到该数据的延迟为3秒。
  • 历史数据:日志中时间点为服务器当前时间点 [-7 x 86400秒,-180秒)。例如,日志时间为 UTC 2014-09-25 12:00:00,服务器收到时为 UTC 2014-09-25 12:05:00,则该日志被作为历史数据处理,一般出现在补数据场景下。

请求语法

GetHistograms 接口请求语法如下。
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 接口无特有请求头。关于 Log Service API 的公共请求头,请参见 公共请求头

  • 请求参数
    名称 类型 必选 描述
    logstorename string 需要查询日志的 Logstore 名称。
    type string 查询 Logstore 数据的类型,在 GetHistograms 接口中该参数必须为 histogram。
    from int 查询开始时间点。精度为秒,从 1970-1-1 00:00:00 UTC 计算起的秒数。
    to int 查询结束时间点。精度为秒,从 1970-1-1 00:00:00 UTC 计算起的秒数。
    topic string 查询日志主题。
    query string 查询表达式。关于查询表达式的详细语法,请参见查询语法

响应元素

  • 响应头

    GetHistograms 接口无特有响应头。关于 Log Service API 的公共响应头,请参见 公共响应头

  • 响应参数
    GetHistograms 请求成功,其响应 Body 会包括查询命中的日志数量在时间轴上的分布情况。响应结果会把您查询的时间范围均匀分割成若干个子时间区间,并返回每个子时间区间内命中的日志条数。具体响应元素格式如下:
    名称 类型 描述
    progress string 查询结果的状态。可以有 Incomplete 和 Complete 两个选值,表示结果是否完整。
    count int 当前查询结果中所有日志总数。
    histograms array 当前查询结果在划分的子时间区间上的分布状况,具体结构见下面的描述。
    上表中的 histograms 数组中的每个元素结构如下:
    名称 类型 描述
    from int 子时间区间的开始时间点。精度为秒,从 1970-1-1 00:00:00 UTC 计算起的秒数。
    to int 子时间区间的结束时间点。精度为秒,从 1970-1-1 00:00:00 UTC 计算起的秒数。
    count int 当前查询结果在该子时间区间内命中的日志条数。
    progress int 当前查询结果在该子时间区间内的结果是否完整,可以有 Incomplete 和 Complete 两个选值。

细节描述

  • 该接口中涉及的时间区间(无论是请求参数 from 和 to 定义的时间区间,还是返回结果中各个子时间区间)都遵循“左闭右开”原则,即该时间区间包括区间开始时间点,但不包括区间结束时间点。如果 from 和 to 的值相同,则为无效区间,函数直接返回错误。
  • 该接口的响应中子区间划分方式是一致稳定的。如果您在请求查询的时间区间不变,则响应中子区间划分结果也不会改变。
  • 当查询涉及的日志数量变化非常大时,日志服务API无法预测需要调用多少次该接口来获取完整结果。所以需要您查看每次请求返回结果中的 x-log-progress 成员状态值,根据成员状态值来确定是否需要重复调用该接口来获取最终完整结果。需要注意的是,每次重复调用该接口都会重新消耗相同数量的查询 CU。

错误码

除了返回 Log Service API 的 通用错误码,还可能返回如下特有错误码:
HTTP 状态码(Status Code) 错误码(Error Code) 错误消息(Error Message) 描述(Description)
404 LogStoreNotExist logstore {Name} does not exist 日志库(logstore)不存在。
400 InvalidTimeRange request time range is invalid 请求的时间区间无效。
400 InvalidQueryString query string is invalided 请求的查询字符串无效。
说明 上表错误消息中 {name} 表示该部分会被具体的 LogstoreName 替换。

示例

以杭州地域内名为 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: LOG <yourAccessKeyId>:<yourSignature>
    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
    [
            {
                "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
[
        {
            "from": 1409529600,
            "to": 1409569200,
            "count": 2,
            "progress": "Complete"
        },
        {
            "from": 1409569200,
            "to": 1409608800,
            "count": 2,
            "progress": "complete"
        }
]