特定のプロジェクトの Logstore でログ分布を照会します。 関連するパラメーターを指定することによって、特定の条件を満たすログの分布を照会することもできます。

ログを Logstore に書き込むとき、Log Service クエリ API (GetHistograms と GetLogs) を使用したログ照会の待ち時間は、ログの種類によって異なります。 Log Service は、ログのタイムスタンプに基づいてログの次の 2 つのタイプに分類されます。

  • リアルタイムデータ:ログの時刻は、サーバー上の現在の時刻 (-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 の場合、ログは履歴データとして処理され、これは通常補足データシナリオに表示されます。

リアルタイムでの書き込みとクエリの間の待ち時間は 3 秒です。

リクエスト構文

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

リクエストパラメーター

パラメータ名 データ型 必須/省略可能 説明
logstorename string 必須 照会するログが属する Logstore の名前
typ string 必須 照会する Logstore データのデータ型。 GetHistograms API のヒストグラムでなければなりません。
from integer 必須 クエリの開始時刻 (1970-1-1 00:00:00 UTCからの秒数)
to integer 必須 このフィールドは、1970-1-1 00:00:00 UTCからの秒数を示します。
topic string 省略可能 照会されるログのトピック
クエリ数 string 省略可能 クエリ表現 クエリ表現構文の詳細については、「クエリ構文」をご参照ください。
リクエストヘッダー

CreateExternalStore API には、特別なリクエストヘッダーはありません。 Log Service API のパブリックリクエストヘッダーについての詳細は、パブリックリクエストヘッダーをご参照ください。

レスポンスヘッダー

GetHistograms API インターフェースには固有のリクエストヘッダーはありません。 Log Service API のパブリックリクエストヘッダーについての詳細は、「パブリックリクエストヘッダー」をご参照ください。

レスポンス要素

リクエストが成功した後、レスポンスボディには、タイムライン上のクエリ条件を満たすログの分布が含まれます。 レスポンス結果は、時間範囲を複数の (1~60) サブインターバルに均等に分割し、各サブインターバルでクエリ条件を満たすログの数を返します。 Log Service は、適時性を保証するために指定された時間内に結果を返さなければなりません。 したがって、各クエリは指定された数のログのみをスキャンできます。 照会されるログの量が多い場合、この API のレスポンス結果は不完全である可能性があります。 特別なレスポンス要素は、返されたリクエストの結果が完了しているかどうかを示すために使用されます。 以下は特別なレスポンス要素形式です。

名前 データ型 説明
progress string クエリ結果のステータス。 2 つのオプション [Imcomplete] と [Complete] は結果が完了したかどうかを示します。
count integer 現在のクエリ結果のログの総数。
histograms array 現在のクエリ分布は部分区間になります。 構造の詳細については、次の表をご参照ください。

ヒストグラム配列の各要素の構造は次のとおりです。

名前 データ型 説明
from integer サブインターバルの開始時刻 (1970-1-1 00:00:00 UTC 以降の秒数)。
to integer サブインターバルの終了時刻 (1970-1-1 00:00:00 UTC 以降の秒数)。
count integer 現在のクエリ結果でこのサブインターバルのクエリ条件を満たすログ数。
progress string このサブインターバルでの現在のクエリ結果が完了しているかどうか。 オプション値:Incomplete と Complete。
詳細説明
  • この API のすべての時間間隔は、リクエストパラメーターの「from」および「to」、または返された結果のサブインターバルによって定義された時間間隔が、左クローズおよび右オープンの原理に従うかどうか、つまり時間間隔に開始時刻は表示されますが、終了時刻は表示されません。 「from」と「to」の値が同じ場合、時間間隔は無効で、関数はエラーを直接返します。
  • この API のレスポンスにおける部分区間分割方法は、一貫性があり不変です。 リクエスト時間間隔が変更されない場合、レスポンスの部分区間は変更されません。
  • この API を呼び出すたびに、指定した時間内に結果が返され、各クエリで指定された数のログのみがスキャンされます。 このリクエストのために処理するログ量が大きい場合、このリクエストから返された結果は不完全です (結果が不完全であろうとなかろうと、返された結果でのプログレスを使って表示されます)。 同時に、Log Service は 15 分以内にクエリ結果をキャッシュします。 クエリリクエスト結果の一部がキャッシュ内のものと同じ場合、Log Service はこのリクエストのキャッシュになりログをスキャンし続けます。 Log Service は、複数のクエリ結果をマージする際の作業負荷を軽減するため、キャッシュ内のクエリ結果とこのクエリで新たにスキャンされた結果をマージして返します。 したがって、Log Service では、同じパラメーターを使用してAPI を複数回呼び出して、最終的な完全な結果を得ることができます。 Log Service API は、 照会するログボリュームが大規模に変更されるため、完全な結果を得る前に API の必要な呼び出し回数を予測することができません。 したがって、各リクエストから返された結果の進捗値を確認して、クエリを続行するかどうかを判断する必要があります。 この API を呼び出すたびに同じ数のクエリ CU が再び消費されることに注意する必要があります。
エラーコード

Log Service API の 一般的なエラーコード のほかに、GetHistograms API は次の特別なエラーコードを返すことがあります。

HTTP ステータスコード エラーコード エラーメッセージ 説明
404 LogStoreNotExist logstore {Name} does not exist. Logstore は存在しません。
400 InvalidTimeRange request time range is invalid. 時間間隔リクエストが無効です。
400 InvalidQueryString query string is invalided リクエストのクエリ文字列が無効です。
上記のエラーメッセージの {name} は特定の Logstore 名に置き換えられます。

杭州リージョンで「big game」と名付けられたプロジェクトを例に説明します。 big game プロジェクトの 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"
        }
    ]
}
このレスポンスの例では、Log Service は 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] の 2 つの時間間隔に分割します。 照会対象のログボリュームが大きいため、最初の照会で返される結果は不完全になります。 レスポンス結果は、3 つのログがクエリ条件を満たしているものの、全体的な結果が不完全であることを示しています。 時間間隔 [2014-09-01 00:00:00, 2014-09-01 11:00:00) の結果のみ、2 つの条件を満たしており完全です。 ただし、他の時間間隔の結果は 1 つのクエリ条件しか満たしておらず不完全です。 この場合、完全な結果を得るには、レスポンスの進捗値が以下のように 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": "Complete",
    "count": 4,
    "histograms": [
        {
            "from": 1509897600,
            "to": 1409569200,
            "count": 1,
            "progress": "Complete",
        },
        {
            "from": 1409569200,
            "to": 1409608800,
            "count": 2,
            "progress": "complete"
        }
    ]
}