1004      阿裏雲

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_日誌服務-阿裏雲